Module texture 

Textures of 3D models: the pictures a model’s materials map onto its surfaces, decoded to RGBA within a memory bound, and how the viewer and the thumbnail renderer sample them.

A reader asks a Loader for each picture, by the name the file gives (a sidecar file) or with its bytes (embedded in the model). Names are looked up only next to the model or in a folder below it: a relative path that stays inside the model’s folder is tried as written, and any name (absolute, climbing out with .., or relative) is also tried as its file name alone, next to the model. Nothing outside the folder is ever read. A picture that is missing or can’t be decoded gives None and the mesh keeps its material colour.

Memory: each picture is decoded to at most MAX_SIDE pixels on its longer side (larger ones are scaled down, by ImageIO while decoding on macOS), and one model’s pictures together take at most BUDGET bytes of RGBA; a picture that doesn’t fit what is left is halved until it does. The same file or the same embedded bytes are decoded once. Normal, bump and emissive maps count too, but each may take only half of what is left (Loader::for_map), so they can’t starve the pictures of the materials read after them.

Textures always repeat, whatever wrap mode the file names: Eagle’s viewer tiles every texture, so falcon’s readers ignore the wrap modes of glTF samplers, COLLADA samplers, FBX textures, OBJ -clamp and 3DS map flags, and the viewer’s GPU sampler repeats too.

Texture coordinates are kept in picture space: u to the right and v downwards, (0, 0) the top left corner. Readers of formats that count v upwards (OBJ, FBX, COLLADA, 3DS) flip it.

Structs

Image

A decoded picture: straight-alpha RGBA8 in its file’s own (sRGB) values, rows top to bottom.

Loader

Decodes one model’s textures: looks pictures up next to the model, keeps the decoded total within BUDGET and decodes each file or embedded picture once.

Texture

A material’s texture: the picture and how it is laid on.

Constants

BUDGET

Bytes of RGBA one model’s textures may take together (64 MB).

MAX_SIDE

Longest side a texture is decoded to.

Functions

candidates

Where a texture named path in a model file may be read, relative to the model’s folder, in the order to try: the path as written when it is relative and stays inside the folder, then its file name alone. Backslashes count as separators and a file:// prefix is dropped.

decode

Decodes a picture file’s bytes to RGBA within max_side and max_bytes (see fit_size). Formats the image crate reads (PNG, JPEG, TGA, BMP, TIFF, DDS, …) go through it; anything else, and pictures to be scaled down, through ImageIO on macOS.

fit_size

The size a w x h picture is decoded at: at most max_side on its longer side, then halved until it takes no more than max_bytes of RGBA. None when not even one pixel fits.

linear_to_srgb

mip_chain

The smaller levels of img’s mipmap chain, each half the one before (at least one pixel), down to 1 x 1: alpha-weighted 2 x 2 averages in linear light, in sRGB values like the picture. The viewer uploads them under the full picture.

mip_chain_data

mip_chain for a map holding data: plain 2 x 2 averages of the stored values, alpha included and with no weight.

modulate

color (display values) times the texel rgb (display values), multiplied in linear light: the textured base colour the viewer’s shader computes the same way.

srgb_to_linear

wrap_coord

A texture coordinate brought into 0..1 by repeating the picture.

Type Aliases

Side

Fetches a file next to the model by relative name.