Blitz3D+ Command Reference

LockBuffer [buffer]

Parameters

buffer (optional) - the buffer to lock; the current buffer set with SetBuffer (default)

Description

Locks a buffer for direct pixel access with the Fast pixel commands.

The fast pixel commands - ReadPixelFast, WritePixelFast, CopyPixelFast - skip every safety check to touch pixels at maximum speed, and the classic contract is that they may only run between LockBuffer and UnlockBuffer. The usual shape is: LockBuffer, a tight loop of Fast reads/writes (a plasma effect, a heightmap render, custom image processing), then UnlockBuffer.

While a buffer is locked, stick to the pixel commands - do not use other drawing commands on it until you unlock. Keep the locked stretch as short as possible.

On the modern runtime buffers live in main memory, so locking is instant and costs nothing - but keep the Lock/Unlock pairing anyway: it is what makes the Fast commands legal, and code without it breaks on classic Blitz3D. What is still very real is that the Fast commands do no bounds checking - see their pages for the warnings.

See also: UnlockBuffer, ReadPixelFast, WritePixelFast, CopyPixelFast.

Example

; LockBuffer Example
; ------------------

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

t#=0

While Not KeyDown(1)

    Cls
    t=t+4

    ; The buffer MUST be locked before ReadPixelFast/WritePixelFast work
    LockBuffer BackBuffer()

    ; Write a plasma pattern pixel by pixel into a small panel
    For y=0 To 95
        For x=0 To 127
            v#=Sin(x*4+t)+Sin(y*5-t)+Sin((x+y)*3+t*2)
            r=128+v*42
            g=128+Sin(v*60+t)*127
            b=255-r
            WritePixelFast 256+x,192+y,$FF000000 Or (r Shl 16) Or (g Shl 8) Or b
        Next
    Next

    ; Unlock before using any other drawing command (Rect, Text, Flip...)
    UnlockBuffer BackBuffer()

    Color 255,255,255
    Rect 255,191,130,98,0
    Text 0,0,"Esc: exit"
    Text 0,20,"LockBuffer BackBuffer() lets us write 12,288 pixels every frame"

    Flip

Wend

End

Index