TgfxOffscreenSurface
A retained GPU surface no view owns - the render target for headless work.
renderToImage is one-shot: every call allocates a surface, compiles the
program, renders, reads back, and throws it all away. This object keeps the
surface and the compiled program alive, so an iterate-and-export loop pays
per frame only what an on-screen canvas does: slot resolution and a render
pass, all on a dedicated offscreen worker thread. Readback happens only when
toImage or save asks.
setScene / setValues / setStringValues are byte-for-byte the
TgfxViewMethods contract, so a surface and a view are interchangeable
scene targets - Scene.attach(surface) and the Reanimated drivers work
unchanged. As a Nitro object it boxes with NitroModules.box(), so a
worklet runtime can own the whole mutate-flush loop.
The colour space is a createOffscreenSurface option rather than a method:
a surface's space is fixed at creation, exactly like a view's.
Extends
HybridObject<{android:"c++";ios:"c++"; }>
Properties
height
readonly height: number;width
readonly width: number;Logical points, as given at creation.
Methods
flush()
flush(): void;Render the staged state now. Stages and wakes the offscreen worker - it never renders on the calling thread, so a UI-runtime caller pays a method call, not a GPU pass. Consecutive flushes coalesce: the worker draws the latest state, and readbacks only run for pending toImage/save.
Returns
void
hitTest()
hitTest(
x: number,
y: number,
precise: boolean): number[];Index paths under a point in canvas points, flattened [depth, i0, i1, …],
topmost first - the view's hitTest, answered headless from the same
staged scene and viewport. The program compiles on the worker's first
drain, so a hit test racing the very first flush() can answer empty.
Parameters
x
number
y
number
precise
boolean
Returns
number[]
save()
save(
path: string,
format?: string,
quality?: number): Promise<void>;Encode the current frame straight to path - png (default) / jpeg / webp,
quality 1-100. The bytes never enter JS, and no image handle is minted.
Parameters
path
string
format?
string
quality?
number
Returns
Promise<void>
setScene()
setScene(scene: ArrayBuffer, strings: string[]): void;Stage a draw program. Same contract as the view: the buffer is only valid
for the duration of the call, and strings is a packStringTable delta
against the table this surface already holds.
Parameters
scene
ArrayBuffer
strings
string[]
Returns
void
setStringValues()
setStringValues(indices: number[], values: string[]): void;Sparse writes into the string-slot array (live text and path data).
Parameters
indices
number[]
values
string[]
Returns
void
setValues()
setValues(values: number[]): void;Patch the animated value slots. Worklet-safe through a boxed surface.
Parameters
values
number[]
Returns
void
setViewport()
setViewport(viewport: number[]): void;[zoom, x, y], the view's viewport contract - a zoomed crop export.
Parameters
viewport
number[]
Returns
void
toImage()
toImage(): Promise<TgfxImage>;The current frame as a registered image handle, read back to CPU pixels
(a texture cannot cross out of the offscreen context). Renders the latest
staged state first, so flush() beforehand is not required.
Returns
Promise<TgfxImage>