lighting
FreeBodyEngine.graphics.pbr.lighting
#
Light node types for PBRPipeline's deferred lighting composite pass (see graphics/pbr/pipeline.py). These are PBRPipeline-specific, not a core engine concept - a different GraphicsPipeline is free to have no lighting model at all, or a completely different one, so this deliberately lives under graphics/pbr rather than core.
A Light is always paired with a Node2D or Node3D base, the same mixin
pattern core/camera.py's Camera uses -
PointLight2D/DirectionalLight2D/SpotLight2D for 2D scenes,
PointLight3D/DirectionalLight3D/SpotLight3D for 3D ones. Both flavors
feed the same per-pixel lighting math in the composite shader (see
engine_assets/shader/lighting_composite.fbfrag) - a 2D light is just a 3D
light whose node happens to live in a Node2D tree, placed at a nominal
world-space Z height so falloff/direction math isn't degenerate at z=0.
Shadows: cast_shadows is honored today only for DirectionalLight3D (a
real orthographic shadow map - see PBRPipeline._render_shadow_maps()). It's
accepted on every other light type but is currently a no-op there - 2D
shadow casting needs its own visibility/radial-map technique rather than a
repurposed 3D depth map (sprites are coplanar with the camera's view plane,
so there's no "above" for a light to look down from the way a 3D directional
light can); that's tracked as separate follow-up work, not implemented here.
Point/spot shadow maps (3D) are also left for follow-up - they need a
cubemap or paraboloid map rather than DirectionalLight3D's single ortho map.
DirectionalLight2D(rotation=45.0, z=5.0, color=Color('#FFFFFFFF'), intensity=1.0)
#
A 2D 'sun' light - shines from a fixed direction across the whole
scene rather than from a point. rotation (inherited from Node2D)
controls that direction in the XY plane; z gives it a small downward
component so it lights flat 2D geometry's surface normal rather than
grazing it edge-on. No shadows (see module docstring).
DirectionalLight3D(rotation=Vector3(-45.0, 45.0, 0.0), color=Color('#FFFFFFFF'), intensity=1.0, cast_shadows=False, shadow_extent=20.0, shadow_distance=30.0)
#
A 3D 'sun' light - shines uniformly from a fixed direction across the
whole scene. This is the one light type with a real shadow
implementation today: with cast_shadows=True, PBRPipeline renders a
single orthographic depth map from this light's direction each frame
and samples it in the composite pass (see
PBRPipeline._render_shadow_maps()).
shadow_extent is the half-width of the orthographic shadow
frustum (world units) and shadow_distance is how far back along
-direction3 the shadow camera is placed before looking at the
scene origin - both only matter when cast_shadows is True.
Light(light_type, color, intensity, range, spot_angle, cast_shadows)
#
Mixin holding the color/intensity/falloff/shadow state shared by every light node - never used on its own, always alongside a Node2D or Node3D base (see the concrete classes below).
Stores this light's shading parameters.
:param light_type: POINT/DIRECTIONAL/SPOT - selects the falloff
model the composite pass uses for this light.
:param color: The light's color.
:param intensity: A brightness multiplier on top of color.
:param range: For POINT/SPOT, the world-space distance at which this
light's contribution reaches zero. Unused for DIRECTIONAL.
:param spot_angle: For SPOT, the half-angle (degrees) of the cone.
Unused otherwise.
:param cast_shadows: Whether this light should cast real-time
shadows - see the module docstring for which light types
actually honor this today.
LightType
#
PointLight2D(position=Vector(), z=0.5, color=Color('#FFFFFFFF'), intensity=1.0, range=6.0)
#
A 2D point light - radiates outward from a world-space point with
distance falloff out to range, no shadows (see module docstring).
z places this light a nominal height above the 2D scene's own
Z=0 plane, purely so falloff distance isn't computed against a
light sitting exactly in the same plane as everything it lights.
PointLight3D(position=Vector3(), color=Color('#FFFFFFFF'), intensity=1.0, range=8.0, cast_shadows=False)
#
A 3D point light - radiates outward from a world-space point with
distance falloff out to range. Shadows not yet implemented for point
lights (needs a cubemap/paraboloid map - see module docstring).
world_position3
property
#
This light's world position - named to match PointLight2D/
SpotLight2D's world_position3 so PBRPipeline can read any light's
position the same way regardless of whether it's 2D or 3D.
SpotLight2D(position=Vector(), rotation=0.0, z=0.5, color=Color('#FFFFFFFF'), intensity=1.0, range=6.0, spot_angle=30.0)
#
SpotLight3D(position=Vector3(), rotation=Vector3(), color=Color('#FFFFFFFF'), intensity=1.0, range=8.0, spot_angle=30.0, cast_shadows=False)
#
A 3D spot light - a point light restricted to a cone facing this node's rotation. Shadows not yet implemented for spot lights (see module docstring).