Blitz3D+ Command Reference

CaptureFrame ( file$ )

Parameters

file$ - base name for the pair of output files, without an extension; the command writes file$.png and file$.txt

Description

Arms a capture of the next presented frame as a PNG image plus a text report of renderer state. Returns True when the request is accepted.

CaptureFrame is CaptureScreenshot's big sibling for bug hunting: one call records both what the frame looked like and what the renderer was doing at the time. Pass a base name - "bugreport" writes bugreport.png and bugreport.txt. Do not include an extension; the .png and .txt are added for you.

The text report covers the capture time, display and internal resolutions, graphics adapter, anti-alias mode, render scale, VSync and frame limit, then the frame's counters: triangles, draw calls, instances, skinning work, texture, geometry and target memory, shadow statistics, post-processing state, culling and LOD totals, terrain and particle totals, frame and render times - and finishes with every record in the diagnostics store. When a tester says "it went weird here", this file is the context you wish you had.

The report also lists resident planar reflection captures separately: dimensions, colour/depth allocation bytes, submitted and timed views, latest draw/triangle counts, renderer CPU time and retired GPU/shadow timings. These are recent samples, not benchmark averages. Resident resources can include a capture retained until earlier GPU work finishes; this is not an enabled-plane count. Allocation bytes cover the capture colour and depth resources, excluding descriptors and other rendering resources.

Like CaptureScreenshot, the capture is armed and fires at the next Flip: poll CaptureStatus for 1 (armed), 2 (success) or -1 (failed), with CaptureError holding the reason on failure. One capture may be armed at a time, and Graphics3D must be active. If the image saves but the report cannot be written, the capture counts as failed.

Requires Extended mode.

See also: CaptureScreenshot, CaptureStatus, CaptureError, DrawRenderStats, CountDiagnostics.

Example

; CaptureFrame 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 small scene worth reporting on
trophy=CreateSphere(24)
EntityColor trophy,60,170,255

While Not KeyDown(1)

    ; Space arms a screenshot PLUS a text diagnostic report for the next Flip
    If KeyHit(57) Then accepted=CaptureFrame("capture_report")

    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: capture frame   Esc: exit"
    ; CaptureStatus reports 0 idle, 1 armed, 2 saved, -1 failed
    Select CaptureStatus()
        Case 1
            Text 0,20,"Armed - the next Flip writes capture_report.png and its report"
        Case 2
            Text 0,20,"Wrote capture_report.png plus a text report of settings and counters"
        Default
            Text 0,20,"Press Space to capture the frame with a diagnostic report"
    End Select
    If CaptureError()<>"" Then Text 0,40,CaptureError()

    Flip

Wend

End

Index