Skip to Content
defold-typescript libraries
Morgerion

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)
    1. 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 — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as rtcapture from "rtcapture"
  • Asset Portal: defold-rtcapture

Functions

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 by render.render_target(), or rtcapture.RENDER_TARGET_DEFAULT for 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 a frame_id for encode, "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: 3840 with max_width = 600 gives 640. 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 through path .. ".tmp" and only then replaces the destination. channels - 4 for RGBA8 or 3 for RGB8 with alpha discarded. Defaults to 4, or to 3 for 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, default 85. subsampling - JPEG only, "444", "422" or "420", default "420". Use "444" for text and interface, where chroma subsampling produces coloured fringes. progressive - JPEG only, default false. Encodes noticeably slower and decodes slower, with little size benefit for local previews. optimize - JPEG only, default false. 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 onto background first. background - table with r, g, b in 0..255, used by alpha_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. x and y default to 0; width and height default to the rest of the target. A rectangle that leaves the target is rejected, never clamped. flip_y - flip rows vertically, false by default. The default was measured: on the OpenGL adapter ReadPixels already 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 — Contains ok, 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_ms and total_ms, plus path when one was given. width and height describe the region that was read, while image_width and image_height describe the image that came out of it - the two differ once max_width is used. On success a raw capture also contains buffer, a Defold buffer whose single stream is rgba of UINT8 x4, or rgb of UINT8 x3 when three channels were requested; a held capture contains frame_id and no pixels at all; an encoded capture without a path contains the encoded bytes in the binary string data. On failure the result contains error and message instead.

Returns

  • request_id: number — Monotonic id of the accepted request, or nil when the request was rejected.
  • error: string — Error code when the request was rejected, otherwise nil.
  • message: string — Human readable reason when the request was rejected, otherwise nil.

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
end

Parameters

  • target: number — The value returned by render.render_target(), or rtcapture.RENDER_TARGET_DEFAULT.
  • options: table — The same options capture accepts.

Returns

  • result: table — The same result table capture passes to its callback, or nil when the request was rejected outright.
  • error: string — Error code when the request was rejected, otherwise nil.
  • message: string — Human readable reason when the request was rejected, otherwise nil.

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 — The frame_id from the result of the held capture.
  • options: table — format (required, "png" or "jpeg"), path, max_width, quality, subsampling, progressive, optimize and tag - the same meaning they have in capture.

Returns

  • result: table — The same result table shape as capture, with downscale_ms, encode_ms, write_ms and total_ms filled for this phase. nil when the call was rejected.
  • error: string — ERR_NO_HELD_FRAME when no frame with that id is held, otherwise nil.
  • message: string — Human readable reason when the call was rejected, otherwise nil.

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 by capture.

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)
end

Parameters

  • data: string — Binary JPEG data.
  • options?: table — channels - 4 for RGBA8 (default) or 3 for RGB8.

Returns

  • image: table — Contains width, height, channels, byte_size, decode_ms and buffer, a Defold buffer whose single stream is rgba of UINT8 x4, or rgb of UINT8 x3. nil when decoding failed.
  • error: string — Error code when decoding failed, otherwise nil.
  • message: string — Human readable reason when decoding failed, otherwise nil.

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 by render.render_target().

Returns

  • width: number
  • height: 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 — Contains available, adapter ("opengl", "vulkan", "directx", ...) and debug_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 by render.render_target().
  • label?: string — Name used in the log line so several targets can be told apart.

Returns

  • info: table — Contains label, handle, handle_hex, color0_width, color0_height and adapter.

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.

On this page