From 82501a67960c54f92358d07123cca78b88082d26 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 10 Aug 2025 16:09:30 -0700 Subject: [PATCH 1/4] Docs for emissive color on StandardMaterial --- crates/bevy_pbr/src/pbr_material.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/crates/bevy_pbr/src/pbr_material.rs b/crates/bevy_pbr/src/pbr_material.rs index 9c988bf1ed0fe..45aaf95814d3f 100644 --- a/crates/bevy_pbr/src/pbr_material.rs +++ b/crates/bevy_pbr/src/pbr_material.rs @@ -78,13 +78,20 @@ pub struct StandardMaterial { /// /// The default emissive color is [`LinearRgba::BLACK`], which doesn't add anything to the material color. /// - /// To increase emissive strength, channel values for `emissive` + /// Emissive strength is controlled by the value of the color channels, + /// while the hue is controlled by their relative values. + /// + /// As a result, channel values for `emissive` /// colors can exceed `1.0`. For instance, a `base_color` of /// `LinearRgba::rgb(1.0, 0.0, 0.0)` represents the brightest /// red for objects that reflect light, but an emissive color /// like `LinearRgba::rgb(1000.0, 0.0, 0.0)` can be used to create /// intensely bright red emissive effects. /// + /// From a physical perspective, the units of the emissive color + /// are given in luminance (cd/m², aka nits), which is a measure of + /// the amount of light emitted per unit area. + /// /// Increasing the emissive strength of the color will impact visual effects /// like bloom, but it's important to note that **an emissive material won't /// light up surrounding areas like a light source**, From 7b3563f5cafdf0a8cdaa8eabffaafc64038de970 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 10 Aug 2025 16:16:03 -0700 Subject: [PATCH 2/4] Note joint effect of texture and color --- crates/bevy_pbr/src/pbr_material.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/crates/bevy_pbr/src/pbr_material.rs b/crates/bevy_pbr/src/pbr_material.rs index 45aaf95814d3f..0bcc78a4efb5e 100644 --- a/crates/bevy_pbr/src/pbr_material.rs +++ b/crates/bevy_pbr/src/pbr_material.rs @@ -88,9 +88,11 @@ pub struct StandardMaterial { /// like `LinearRgba::rgb(1000.0, 0.0, 0.0)` can be used to create /// intensely bright red emissive effects. /// - /// From a physical perspective, the units of the emissive color - /// are given in luminance (cd/m², aka nits), which is a measure of - /// the amount of light emitted per unit area. + /// This results in a final luminance value when multiplied + /// by the value of the greyscale emissive texture (which ranges from 0 for black to 1 for white). + /// Luminance is a measure of the amount of light emitted per unit area, + /// and can be thought of as the "brightness" of the effect. + /// In Bevy, these luminance values correspond to physical units of cd/m², aka nits. /// /// Increasing the emissive strength of the color will impact visual effects /// like bloom, but it's important to note that **an emissive material won't From 5edcede141d1a96bcb843dff8177c98a0d114296 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 10 Aug 2025 16:17:27 -0700 Subject: [PATCH 3/4] Weasel words to account for bevy_solari :p --- crates/bevy_pbr/src/pbr_material.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_pbr/src/pbr_material.rs b/crates/bevy_pbr/src/pbr_material.rs index 0bcc78a4efb5e..5fb9066eebc25 100644 --- a/crates/bevy_pbr/src/pbr_material.rs +++ b/crates/bevy_pbr/src/pbr_material.rs @@ -96,7 +96,7 @@ pub struct StandardMaterial { /// /// Increasing the emissive strength of the color will impact visual effects /// like bloom, but it's important to note that **an emissive material won't - /// light up surrounding areas like a light source**, + /// typically light up surrounding areas like a light source**, /// it just adds a value to the color seen on screen. pub emissive: LinearRgba, From d09f3d11696aa9ab2ac0a037ccac5f67c9f77527 Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Sun, 10 Aug 2025 22:06:19 -0400 Subject: [PATCH 4/4] Clarify that our usage of the units is normative --- crates/bevy_pbr/src/pbr_material.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_pbr/src/pbr_material.rs b/crates/bevy_pbr/src/pbr_material.rs index 5fb9066eebc25..5f6314b9a11b5 100644 --- a/crates/bevy_pbr/src/pbr_material.rs +++ b/crates/bevy_pbr/src/pbr_material.rs @@ -92,7 +92,7 @@ pub struct StandardMaterial { /// by the value of the greyscale emissive texture (which ranges from 0 for black to 1 for white). /// Luminance is a measure of the amount of light emitted per unit area, /// and can be thought of as the "brightness" of the effect. - /// In Bevy, these luminance values correspond to physical units of cd/m², aka nits. + /// In Bevy, we treat these luminance values as the physical units of cd/m², aka nits. /// /// Increasing the emissive strength of the color will impact visual effects /// like bloom, but it's important to note that **an emissive material won't