Blitz3D+ Command Reference

CameraClsMode camera,cls_color,cls_zbuffer

Parameters

camera - camera handle

cls_color - true to clear the colour buffer before rendering, false not to; true (default)

cls_zbuffer - true to clear the z-buffer before rendering, false not to; true (default)

Description

Sets what a camera clears before it renders.

By default a camera clears both the colour buffer (to its CameraClsColor) and the z-buffer each time it is rendered. Turning either off is a tool for layered rendering with multiple cameras.

Turning cls_color off leaves the previous contents on screen and draws the new view over the top. The classic use is a skybox camera: render the sky first with a dedicated camera, then render the main scene with cls_color off so the sky shows behind it. It also enables trippy motion-trail effects in windowed play areas.

Turning cls_zbuffer off keeps the depth information from an earlier camera, so a second pass can depth-test against the first. Leave it on for overlay cameras (a 3D cockpit or weapon view) that should draw over the whole scene regardless of distance.

Gotcha: with cls_color off and nothing behind, the viewport shows leftover garbage from previous frames - make sure something (another camera, or 2D drawing) fills the background every frame.

See also: CameraClsColor, CameraViewport, CameraProjMode.

Example

; CameraClsMode Example
; ---------------------

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

camera=CreateCamera()
PositionEntity camera,0,1,-10

light=CreateLight()
RotateEntity light,45,45,0

; Textured ground plane
plane=CreatePlane()
ground_tex=LoadTexture("media/MossyGround.BMP")
EntityTexture plane,ground_tex

cube=CreateCube()
PositionEntity cube,0,1,0

; Load a 2D sky image to draw behind the 3D scene
background=LoadImage("media/sky.bmp")

; Red ink so the text shows on both the black and sky backgrounds
Color 255,0,0

cls_color=1

While Not KeyDown(1)

    ; Space toggles colour-buffer clearing on and off
    If KeyHit(57) Then cls_color=1-cls_color

    ; When cls_color is 0 the camera no longer wipes the screen, so the
    ; 2D sky drawn below shows through behind the 3D scene
    CameraClsMode camera,cls_color,1

    ; Tile the 2D sky image across the screen before rendering the 3D scene
    TileBlock background,0,0

    TurnEntity cube,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,"Arrow keys: move camera   Space: toggle colour clearing   Esc: exit"
    Text 0,20,"CameraClsMode camera,"+cls_color+",1"

    Flip

Wend

End

Index