Morgerion/defold-rtcapture/rtcapture
Capture of arbitrary render targets and of the default framebuffer. Reads COLOR0 of a render target given by a render script, or the screen itself, and returns raw RGB8/RGBA8 pixels as a Defold buffer, or a PNG or JPEG in memory or written to a file. Binding and readback use the portable DMSDK graphics API only, with no backend specific code.
- GitHub: Morgerion/defold-rtcapture — pinned to
1.0.0(released while Defold 1.14.0 was current)- This repo publishes no stable release. Pick a tag from Morgerion/defold-rtcapture tags and add its Source code (zip) URL — for the pinned tag,
https://github.com/Morgerion/defold-rtcapture/archive/refs/tags/1.0.0.zip— togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as rtcapture from "rtcapture"
- This repo publishes no stable release. Pick a tag from Morgerion/defold-rtcapture tags and add its Source code (zip) URL — for the pinned tag,
- Asset Portal: defold-rtcapture
Functions
rtcapture.capture(target: number, options: table, callback: function): LuaMultiReturn<[number, string, string]>rtcapture.capture_sync(target: number, options: table): LuaMultiReturn<[table, string, string]>rtcapture.encode(frame_id: number, options: table): LuaMultiReturn<[table, string, string]>rtcapture.release_frame(frame_id?: number): booleanrtcapture.cancel(request_id: number): booleanrtcapture.cancel_all(): numberrtcapture.invalidate_render_targets(): numberrtcapture.decode_jpeg(data: string, options?: table): LuaMultiReturn<[table, string, string]>rtcapture.get_render_target_size(target: number): LuaMultiReturn<[number, number]>rtcapture.set_debug_logging(enabled: boolean)rtcapture.get_capabilities(): tablertcapture.debug_target(target: number, label?: string): table
rtcapture.capture(target: number, options: table, callback: function): LuaMultiReturn<[number, string, string]>
Queue a readback of the given render target. The readback runs in the post-render phase of the current frame, so call this from the render script that owns the target and in the same frame the target was drawn. The extension does not own the target and cannot detect that it was deleted or resized after the request.
rtcapture.capture(self.preview_rt, {
format = "raw",
channels = 4,
tag = "save_slot_3",
}, function(_, result)
if result.ok then
-- result.buffer holds RGBA8 pixels of the render target
else
print(result.error, result.message)
end
end)
-- screen grab straight to a file, from any script
rtcapture.capture(rtcapture.RENDER_TARGET_DEFAULT, {
format = "png",
path = sys.get_save_file("my_game", "screenshot.png"),
}, function(_, result)
print(result.ok, result.path, result.encoded_size)
end)Parameters
target:number— The value returned byrender.render_target(), orrtcapture.RENDER_TARGET_DEFAULTfor the main screen framebuffer. The screen can be captured from any script; a render target must come from the render script that owns it.options:table—format-"raw"(default) for pixels in a Defold buffer,"hold"to keep the pixels inside the extension and get aframe_idforencode,"png"or"jpeg". Use"hold"to spread a capture over two frames: the frame that reads pays for the readback only, and the downscale and the encoding happen on the next frame, without a multi megabyte buffer travelling through Lua in between.max_width- target width of the resulting image. The extension picks the integer box filter factor itself, because only it knows the size of the region it read. Rounding is down, with a minimum of 1, so the result can be slightly wider than asked:3840withmax_width = 600gives640. Without this option the image keeps the size of the region that was read.path- encoded formats only. When given, the image is written to that file and is not copied into a Lua string. The file is written throughpath .. ".tmp"and only then replaces the destination.channels-4for RGBA8 or3for RGB8 with alpha discarded. Defaults to4, or to3for JPEG, which cannot store alpha anyway. PNG keeps alpha losslessly for four channels and writes a true 24bpp PNG for three.quality- JPEG only,1..100, default85.subsampling- JPEG only,"444","422"or"420", default"420". Use"444"for text and interface, where chroma subsampling produces coloured fringes.progressive- JPEG only, defaultfalse. Encodes noticeably slower and decodes slower, with little size benefit for local previews.optimize- JPEG only, defaultfalse. Optimized Huffman tables cost encoding time.alpha_mode- JPEG from four channels."discard"(default) ignores alpha, so transparent areas keep whatever colour they hold."composite"blends ontobackgroundfirst.background- table withr,g,bin0..255, used byalpha_mode = "composite". Defaults to black.x,y,width,height- rectangle to read, with the origin in the top left corner of the target, matching the orientation of the returned image.xandydefault to0;widthandheightdefault to the rest of the target. A rectangle that leaves the target is rejected, never clamped.flip_y- flip rows vertically,falseby default. The default was measured: on the OpenGL adapterReadPixelsalready returns top-down rows.tag- any Lua value, returned unchanged in the result so a caller can correlate the result with its own request.callback:function— Called from post-render with one result table.self:object— The calling script instance.result:table— Containsok,request_id,tag,format,channels,x,y,width,height,image_width,image_height,target_width,target_height,byte_size,encoded_size,request_to_post_render_ms,readback_ms,convert_ms,downscale_ms,encode_ms,write_msandtotal_ms, pluspathwhen one was given.widthandheightdescribe the region that was read, whileimage_widthandimage_heightdescribe the image that came out of it - the two differ oncemax_widthis used. On success a raw capture also containsbuffer, a Defold buffer whose single stream isrgbaofUINT8x4, orrgbofUINT8x3 when three channels were requested; a held capture containsframe_idand no pixels at all; an encoded capture without apathcontains the encoded bytes in the binary stringdata. On failure the result containserrorandmessageinstead.
Returns
request_id:number— Monotonic id of the accepted request, ornilwhen the request was rejected.error:string— Error code when the request was rejected, otherwisenil.message:string— Human readable reason when the request was rejected, otherwisenil.
rtcapture.capture_sync(target: number, options: table): LuaMultiReturn<[table, string, string]>
Read the given target immediately instead of waiting for post render. Takes the same options as capture and returns the same result table, only as a direct return value. Use it where no further post render will happen - the save written from the final() of a game script when the window is closing is the case this exists for, since a queued request there would never run. A render target still has to be captured from the render script that owns it and in the frame it was drawn; the screen framebuffer can be captured from anywhere.
-- сохранение при закрытии игры: post-render уже не наступит
local result = rtcapture.capture_sync(rtcapture.RENDER_TARGET_DEFAULT, {
format = "jpeg",
max_width = 600,
quality = 85,
})
if result and result.ok then
save_preview = result.data
endParameters
target:number— The value returned byrender.render_target(), orrtcapture.RENDER_TARGET_DEFAULT.options:table— The same optionscaptureaccepts.
Returns
result:table— The same result tablecapturepasses to its callback, ornilwhen the request was rejected outright.error:string— Error code when the request was rejected, otherwisenil.message:string— Human readable reason when the request was rejected, otherwisenil.
rtcapture.encode(frame_id: number, options: table): LuaMultiReturn<[table, string, string]>
Downscale and encode a frame that a format = "hold" capture left inside the extension. This is the second phase of a capture spread over two frames. The frame stays held after encoding, so the same shot can be encoded more than once - to compare formats, for example - and is freed by release_frame. Compositing is not available here the held pixels have already been converted, so alpha_mode = "composite" only works at capture time.
-- кадр A: только чтение пикселей
rtcapture.capture(rtcapture.RENDER_TARGET_DEFAULT, {
format = "hold",
channels = 3,
}, function(_, result)
held_frame_id = result.ok and result.frame_id or nil
end)
-- кадр B: усреднение и упаковка
local encoded = rtcapture.encode(held_frame_id, {
format = "jpeg",
max_width = 600,
})
rtcapture.release_frame(held_frame_id)Parameters
frame_id:number— Theframe_idfrom the result of the held capture.options:table—format(required,"png"or"jpeg"),path,max_width,quality,subsampling,progressive,optimizeandtag- the same meaning they have incapture.
Returns
result:table— The same result table shape ascapture, withdownscale_ms,encode_ms,write_msandtotal_msfilled for this phase.nilwhen the call was rejected.error:string—ERR_NO_HELD_FRAMEwhen no frame with that id is held, otherwisenil.message:string— Human readable reason when the call was rejected, otherwisenil.
rtcapture.release_frame(frame_id?: number): boolean
Free the frame held by a format = "hold" capture. Call it once the frame has been encoded, or when the encoding is abandoned - otherwise a full screen frame stays in the memory of the extension until the next held capture replaces it. Only one frame is held at a time.
Parameters
frame_id?:number— The id to free. Without it the currently held frame is freed, whatever its id.
Returns
released:boolean— True when a frame was actually freed.
rtcapture.cancel(request_id: number): boolean
Drop a pending capture request. Its callback is never invoked, because cancelling was the caller's own decision. Everything the request owned is released immediately.
Parameters
request_id:number— The id returned bycapture.
Returns
cancelled:boolean— True when a pending request with that id was found and removed.
rtcapture.cancel_all(): number
Drop every pending capture request. No callbacks are invoked.
Returns
count:number— How many requests were dropped.
rtcapture.invalidate_render_targets(): number
Declare that every render target handed to the extension so far is gone. Call this right after recreating render targets, for example when the window was resized. The extension cannot detect this on its own - the public DMSDK has no way to test whether a handle is still alive. Requests made before the call stay in the queue and complete with ERR_RENDER_TARGET_DESTROYED rather than reading through a dead handle, so every accepted request still gets exactly one answer. Requests for rtcapture.RENDER_TARGET_DEFAULT are unaffected.
Returns
affected:number— How many pending requests will now fail.
rtcapture.decode_jpeg(data: string, options?: table): LuaMultiReturn<[table, string, string]>
Decode JPEG bytes into a Defold buffer. Synchronous, and callable from any script. The header is validated before anything is allocated dimensions, data precision and colour space are checked first, and images above 64 million pixels are refused. JPEG stores no alpha, so a four channel result is always fully opaque.
local image, err = rtcapture.decode_jpeg(jpeg_bytes, { channels = 4 })
if image then
-- resource.create_texture needs a game object context and does not work
-- from a render script.
local texture = resource.create_texture("/preview.texturec", {
type = graphics.TEXTURE_TYPE_2D,
width = image.width,
height = image.height,
format = graphics.TEXTURE_FORMAT_RGBA,
}, image.buffer)
endParameters
data:string— Binary JPEG data.options?:table—channels-4for RGBA8 (default) or3for RGB8.
Returns
image:table— Containswidth,height,channels,byte_size,decode_msandbuffer, a Defold buffer whose single stream isrgbaofUINT8x4, orrgbofUINT8x3.nilwhen decoding failed.error:string— Error code when decoding failed, otherwisenil.message:string— Human readable reason when decoding failed, otherwisenil.
rtcapture.get_render_target_size(target: number): LuaMultiReturn<[number, number]>
Report the size of the COLOR0 attachment of the given render target, so calling code can compute a rectangle without repeating the parameters the render script created the target with.
Parameters
target:number— The value returned byrender.render_target().
Returns
width:numberheight:number
rtcapture.set_debug_logging(enabled: boolean)
Enable the detailed capture log. Off by default. The log line reports the raw first pixel before conversion, the viewport before and after the readback, and per stage timings.
Parameters
enabled:boolean
rtcapture.get_capabilities(): table
Report what the extension can currently do on the installed graphics adapter. Only verified capabilities are listed; stages that are not implemented yet do not appear as fields.
Returns
capabilities:table— Containsavailable,adapter("opengl","vulkan","directx", ...) anddebug_target.
rtcapture.debug_target(target: number, label?: string): table
Identify an arbitrary render target without reading its pixels. Call it from the render script that owns the target, in the same frame, so the handle is guaranteed to be alive.
local info = rtcapture.debug_target(self.preview_rt, "preview_rt")
print(info.handle_hex, info.color0_width, info.color0_height)Parameters
target:number— The value returned byrender.render_target().label?:string— Name used in the log line so several targets can be told apart.
Returns
info:table— Containslabel,handle,handle_hex,color0_width,color0_heightandadapter.
Constants
rtcapture.RENDER_TARGET_DEFAULT
Pass as the capture target to read the main screen framebuffer instead of a render target. Its value is 0, the same one render.RENDER_TARGET_DEFAULT uses in a render script.