Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Specify units in AmbientLight::brightness docs #13297

Merged
merged 1 commit into from
Jun 18, 2024
Merged

Specify units in AmbientLight::brightness docs #13297

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
4 changes: 4 additions & 0 deletions crates/bevy_pbr/src/light/ambient_light.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ use super::*;
pub struct AmbientLight {
pub color: Color,
/// A direct scale factor multiplied with `color` before being passed to the shader.
///
/// After applying this multiplier, the resulting value should be in units of [cd/m^2].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

///
/// [cd/m^2]: https://en.wikipedia.org/wiki/Candela_per_square_metre
pub brightness: f32,
}

Expand Down