Blitz3D+ Command Reference

UpdateGamma [calibrate]

Parameters

calibrate (optional) - ask the driver to calibrate the ramp rather than take it literally
   0: use the ramp as given (default)
   1: let the driver calibrate it

Description

Sends the gamma table you built with SetGamma to the display.

SetGamma only fills in a 256-entry table held in memory; nothing happens on screen until UpdateGamma hands that table over. The usual shape is a loop that writes the whole ramp followed by one UpdateGamma, once per frame while a fade is running, or once when the player moves the brightness slider in your options menu.

The optional calibrate flag came from DirectDraw. With it off, the ramp is passed through as written. With it on, the driver was allowed to adjust the ramp so that the result matched a calibrated response on that particular monitor - more accurate in theory, but slower, and not supported by every card, so most games left it off.

On the modern DirectX 12 backend UpdateGamma is a no-op. It accepts the call and the flag, costs nothing, and does not raise an error, but the ramp is never handed to the monitor, so screen brightness does not change. The table itself is still real: everything you wrote with SetGamma reads back correctly through GammaRed, GammaGreen and GammaBlue, which makes it a perfectly good place to keep the player's brightness setting - your renderer just has to apply it itself.

So if you are writing a fade today, draw it: a black Rect over the frame with a rising alpha, or a post-process shader. Keep the SetGamma/UpdateGamma pair if you are porting an old project - it is harmless, and it documents the intent.

See also: SetGamma, GammaRed, GammaGreen, GammaBlue, Graphics.

Example

; UpdateGamma Example
; -------------------

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

; Fade level for a classic screen fade: 1.0 is normal, 0.0 is black
fade#=1.0

; UpdateGamma's optional flag asks the driver to calibrate the ramp
calibrate=0

While Not KeyDown(1)

    Cls

    ; [ and ] fade the picture down and back up
    If KeyDown(26) And fade>0 Then fade=fade-0.01
    If KeyDown(27) And fade<1 Then fade=fade+0.01

    ; Space toggles the calibrate flag
    If KeyHit(57) Then calibrate=1-calibrate

    ; Build the faded ramp...
    For i=0 To 255
        level#=i*fade
        SetGamma i,i,i,level,level,level
    Next

    ; ...then hand it to the display. Without this call the table you
    ; built with SetGamma just sits in memory.
    UpdateGamma calibrate

    ; Colour bars drawn straight to the screen
    For x=0 To 255
        Color x,x/2,255-x
        Rect 60+x,140,1,60
    Next

    ; The same bars run through the ramp by hand, so you can see the
    ; fade this example is asking the driver for
    For x=0 To 255
        Color GammaRed(x),GammaGreen(x/2),GammaBlue(255-x)
        Rect 60+x,220,1,60
    Next

    Color 255,255,255

    Text 0,0,"[ / ] : fade out and in   Space: calibrate flag   Esc: exit"
    Text 0,20,"UpdateGamma "+calibrate+"   (fade level "+fade+")"

    Text 60,120,"Drawn normally"
    Text 60,200,"Through the ramp UpdateGamma was given"

    Text 0,420,"On the DirectX 12 backend UpdateGamma accepts the table but"
    Text 0,440,"does nothing with it, so the window does not really fade."
    Text 0,460,"The lower bars show the fade the ramp describes."

    Flip

Wend

End

Index