CaptureError$ ( )

Parameters

None.

Description

Returns the message explaining the latest rejected or failed capture, or an empty string.

When CaptureScreenshot or CaptureFrame returns False, or CaptureStatus reports -1, CaptureError tells you why in a single human-readable line: an unsupported file extension, no Graphics3D active, a capture already armed, a file that could not be written. Show it on screen or log it, and a failed screenshot key stops being a mystery.

After a successful capture the message is cleared, so an empty string means "nothing went wrong" - either the last capture succeeded or none was requested. Note the one soft case: asking for a capture while another is already armed returns False and sets this message, but leaves CaptureStatus at 1 because the original request is still armed and healthy.

Capture failures are also filed as error records in the diagnostics store (category "capture"), so they show up in DrawDiagnostics and in CaptureFrame reports.

See also: CaptureStatus, CaptureScreenshot, CaptureFrame, CountDiagnostics.

Example

; CaptureError Example
; --------------------

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,120,220,120

While Not KeyDown(1)

    ; Space arms a valid PNG screenshot
    If KeyHit(57) Then CaptureScreenshot "capture_example.png"

    ; J tries an unsupported .jpg capture, which is rejected
    If KeyHit(36) Then CaptureScreenshot "capture_example.jpg"

    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: PNG capture   J: JPG capture   Esc: exit"
    ; CaptureError explains the latest rejected or failed capture
    If CaptureError()<>"" Then Text 0,20,"CaptureError() = "+CaptureError() Else Text 0,20,"CaptureError() is empty - no capture has failed"

    Flip

Wend

End

Index