Blitz3D+ Command Reference

ToneMapExposure [stops#]

Parameters

stops# (optional) - manual exposure in photographic stops, from -16 to 16; 0 (default)

Description

Brightens or darkens the HDR scene before tone mapping.

Exposure works like a camera's: each positive stop doubles scene brightness and each negative stop halves it, applied before the tone-map curve. Use it to set a scene's mood - push a stop or two negative for a dim interior, positive to lift a dark night scene - or animate it briefly for a flash-bang or an eyes-adjusting transition when the player steps outdoors.

The gotcha: it only has a visible effect while HDRRendering is enabled. The value is stored regardless, so setting it before enabling HDR is fine. There is no automatic exposure - this command is the manual control. Out-of-range values are clamped and a non-finite value resets to 0.

For the full story, see the image-quality guide.

Requires Extended mode.

See also: HDRRendering, ToneMapMode.

Example

; ToneMapExposure Example
; -----------------------
; Requires Extended mode.

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

camera=CreateCamera()
PositionEntity camera,0,2,-7
RotateEntity camera,10,0,0

; An overbright sun pushes lit surfaces well above white
sun=CreateLight(1)
RotateEntity sun,45,30,0
LightColor sun,480,440,380

; Exposure only applies while HDR rendering is enabled
HDRRendering True

; Ground plane catching the intense light
ground=CreateCube()
ScaleEntity ground,10,0.1,10
PositionEntity ground,0,-0.1,3
EntityColor ground,190,190,200

; Orbiting gems - dial exposure down to rescue their bright detail,
; or up to blow the scene out like a camera left in the sun
ring=CreatePivot()
PositionEntity ring,0,1.5,3
For i=0 To 5
    gem=CreateSphere(16)
    ScaleEntity gem,0.7,0.7,0.7
    PositionEntity gem,Cos(i*60)*3,0,Sin(i*60)*3
    EntityColor gem,255-i*25,90+i*25,140
    EntityParent gem,ring
Next

stops#=0

While Not KeyDown(1)

    ; [ / ] darken or brighten by fractions of a stop; R resets
    If KeyDown(26) And stops>-4 Then stops=stops-0.02
    If KeyDown(27) And stops<4 Then stops=stops+0.02
    If KeyHit(19) Then stops=0

    ; Set manual exposure in photographic stops (each stop doubles)
    ToneMapExposure stops

    TurnEntity ring,0,0.7,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,"[ ]: exposure down/up   R: reset   Arrow keys: move camera   Esc: exit"
    Text 0,20,"ToneMapExposure "+stops
    Text 0,40,"Each +1 stop doubles scene brightness; -1 halves it"

    Flip

Wend

End

Index