screenshot

stable

Helpers for configuring screen capture regions, querying pixel formats, inspecting display dimensions, and preparing save operations.

use plugin screenshot::{create_capture_config, full_screen_config, region_to_bytes_placeholder, …}

8 functions Systems

/ filter jk navigate Esc clear

Functions (8)

create_capture_config Build a region capture config table
full_screen_config Build a full-screen capture config table
region_to_bytes_placeholder Placeholder capture result from a config
pixel_format_info Get bytes-per-pixel info for a pixel format
save_to_file Build a save descriptor for a config
get_dimensions Extract width, height, and pixel count
display_info Return simulated display metadata
supported_formats List supported pixel output formats

Overview

screenshot is a dependency-free toolkit for describing screen captures rather than performing them. Every function takes and returns ordinary tables: you build a capture configuration (a region or a full screen), inspect it, and prepare a save descriptor — all as plain data, with no external graphics backend involved. The capture and save functions are placeholders that echo their inputs back as structured results, so the plugin is ideal for wiring up a capture pipeline, testing config flows, or computing pixel buffer sizes before a real backend is connected.

The mental model is: create a config with create_capture_config or full_screen_config, query it with get_dimensions and pixel_format_info, then hand it to region_to_bytes_placeholder or save_to_file. Display and format metadata come from display_info and supported_formats.

Common patterns

Build a full-screen config sized to the primary display, then save it:

use plugin screenshot::{display_info, full_screen_config, save_to_file}

let display = display_info()
let cfg = full_screen_config(display["width"], display["height"])
let desc = save_to_file(cfg, "/tmp/screen.bmp", "bmp")
print("saved {desc["width"]}x{desc["height"]} to {desc["path"]}")

Compute the raw byte size of a region capture from its pixel format:

use plugin screenshot::{create_capture_config, get_dimensions, pixel_format_info}

let cfg = create_capture_config(0, 0, 1280, 720)
let dims = get_dimensions(cfg)
let fmt = pixel_format_info("rgba")
let bytes = dims["pixels"] * fmt["bytes_per_pixel"]
print("{dims["pixels"]} pixels = {bytes} bytes in rgba")

Capture a region into a placeholder buffer and confirm its format:

use plugin screenshot::{create_capture_config, region_to_bytes_placeholder}

let cfg = create_capture_config(100, 100, 800, 600)
let buf = region_to_bytes_placeholder(cfg)
print("captured {buf["width"]}x{buf["height"]} as {buf["format"]}")

create_capture_config(x, y, w, h) → table

Build a region capture config table

Creates a capture configuration table describing a screen region. The returned table has x, y, width, height, and type = "region" fields.

use plugin screenshot::{create_capture_config}

let cfg = create_capture_config(100, 200, 640, 480)
print(cfg["width"])   // 640
print(cfg["height"])  // 480
print(cfg["type"])    // region

The config is plain data, so you can immediately derive its pixel buffer size:

use plugin screenshot::{create_capture_config, get_dimensions}

let cfg = create_capture_config(50, 50, 200, 150)
print("pixels: {get_dimensions(cfg)["pixels"]}")  // 30000

full_screen_config(width, height) → table

Build a full-screen capture config table

Creates a capture configuration for the full screen. The origin is fixed at (0, 0) and type is set to "fullscreen".

use plugin screenshot::{full_screen_config}

let cfg = full_screen_config(1920, 1080)
print(cfg["x"])      // 0
print(cfg["type"])   // fullscreen

Size it directly from the reported display metadata:

use plugin screenshot::{display_info, full_screen_config}

let d = display_info()
let cfg = full_screen_config(d["width"], d["height"])
print("{cfg["width"]}x{cfg["height"]}")  // 1920x1080

region_to_bytes_placeholder(config) → table

Placeholder capture result from a config

Returns a placeholder capture result from a config table. Includes width, height, format = "rgba", and placeholder = true. Use during development before wiring up a real capture backend.

use plugin screenshot::{create_capture_config, region_to_bytes_placeholder}

let cfg = create_capture_config(0, 0, 800, 600)
let result = region_to_bytes_placeholder(cfg)
print(result["format"])       // rgba
print(result["placeholder"])  // true
print(result["width"])        // 800

It works with a full-screen config just as well, copying its dimensions through:

use plugin screenshot::{full_screen_config, region_to_bytes_placeholder}

let buf = region_to_bytes_placeholder(full_screen_config(2560, 1440))
print("{buf["width"]}x{buf["height"]}")  // 2560x1440

pixel_format_info(format_str) → table

Get bytes-per-pixel info for a pixel format

Returns the bytes-per-pixel count and channel count for a named pixel format. Supported formats: "rgba", "rgb", "bgra", "bgr", "gray", "greyscale", "gray_alpha".

use plugin screenshot::{pixel_format_info}

let info = pixel_format_info("rgba")
print(info["bytes_per_pixel"])  // 4
print(info["channels"])         // 4

let gray = pixel_format_info("gray")
print(gray["bytes_per_pixel"])  // 1

Combine it with get_dimensions to size a raw pixel buffer exactly:

use plugin screenshot::{create_capture_config, get_dimensions, pixel_format_info}

let dims = get_dimensions(create_capture_config(0, 0, 640, 480))
let bpp = pixel_format_info("bgra")["bytes_per_pixel"]
print("buffer bytes: {dims["pixels"] * bpp}")  // 1228800

save_to_file(config, path, format) → table

Build a save descriptor for a config

Builds a save descriptor combining the config dimensions with the target file path and format string. Does not perform actual file I/O. Returns a table with path, format, width, height, and saved = true.

use plugin screenshot::{full_screen_config, save_to_file}

let cfg = full_screen_config(1920, 1080)
let desc = save_to_file(cfg, "/tmp/capture.bmp", "bmp")
print(desc["path"])    // /tmp/capture.bmp
print(desc["format"])  // bmp
print(desc["saved"])   // true

get_dimensions(config) → table

Extract width, height, and pixel count

Extracts width, height, and pixels (width * height) from a capture config table.

use plugin screenshot::{create_capture_config, get_dimensions}

let cfg = create_capture_config(0, 0, 320, 240)
let dims = get_dimensions(cfg)
print(dims["width"])   // 320
print(dims["height"])  // 240
print(dims["pixels"])  // 76800

display_info() → table

Return simulated display metadata

Returns simulated display metadata with primary, width, height, and scale_factor fields. Currently returns fixed values for a 1920x1080 primary display at 1.0 scale.

use plugin screenshot::{display_info}

let info = display_info()
print(info["width"])         // 1920
print(info["height"])        // 1080
print(info["primary"])       // true
print(info["scale_factor"])  // 1.0

supported_formats() → table

List supported pixel output formats

Returns a 1-indexed table of supported pixel output format names.

use plugin screenshot::{supported_formats}

let fmts = supported_formats()
print(fmts[1])  // bmp
print(fmts[2])  // ppm
print(fmts[3])  // raw
print(fmts[4])  // rgba

View source code