# `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. ## Types ### `Capture` _record_ ```nupp record Capture ready: boolean end ``` A requested frame. The host completes it after rendering. #### Fields ##### `ready` ```nupp ready: boolean ``` Read-only to callers. True after completion, including failure. ## Functions ### `cancelPending` _function_ ```nupp function cancelPending(): nil ``` Releases outstanding requests when the host session closes. #### Returns | Type | Description | | --- | --- | | `nil` | | ### `complete` _function_ ```nupp 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 | Name | Type | Description | | --- | --- | --- | | `id` | `integer` | | | `width` | `integer` | | | `height` | `integer` | | | `rgba` | `string` | | | `png` | `string` | | | `reason` | `string?` | | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `encode` _function_ ```nupp function encode(capture: Capture): string?, string? ``` Returns PNG bytes, or nil and a pending/readback failure reason. #### Arguments | Name | Type | Description | | --- | --- | --- | | `capture` | `Capture` | | #### Returns | Type | Description | | --- | --- | | `string?` | | | `string?` | | ### `nextRequest` _function_ ```nupp function nextRequest(): integer? ``` Consumes a queued request for the rendering host. #### Returns | Type | Description | | --- | --- | | `integer?` | | ### `pixels` _function_ ```nupp function pixels(capture: Capture): string?, integer, integer, string? ``` Returns top-to-bottom RGBA8 bytes, width, height and an optional failure. #### Arguments | Name | Type | Description | | --- | --- | --- | | `capture` | `Capture` | | #### Returns | Type | Description | | --- | --- | | `string?` | | | `integer` | | | `integer` | | | `string?` | | ### `request` _function_ ```nupp function request(): Capture ``` Requests the next rendered frame; poll `ready` from subsequent updates. #### Returns | Type | Description | | --- | --- | | `Capture` | | ### `save` _function_ ```nupp function save(capture: Capture, path: string): boolean, string? ``` Writes the completed frame as PNG; returns false and a reason on failure. #### Arguments | Name | Type | Description | | --- | --- | --- | | `capture` | `Capture` | | | `path` | `string` | | #### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | |