Blitz3D+ Command Reference

CaptureStatus ( )

Parameters

None.

Description

Returns the state of the most recent capture request.

Captures are asynchronous - CaptureScreenshot and CaptureFrame arm a request that fires at the next Flip - so CaptureStatus is how your program follows along. It returns one of four values:

0: idle - no capture has been requested
1: armed - a capture is waiting for the next Flip
2: success - the last capture was written to disk
-1: failed - the last request was rejected or the write failed

The usual pattern: request the capture, keep running your normal RenderWorld/Flip loop, and watch for the status to change from 1. On 2 the files are on disk; on -1 call CaptureError for the reason. A rejected request (bad extension, no Graphics3D) goes straight to -1 without ever being armed, and an armed capture also drops to -1 if 3D graphics end before the next Flip.

Note that a fresh request resets the status, so read the result you care about before arming the next capture.

Requires Extended mode.

See also: CaptureScreenshot, CaptureFrame, CaptureError.

Example

; CaptureStatus Example
; ---------------------
; Requires Extended mode.

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

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

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

trophy=CreateSphere(24)
EntityColor trophy,255,120,60

While Not KeyDown(1)

    ; Space arms a screenshot; watch the status change as it is taken
    If KeyHit(57) Then CaptureScreenshot "capture_example.png"

    TurnEntity trophy,0.5,1.5,0

    ; CaptureStatus tracks the life of a capture request
    status=CaptureStatus()
    If status=0 Then label$="0 - idle"
    If status=1 Then label$="1 - armed for the next Flip"
    If status=2 Then label$="2 - capture_example.png saved"
    If status=-1 Then label$="-1 - rejected or failed"

    ; 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: take screenshot   Esc: exit"
    Text 0,20,"CaptureStatus() = "+label

    Flip

Wend

End

Index