CaptureScreenshot ( file$ )

Parameters

file$ - file to write; .png and .bmp are supported, and a name with no extension gets .png added

Description

Arms a screenshot of the next presented frame, saved as a PNG or BMP file. Returns True when the request is accepted.

CaptureScreenshot does not grab pixels immediately - it arms a capture that fires at the next Flip (or FlipCanvas), saving exactly what the player sees: the rendered world, your 2D overlay text and drawing, everything, including views presented through RenderWorldToCanvas. Bind it to a key and you have a player screenshot feature in three lines.

The write happens as the frame is presented, and the result arrives afterwards: poll CaptureStatus (1 while armed, 2 on success, -1 on failure) and read CaptureError for the reason when something went wrong. The outcome is also filed in the diagnostics store.

Only .png and .bmp files are supported - any other extension, such as .jpg, is rejected on the spot: the function returns False, CaptureStatus goes to -1 and CaptureError explains. A file name with no extension quietly becomes a .png.

One capture can be armed at a time. Asking again while one is waiting returns False and leaves the armed request untouched. Capturing requires Graphics3D, and an armed capture is cancelled (status -1) if 3D graphics end before the next Flip.

For a screenshot plus a full renderer report in one go, use CaptureFrame. To copy pixels between buffers inside your program instead of to a file, SaveBuffer still works too.

For the full story, see the Prototyping and Diagnostics guide.

Requires Extended mode.

See also: CaptureFrame, CaptureStatus, CaptureError, Flip, SaveBuffer.

Example

; CaptureScreenshot 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

; A trophy worth photographing
trophy=CreateSphere(24)
EntityColor trophy,255,210,40

While Not KeyDown(1)

    ; Space arms a screenshot of the NEXT presented frame
    If KeyHit(57) Then CaptureScreenshot "capture_example.png"

    TurnEntity trophy,0.5,1.5,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: screenshot   Esc: exit"
    ; CaptureStatus reports 0 idle, 1 armed, 2 saved, -1 failed
    Select CaptureStatus()
        Case 1
            Text 0,20,"Armed - the next Flip is saved to capture_example.png"
        Case 2
            Text 0,20,"Saved capture_example.png in this example's directory"
        Default
            Text 0,20,"Press Space to save capture_example.png"
    End Select
    If CaptureError()<>"" Then Text 0,40,CaptureError()

    Flip

Wend

End

Index

Blitz3D+ Command Reference

CaptureScreenshot ( file$ )

Parameters

Description

Example