Blitz3D+ Command Reference

ShadowBias depth_bias#,normal_bias#

Parameters

depth_bias# - offset applied to the shadow depth comparison; 0.001 (default)

normal_bias# - offset pushing receivers along their surface normal, in world units; 0.02 (default)

Description

Fine-tunes shadows to remove acne or gaps.

Shadow maps have limited precision, and bias is the trade-off dial between their two classic artefacts. Too little bias causes shadow acne: stripey or checkered self-shadowing crawling across surfaces that should be lit. Too much causes peter-panning: shadows detach from their objects, leaving a gap at the feet so everything looks like it is floating. The goal is the narrow band in between.

The depth bias offsets the depth comparison itself, and the normal bias nudges each receiving surface along its normal before the test. The engine additionally scales bias with shadow-map texel size per cascade, so your values act as the base and the defaults hold up well at ordinary metre-ish scene scales.

Reach for this command when your world is unusually large or tiny, or when a low quality preset shows acne at distance: nudge depth bias in small steps (0.0005 at a time) and normal bias in centimetre steps until both artefacts are gone. Negative values are clamped to 0.

Requires Extended mode.

See also: Shadows, ShadowQuality, ShadowDistance.

Example

; ShadowBias Example
; ------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,4,-8
RotateEntity camera,22,0,0

; A directional sun; the shadow system selects it automatically
sun=CreateLight(1)
AmbientLight 70,75,85

; Large ground plane; low bias values show acne speckles here
ground=CreateCube()
ScaleEntity ground,10,0.1,10
PositionEntity ground,0,-0.1,4
EntityColor ground,170,190,170

; A crate and a pillar to cast shadows
crate=CreateCube()
PositionEntity crate,-2.5,1,4
EntityColor crate,210,150,80

pillar=CreateCylinder()
ScaleEntity pillar,0.7,2,0.7
PositionEntity pillar,2.5,2,5
EntityColor pillar,120,160,220

; Turn on the automatic shadow system
Shadows 1

; Engine defaults are 0.001 and 0.02
depth_bias#=0.001
normal_bias#=0.02
angle#=0

While Not KeyDown(1)

    ; [ / ] adjust depth bias, - / = adjust normal bias
    If KeyDown(26) And depth_bias>0 Then depth_bias=depth_bias-0.0001
    If KeyDown(27) And depth_bias<0.01 Then depth_bias=depth_bias+0.0001
    If KeyDown(12) And normal_bias>0 Then normal_bias=normal_bias-0.002
    If KeyDown(13) And normal_bias<0.2 Then normal_bias=normal_bias+0.002
    If depth_bias<0 Then depth_bias=0
    If normal_bias<0 Then normal_bias=0

    ; Tune away shadow acne (bias too low) or detached shadows (too high)
    ShadowBias depth_bias,normal_bias

    ; Swing the sun so grazing angles reveal acne at low bias
    angle=angle+0.3
    RotateEntity sun,55,angle,0

    TurnEntity crate,0,1,0

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"[ ]: depth bias   - =: normal bias   Arrow keys: move camera   Esc: exit"
    Text 0,20,"ShadowBias "+depth_bias+","+normal_bias
    Text 0,40,"Drop both to 0 for acne; push them high for detached shadows"

    Flip

Wend

End

Index