AmbientLight docs doesn't specify units

[fintelia]

How can Bevy's documentation be improved?

The documentation for AmbientLights brightness field says:

A direct scale factor multiplied with color before being passed to the shader.

However, it would be helpful to know the units of the product of multiplying color and the scale factor. I suspect the unit is either lux or nits, but I haven't investigated

[BD103]

brightness is a multiplier, so it itself does not have any units. It was originally added in #1605, where it calculates:

(ambient_light_resource.color * ambient_light_resource.brightness)

Which is equivalent to a Vec4 * f32. On main, it currently looks like:

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

Lines 983 to 984 in a9ca849

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

[fintelia]

You could say the same thing about the skybox's brightness field. The documentation I'm looking for is the analog of this line:

Scale factor applied to the skybox image. After applying this multiplier to the image samples, the resulting values should be in units of cd/m^2.

[BD103]

That's a very good point. So would AmbientLight::brightness also be in cd/m^2, or would it be some other unit?

[superdump]

Looking at the code I think @fintelia ’s last comment is the correct answer.

[BD103]

Marking this as a good first issue. AmbientLight's brightness field should document that it is in cd/m^2, similar to Skybox::brightness, if I'm understanding @superdump's comment correctly.

[janhohenheim]

Maybe it would also be good to specify that this is not equivalent to Filament's IBL, even though the units are the same and they are both used for global illumination.

[superdump]

@janhohenheim my understanding is that if one sets bevy’s ambient light brightness to 1 then it would be the same. Or you can consider the combination of color * brightness to be the same as Filament’s IBL.

[janhohenheim]

@superdump I'm very skeptical because per google/filament#1667, Blender's background shader is the same as IBL, but my testing in #12280 reveals that it does not correspond at all to an AmbientLight when using a strength of 1.
Of course, I might be wrong in how I export stuff from Blender, so take this with a grain of salt.