tecs.gfx.screenshot

Capture the next presented frame, including UI and post-processing.

request() queues one readback. Check capture.ready in a later update before calling pixels, encode, or save. Only requested frames allocate readback storage or wait for the GPU. RGBA pixels run top to bottom; captures are opaque, matching the displayed image rather than the composite target's internal alpha.

Module contents

Types

TypeKindDescription
CapturerecordA requested frame.

Functions

FunctionKindDescription
cancelPendingfunctionReleases outstanding requests when the host session closes.
completefunctionCompletes a host readback and releases the registry's reference.
encodefunctionReturns PNG bytes, or nil and a pending/readback failure reason.
nextRequestfunctionConsumes a queued request for the rendering host.
pixelsfunctionReturns top-to-bottom RGBA8 bytes, width, height and an optional failure.
requestfunctionRequests the next rendered frame; poll ready from subsequent updates.
savefunctionWrites the completed frame as PNG; returns false and a reason on failure.

Types#

Capturerecord#

record Capture
    ready: boolean
end

A requested frame. The host completes it after rendering.

Fields

ready#
ready: boolean

Read-only to callers. True after completion, including failure.

Functions#

cancelPendingfunction#

function cancelPending(): nil

Releases outstanding requests when the host session closes.

Returns

TypeDescription
nil

completefunction#

function complete(id: integer, width: integer, height: integer, rgba: string, png: string, reason: string?): nil

Completes a host readback and releases the registry's reference.

Arguments

NameTypeDescription
idinteger
widthinteger
heightinteger
rgbastring
pngstring
reasonstring?

Returns

TypeDescription
nil

encodefunction#

function encode(capture: Capture): string?, string?

Returns PNG bytes, or nil and a pending/readback failure reason.

Arguments

NameTypeDescription
captureCapture

Returns

TypeDescription
string?
string?

nextRequestfunction#

function nextRequest(): integer?

Consumes a queued request for the rendering host.

Returns

TypeDescription
integer?

pixelsfunction#

function pixels(capture: Capture): string?, integer, integer, string?

Returns top-to-bottom RGBA8 bytes, width, height and an optional failure.

Arguments

NameTypeDescription
captureCapture

Returns

TypeDescription
string?
integer
integer
string?

requestfunction#

function request(): Capture

Requests the next rendered frame; poll ready from subsequent updates.

Returns

TypeDescription
Capture

savefunction#

function save(capture: Capture, path: string): boolean, string?

Writes the completed frame as PNG; returns false and a reason on failure.

Arguments

NameTypeDescription
captureCapture
pathstring

Returns

TypeDescription
boolean
string?