chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add light softness: spotlight edge softness for physically-based rendering.

Browse Source 
The new spotlight attribute softness (real in [0, 1], default 0) is the
fraction of the cone, measured inward from the cutoff, over which
intensity falls to zero. It is used by physically-based lighting models;
the Phong model's corresponding knob remains exponent.

The filament renderer previously hardcoded the inner cone angle to 0,
making the entire beam penumbra: the shader attenuates by the squared
smoothstep ((cos(theta) - cos(outer)) / (cos(inner) - cos(outer)))^2, so
a cutoff-25 spot delivered its rated candela only exactly on-axis and
about a third of it averaged over the light pool, with the deficit
shrinking as the cutoff widens. The inner angle is now
(1 - softness) * cutoff, so at the default the light delivers its full
intensity everywhere inside the cone and illuminance follows E = I/d^2
independent of the cutoff. Setting softness to 1 reproduces the previous
appearance exactly (verified bit-identical), which is the migration path
for models tuned against the old behavior.

The filament light type also changes from FOCUSED_SPOT to SPOT. With
intensity given in candela and the cone set at build time the two types
produce identical output (FOCUSED_SPOT's power-conserving rescale only
applies when the cone changes after the intensity is set), but SPOT
guarantees that candela never rescales with cone angle should the cone
ever become runtime-editable.

Verified with headless renders under a linear tone mapper against an
equal-candela point light at cutoffs 25/45/80: softness 0 gives
spot/point luminance ratio 1.000 at all sampled angles inside the cone;
softness 0.2 is flat over the inner 80% of the cone; softness 1 matches
the previous renderer with zero linear-pixel difference. XML round-trip
and the [0, 1] compile-time check verified. Introspect and wasm bindings
regenerated.

PiperOrigin-RevId: 959334706
Change-Id: I0f0729781899880de1729ea9b3d8c055d715a025
This commit is contained in:
Yuval Tassa
2026-08-04 18:11:03 -07:00
committed by Copybara-Service
parent 92261d9095
commit f9a00bd5b5
27 changed files with 118 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/XMLreference.rst
+18 -4
View File
@@ -3307,18 +3307,30 @@ Attributes may be applied or ignored depending on the lighting model being used.
.. _body-light-attenuation:
:at:`attenuation`: :at-val:`real(3), "1 0 0"`
These are the constant, linear and quadratic attenuation coefficients for Phong lighting.
The default corresponds to no attenuation.
These are the constant, linear and quadratic attenuation coefficients, used by the default Phong lighting model.
The default corresponds to no attenuation. Physically-based lighting models instead attenuate with the inverse
square of distance, scaled by :ref:`intensity<body-light-intensity>` and limited by :ref:`range<body-light-range>`.
.. _body-light-cutoff:
:at:`cutoff`: :at-val:`real, "45"`
Cutoff angle for spotlights, always in degrees regardless of the global angle setting.
Cutoff angle for spotlights, always in degrees regardless of the global angle setting. The falloff of intensity
inside the cone is controlled by :ref:`softness<body-light-softness>` for physically-based lighting models and by
:ref:`exponent<body-light-exponent>` for the default Phong lighting model.
.. _body-light-softness:
:at:`softness`: :at-val:`real, "0"`
Edge softness for spotlights, as a fraction of the :ref:`cutoff<body-light-cutoff>` angle in [0, 1], used by
physically-based lighting models. The light delivers its full :ref:`intensity<body-light-intensity>` inside the
cone, falling to zero over the outer softness fraction of the cone angle; the default corresponds to a sharp-edged
cone. This is unused by the default Phong lighting model, which uses :ref:`exponent<body-light-exponent>`.
.. _body-light-exponent:
:at:`exponent`: :at-val:`real, "10"`
Exponent for spotlights. This setting controls the softness of the spotlight cutoff.
Exponent for spotlights, used by the default Phong lighting model. This setting controls the softness of the
spotlight cutoff. Physically-based lighting models use :ref:`softness<body-light-softness>` instead.
.. _body-composite:
@@ -10035,6 +10047,8 @@ if omitted.
.. _default-light-cutoff:
.. _default-light-softness:
.. _default-light-exponent:
.. _default-light-mode:
doc/XMLschema.rst
+6
View File
@@ -1163,6 +1163,9 @@
.. grid-item::
:ref:`cutoff<body-light-cutoff>`
.. grid-item::
:ref:`softness<body-light-softness>`
.. grid-item::
:ref:`exponent<body-light-exponent>`
@@ -5873,6 +5876,9 @@
.. grid-item::
:ref:`cutoff<default-light-cutoff>`
.. grid-item::
:ref:`softness<default-light-softness>`
.. grid-item::
:ref:`exponent<default-light-exponent>`
doc/changelog.rst
+15 -2
View File
@@ -13,8 +13,6 @@ General
grammar table, presence constraints, keyword maps, typed attribute bindings and save policies are generated from it
and gated by tests, as are the schema's enum keywords and declared defaults against the C headers and
default-constructors.
- An XSD schema derived from the main schema is provided in
`model/mjcf.xsd <https://github.com/google-deepmind/mujoco/tree/main/src/xml/generated/mjcf.xsd>`__.
Actuation
^^^^^^^^^
@@ -58,6 +56,21 @@ Models
Unlike the poncho models, which are bending-only, this model exercises the 2D
:ref:`stretch<flex-elasticity-elastic2d>` elasticity of a flex.
Rendering
^^^^^^^^^
.. admonition:: Breaking API changes
:class: attention
- Added :ref:`light/softness<body-light-softness>`: edge softness for spotlights under physically-based lighting
models, given as the fraction of the cone over which intensity falls to zero. The default of 0 is a sharp-edged
cone which delivers the full :ref:`intensity<body-light-intensity>` everywhere inside it, so that illuminance
follows :math:`E = I/d^2` independent of the :ref:`cutoff<body-light-cutoff>` angle. Previously the filament
renderer treated the entire cone as penumbra, dimming spotlights well below their rated intensity, increasingly
so for narrow cutoffs.
**Migration:** Set :at:`softness` to 1 to reproduce the previous appearance of existing models.
Bug fixes
^^^^^^^^^
doc/includes/references.h
+4
View File
@@ -860,6 +860,7 @@ typedef struct mjModel_ {
mjtNum* light_dir0; // global direction in qpos0 (nlight x 3)
float* light_attenuation; // OpenGL attenuation (quadratic model) (nlight x 3)
float* light_cutoff; // OpenGL cutoff (nlight x 1)
float* light_softness; // spotlight edge softness (nlight x 1)
float* light_exponent; // OpenGL exponent (nlight x 1)
float* light_ambient; // ambient rgb (alpha=1) (nlight x 3)
float* light_diffuse; // diffuse rgb (alpha=1) (nlight x 3)
@@ -1606,6 +1607,7 @@ typedef struct mjrfLightParams_ {
mjtBool cast_shadows; // if true, cast shadows
float range; // effective range of light, in meters
float spot_cone_angle; // spot light cone angle, in degrees
float spot_softness; // spot light edge softness, fraction of cone angle in [0, 1]
int shadow_map_size; // size of shadow map texture, 0 to use default size
float bulb_radius; // bulb radius, used for soft shadows
float vsm_blur_width; // variance shadow map blur width
@@ -1999,6 +2001,7 @@ typedef struct mjsLight_ { // light specification
float range; // range of effectiveness
float attenuation[3]; // OpenGL attenuation (quadratic model)
float cutoff; // OpenGL cutoff
float softness; // spotlight edge softness
float exponent; // OpenGL exponent
float ambient[3]; // ambient color
float diffuse[3]; // diffuse color
@@ -3291,6 +3294,7 @@ typedef struct mjvLight_ { // OpenGL light
float bulbradius; // bulb radius for soft shadows
float intensity; // intensity, in candelas
float range; // range of effectiveness
float softness; // spotlight edge softness
} mjvLight;
typedef struct mjvOption_ { // abstract visualization options
int label; // what objects to label (mjtLabel)