| file$ - base name for the pair of output files, without an extension; the command writes file$.png and file$.txt |
|
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. See also: CaptureScreenshot, CaptureStatus, CaptureError, DrawRenderStats, CountDiagnostics. |
; CaptureFrame Example
; --------------------
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