Specify units in AmbientLight::brightness docs

[BD103]

Objective

• Fixes AmbientLight docs doesn't specify units #11933.
• Related: What is the relationship between AmbientColor::brightness and Blender's background color strength? #12280.

Solution

• Specify that, after applying AmbientLight, the resulting units are in cd/m^2.
• This is based on @fintelia's comment, and will need to be verified.

---

Changelog

• Specified units for AmbientLight's brightness field.

[mockersf]

Is it that straightforward? Does it depend on the color type? Is alpha ignored? How can I get the total brightness from each channel?

[BD103]

I don't know; I was just following the comments in the issue. @fintelia or @superdump, could you comment on this?

[fintelia]

First the color gets converted to linear sRGB (if necessary) and scaled by the brightness:

bevy/crates/bevy_pbr/src/render/light.rs

Lines 985 to 986 in 4da11fd

	ambient_color: Vec4::from_slice(&LinearRgba::from(ambient_light.color).to_f32_array())
	* ambient_light.brightness,

Then the alpha channel gets completely ignored via a swizzle and the RGB channels are used for rendering calculations:

bevy/crates/bevy_pbr/src/render/pbr_ambient.wgsl

Line 28 in 4da11fd

return (diffuse_ambient + specular_ambient * specular_occlusion) * lights.ambient_color.rgb * occlusion;

Interpreting the meaning of the three values in the RGB channels is a much deeper rabbit hole. My non-expert understanding is that a value like (100.0, 100.0, 100.0) corresponds to a total light intensity of 100 cd/m^2 divided up as 21 cd/m^2 of red light, 72 cd/m^2 of green light, and 7 cd/m^2 of blue light. Where the colors precise meanings of "red light", "green light", and "blue light" are given by the sRGB spec and the relative weights also come from that same spec

[bushrat011899]

Based on its usage in prepare_lights, the ambient light is always converted to LinearRgba (so colour space does not matter), and the colour passed to the GPU is this colour scaled by brightness.

So, we could either say Color is unitless (a scalar) and brightness is in cd/m^2, or the reverse. I think we want to say Color is unitless because it conceptually makes more sense that brightness is the intensity value (candela/square-metre).