Files
craft-libs/crates/texture/README.md
T
dotCooCoo 316db97052 craft-texture: keep bilinear samples of finite texels finite
The four weighted texels are summed in f64 and a finite sum is clamped
to the f32 range. Rounded weights can add up to slightly more than 1,
which made a constant image of f32::MAX sample to infinity at some
coordinates. Infinite texels still give an infinite or NaN sample.

The crate docs and README now limit the OutOfMemory guarantee of the
try_ forms to the pixel buffer, and name the Arc and the try_resize
resampler as allocations that are not fallible.
2026-11-13 19:52:40 -08:00

78 lines
4.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# craft-texture
Linear float image planes and texture sampling. An `Image` is a gray (1 channel) or RGBA plane of
`f32`, row-major with the top row first, shared copy-on-write through an `Arc`. Values are stored
as given, so HDR values above 1 and negative values are kept. The crate has no UI, does no file or
network I/O and has no `unsafe` code.
- **Construction.** `try_filled`, `try_generate`, `try_generate_uv` and `from_data` check the size
against `Limits` (longest side, pixel count, bytes) before allocating and return an
`ImageError`. `from_data` also checks that the buffer holds width × height × channels floats.
`filled`, `generate`, `generate_uv` and `gray` clamp each side to `1..=MAX_SIDE` (8192).
A plane is never larger than `isize::MAX` bytes (2 GiB minus one byte on `wasm32`), even with
raised limits: the `try_` forms return `ImageError::TooLarge` for a larger one, and `map`,
`to_color` and `to_kind` clamp each side to `1..=MAX_SIDE` and map the top-left part instead.
`try_map`, `try_to_kind`, `try_resize` and `try_to_rgba8_display` reserve their pixel buffer
first and return `ImageError::OutOfMemory` when that reservation fails. They still make small
allocations that are not fallible: the `Arc` around a new image's buffer, and the boxed
resampler of `try_resize`. The forms without `try_` allocate like `Vec`. A failed infallible
allocation ends the process.
- **Sampling.** `sample` (bilinear) and `sample_nearest` take normalized `(u, v)` with `(0, 0)` at
the upper-left corner and `v` increasing downward, as glTF 2.0 section 3.8.3 defines them
(<https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html>). `tile` picks repeat (glTF
`REPEAT`) or clamp to edge (`CLAMP_TO_EDGE`) for both axes. The texel coordinate, the wrapping
and the bilinear weights follow the Vulkan specification, sections 20.4.1, 20.6.1 and 20.6.3
(<https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#textures-texel-filtering>).
Repeat keeps its period at any finite coordinate. A NaN or infinite coordinate gives
`[0, 0, 0, 1]`. Bilinear sums are taken in `f64` and clamped to the `f32` range, so finite
texels give a finite sample.
- **Other operations.** `get` reads one texel, `map`, `to_gray`, `to_color` and `to_kind` convert,
`resize` box-averages whole-factor shrinks and samples bilinearly otherwise, and
`to_rgba8_display` encodes 8-bit sRGB RGBA. `linear_to_srgb`, `srgb_to_linear` and `luminance`
(Rec. 709) are scalar helpers. `resource_key` and `split_resource_key` tag a bitmap name with
its color space.
Mirrored repeat, mip chains, height to normal, channel packing, decoding and texture-set
recognition are not in the crate yet.
## Cargo features
No default features.
| Feature | Provides | Pulls in |
|---|---|---|
| `parallel` | generated images and display conversion fill rows on several threads; the results are the same | `rayon` |
Without `parallel` the crate builds for `wasm32-unknown-unknown`.
## Limits
| Field | Default | Checked by |
|---|---|---|
| `max_side` | 8192 | every `try_` constructor and `from_data` |
| `max_pixels` | 2^26 (8192 × 8192) | the same |
| `max_bytes` | 1 GiB (an 8192 × 8192 RGBA plane) | the same |
## Origin
| Part | Source |
|---|---|
| `Image`, `Kind`, sampling, resizing, conversions, sRGB helpers, resource keys and the six tests `sample_survives_huge_coordinates`, `resource_keys_round_trip`, `sample_wraps_and_clamps`, `resize_box_and_bilinear`, `hostile_sizes_are_clamped`, `conversions` | MaterialCraft `crates/image/src/lib.rs` at [3133062](https://github.com/storytold/materialcraft/commit/3133062968b8a1566eda12a357cb06062db16687) |
| `Limits`, the `try_` constructors, `from_data`, private fields with getters, the `parallel` feature | written here |
## Migration
| App | Status |
|---|---|
| MaterialCraft | `materialcraft-image` is the source. The app switches to this crate in its own pull request. |
| EffectCraft | Its texture sampling moves into this crate later, with mirrored repeat. |
For MaterialCraft:
| `materialcraft-image` | craft-texture |
| --- | --- |
| `image.w`, `image.h`, `image.kind`, `image.data` | `width()`, `height()`, `kind()`, `data()` and `shared_data()` |
| `Image { w, h, kind, data }` built by hand | `Image::from_data(w, h, kind, data, &Limits::default())` |
| `rayon` always on | the `parallel` feature |
| `linear_to_srgb(NaN)` returned −0.055 | it returns NaN |