mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 19:14:26 +00:00
8.7 KiB
8.7 KiB
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_uvandfrom_datacheck the size againstLimits(longest side, pixel count, bytes) before allocating and return anImageError.from_dataalso checks that the buffer holds width × height × channels floats.filled,generate,generate_uvandgrayclamp each side to1..=MAX_SIDE(8192). A plane is never larger thanisize::MAXbytes (2 GiB minus one byte onwasm32), even with raised limits: thetry_forms returnImageError::TooLargefor a larger one, andmap,to_colorandto_kindclamp each side to1..=MAX_SIDEand map the top-left part instead.try_map,try_to_kind,try_resizeandtry_to_rgba8_displayreserve their pixel buffer first and returnImageError::OutOfMemorywhen that reservation fails. They still make small allocations that are not fallible: theArcaround a new image's buffer, and the boxed resampler oftry_resize. The forms withouttry_allocate likeVec. A failed infallible allocation ends the process. - Sampling.
sample(bilinear) andsample_nearesttake normalized(u, v)with(0, 0)at the upper-left corner andvincreasing downward, as glTF 2.0 section 3.8.3 defines them (https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html).tilepicks repeat (glTFREPEAT) 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 inf64and clamped to thef32range, so finite texels give a finite sample.sample_axes,sample_nearest_axesandget_axestaketiling: [bool; 2], the wrap mode ofuand ofvon their own, as glTF'swrapSandwrapT; with equal entries they give the same results as the forms with onetile. - Stored sampling.
sample_storedis the texture read of MaterialCraft's function graphs. It rounds the bilinear weights to multiples of 1/256 and blends the texels by linear interpolation inf32. When the image's integer-sampling flag is on (with_integer_sampling(true), read withinteger_sampling()), it then clamps each channel to0..=1and rounds it to a multiple of 1/65535. A channel whose interpolation is not finite is taken from thef64weighted sum instead, so finite texels give a finite sample. New images start with the flag off, clones keep it, and two images are equal only when their flags are equal. - Other operations.
getreads one texel,map,to_gray,to_colorandto_kindconvert,resizebox-averages whole-factor shrinks and samples bilinearly otherwise, andto_rgba8_displayencodes 8-bit sRGB RGBA.linear_to_srgb,srgb_to_linearandluminance(Rec. 709) are scalar helpers.resource_keyandsplit_resource_keytag a bitmap name with its color space. - Height to normal and ORM packing. Both read a
ScalarSource: a plane of linear scalar samples that gives its size and one row at a time, so an adapter can decode a tiled or encoded surface in place. Besides the output, each worker keeps at most three rows for the normal map and one row for each given plane for ORM packing, never a fullf32copy of the input. Both check the output size againstLimitsbefore reading. AnImageis aScalarSourceof its gray value, or its Rec. 709 luminance for a color image.normal::try_height_to_normalreturns an RGBA tangent-space normal map. It takes the 3×3 Sobel gradient of the height, scales it bystrengthand normalizes(-gx × s, gy × s, 1), then stores0.5 × n + 0.5with alpha 1, as glTF 2.0 encodes normal textures. OpenGL normals have green up the image;NormalConvention::DirectXnegates green. Neighbors clamp to the image, or withBoundaryMode::ClampToBlockto theblock × blockUV tile of the center sample. A neighbor thatScalarSource::coveredreports as not covered takes the center height.HeightNormalOptions::uv_tiles(height_strength, tile_res, block_scale)gives the strengthheight_strength × tile_res × block_scale / 16and clamps to UV tiles oftile_res. A strength of 0 gives flat normals[0.5, 0.5, 1].packing::try_pack_ormreturns RGBA[occlusion, roughness, metallic, 1], the channels glTF 2.0 reads occlusion from (red) and metallic-roughness from (green and blue). A plane that is not given takes 1, 0.5 or 0.occlusion_multipliermultiplies a second occlusion plane, such as baked occlusion, into red. Every plane must have the same size, andsizegives it when no plane is given.- Values are linear data with no transfer curve. A NaN or infinite strength, sample or block
scale, a block of 0, an occlusion product that overflows
f32, mismatched sizes and a failed row read return aTextureOpError.
Mirrored repeat, mip chains, decoding and texture-set recognition are not in the crate yet.
Cargo features
No default features.
| Feature | Provides | Pulls in |
|---|---|---|
parallel |
generated images, display conversion, height to normal and ORM packing 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, from_data, try_height_to_normal and try_pack_orm |
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 |
get_axes, sample_axes, sample_nearest_axes, sample_stored and the integer-sampling flag |
MaterialCraft crates/image/src/lib.rs at 6c3b35c, on this crate's coordinate reduction and f64 bilinear sum |
Limits, the try_ constructors, from_data, private fields with getters, the parallel feature, with_integer_sampling and integer_sampling |
written here |
The Sobel normal, its strength scale, UV-tile clamp and uncovered-neighbor rule, the ORM channels and defaults, and the tests gltf_png_matches_the_composite, directx_flips_green, height_becomes_normal_detail, ao_mixes_baked_and_channel, converted_maps_invert_and_derive_normals and uv_tiles_export_one_file_per_tile_without_padding_across, with assertions on the new functions |
TextureCraft crates/formats/src/export/mod.rs, presets.rs and tests.rs and crates/core/src/channel.rs at b89badc |
ScalarSource, row-at-a-time reading, the limit and non-finite checks, and the tiled-input tests |
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. |
| TextureCraft | Its export's height normal and ORM packing are the source of normal and packing. The app switches to them in its own pull request. |
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()) |
image.integer_sampling = on and Image { integer_sampling, .. } |
image.with_integer_sampling(on); read it with integer_sampling() |
sample_axes blends with a + (b − a)t in f32 |
it sums the weighted texels in f64, as sample does; the results differ by rounding |
rayon always on |
the parallel feature |
linear_to_srgb(NaN) returned −0.055 |
it returns NaN |