Add source color primaries metadata to image assets

[stuartparmenter]

Objective

An image asset does not record the gamut its colors came from. Once the working color space widens, every existing texture shifts saturation, and nothing can tell which textures were already wide-gamut.

Solution

• Adds the Image::source_primaries field and SourceColorPrimaries, a closed set of Bt709, Bt2020 and DisplayP3.
• Reads the gamut from file metadata: the KTX2 data format descriptor's colorPrimaries, the PNG cICP chunk, Radiance PRIMARIES= header lines, and the OpenEXR chromaticities attribute.
• Stamps glTF textures Bt709. The glTF 2.0 spec mandates it, and KHR_texture_basisu requires the same from KTX2 files.
• Adds a source_primaries loader setting to override it per asset, in code or in a .meta file. Order is setting, then file metadata, then Bt709. The setting also flows through Image::from_buffer, so an override skips the file read and its warnings in every format.
• Warns once when file metadata disagrees with the load, meaning unsupported primaries, a PQ or HLG transfer function, or a KTX2 transfer that contradicts is_srgb. Each warning names the fix, either a loader setting or re-encoding the file.
• Fills in the field at the exhaustive Image { .. } literals in the repo.

This is metadata only. Nothing reads the field yet, so decoding and rendering are unchanged. The future working color space PR (from the HDR series) carries the value into GpuImage, and a follow-up will use it to convert wide-gamut textures instead of assuming every texture is Rec. 709.

Design notes

SourceColorPrimaries is a closed set of named gamuts, not a second copy of bevy_color::RgbPrimaries. The renderer needs a discrete label it can hash, compare, and match on, for example in pipeline keys, and the loader settings need stable names in .meta files. RgbPrimaries cannot provide either, since it is a struct of chromaticity floats. It stays the colorimetric data you convert through, and to_rgb_primaries bridges the two.

There is no Unspecified variant. A file that declares nothing is treated as sRGB. That is what most tools assume, and it matches how is_srgb already works on Image.

The metadata reads never repeat the pixel decode. The EXR read parses only the header, and the PNG read stops at the first image-data chunk and skips ICC profiles, so the extra cost stays proportional to the header, not the file.

Testing

• Tests pass across bevy_image and bevy_gltf, including new ones for PNG cICP parsing and the loader-setting override.
• cargo check -p bevy with png, ktx2, hdr, exr, gltf and serialize, and the mipmap_generator workspace member compiles.
• cargo check -p bevy_image with the ctt and basis-universal saver features, combined and universal-only.
• cargo clippy and cargo fmt --check.

Migration

Image gains a field and has a manual Default, so exhaustive Image { .. } literals need it. Image::from_buffer and ktx2_buffer_to_image gain a trailing source_primaries: Option<SourceColorPrimaries> parameter. It only sets the stamped metadata, and with None the file's own metadata wins. See _release-content/migration-guides/image_source_color_primaries.md.

---

This PR was built by me with the assistance of Claude Code w/ Fable 5

[JMS55]

Technically sound, but docs need some work.

Also, I think we should talk to the image-rs people about trying to get this upstreamed, seems like code that would be better off living with them long term.

[JMS55]

Really feels like we should try to upstream this stuff into the image crate...

[stuartparmenter]

I agree, I can file an upstream issue and look at it, but don't want to block

[JMS55]

Can you write some documentation explaining in simple terms what color primaries are, and then link to the wikipedia page or another resource explaining it in more detail? We shouldn't assume people looking at this type have any idea what a color primary or white point is is :)

[stuartparmenter]

would it be OK to link to the recently added

bevy/crates/bevy_color/src/primaries.rs

Line 98 in 17e28cd

impl RgbPrimaries {

which covers most of it, rather than duplicate?

[JMS55]

Oh hmm. Yeah it would be, but why can't we use that directly?

[stuartparmenter]

The renderer needs a discrete label it can hash/compare/match on, for example in pipeline keys, and the loader settings need stable names in .meta files, which is what SourceColorPrimaries is -- RgbPrimaries is a struct of chromaticity floats focused on colormetric data. Not sure it makes sense to force one in to the other

[JMS55]

Why do we need a tolerance?

[stuartparmenter]

I rewrote the comment to explain it more or less in these terms:

Basically its a helper for EXR and Radiance HDR files -- other files have basically enums.

A Radiance HDR file can carry a header line like this:
PRIMARIES= 0.640 0.330 0.300 0.600 0.150 0.060 0.3127 0.3290

Those eight numbers pin down which exact red, green, blue, and white the file's RGB values are mixing between -- two numbers per color, locating it on a standard color chart. EXR files can carry the same eight numbers in a chromaticities attribute. Each of the three sets we support (BT.709, BT.2020, Display P3) is defined by its own well known eight numbers, so identifying the file's set is just asking: whose numbers does this line match?

The catch is that these are decimals written by whatever program made the file, and programs round differently. The standard white point is 0.3127, but plenty of writers emit 0.313. Same intent, but a straight == would fail. Allowing each number to be off by up to 0.002 absorbs the rounding.

And 0.002 can't pick the wrong set, because the three sets aren't remotely close to each other: any two of them differ by at least 0.09 in one of the eight numbers, about 45 times the tolerance. A file's numbers can only ever be near one of them.

[beicause]

Question: How do you plan to utilize the image color primaries information? In shaders, it is impossible to attach primaries information to every texture for performance reasons.

[stuartparmenter]

Question: How do you plan to utilize the image color primaries information? In shaders, it is impossible to attach primaries information to every texture for performance reasons.

I have planned, but haven't actually built, tested, and profiled the answer to your question yet -- was wanting to avoid making the already large HDR branch even bigger. Today the full branch carries the the metadata through to GpuImage, but then nothing reads it. Under the (upcoming) wide working space, every color texture is assumed to be Rec.709-authored, and the composed color converts once at the end of composition.

The future plan (that I will build out once more of the PRs have made progress and the dust has settled) is roughly:

1. single-texture pipelines specialize on the texture's primaries metadata. The skybox and environment map pipelines come first for things like wide-gamut HDRIs. The metadata selects a shader def at pipeline build, and the def folds a constant conversion matrix into the shader. No primaries data reaches the shader at runtime. This is also why the type is a small enum that can be hashed and compared -- it's built to sit in a pipeline key.

2. materials that bind many textures need something else. Thinking that we probably convert the pixel data at decode or upload time, but want to explore some more options. I don't like doing a per-texture flag at shared sampling sites since they can't know whether an earlier step already converted the value, so it can be double converted.

I can open a issue and add it to my HDR tracking issue if you want to discuss approaches there on how to best do it, would love any input!