pyvterm 0.1.0__py3-none-any.whl

pyvterm/__init__.py

@@ -0,0 +1,66 @@
+"""pyvterm — drive a pitrex/Vectrex over a serial port from Python.
+
+pyvterm speaks the **USB-DVG / *vecterm* serial protocol** used by the
+`gtoal/pitrex <https://github.com/gtoal/pitrex>`_ project: the same wire
+format a custom MAME build uses to push vector frames to a Vectrex. With it
+you can act as the "custom MAME" and draw vectors on real hardware from
+Python.
+
+Quick start
+-----------
+>>> from pyvterm import VectorTerminal
+>>> with VectorTerminal(port="/dev/ttyACM0") as vt:   # doctest: +SKIP
+...     with vt.frame():
+...         vt.set_intensity(15)
+...         vt.polyline([(0, 0), (100, 100), (-100, 100)], closed=True)
+
+For tests and dry runs, pass a :class:`MemoryTransport` instead of a port.
+"""
+
+from __future__ import annotations
+
+from . import geometry, protocol
+from .frame import FrameBuilder
+from .geometry import clip_line, vector_length
+from .protocol import (
+    DEFAULT_BOUNDS,
+    DVG_RENDER_QUALITY,
+    DVG_RES_MAX,
+    DVG_RES_MIN,
+    Bounds,
+    Flag,
+)
+from .terminal import VectorTerminal
+from .transport import (
+    DEFAULT_BAUDRATE,
+    DEFAULT_PORT,
+    MemoryTransport,
+    SerialTransport,
+    Transport,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # high level
+    "VectorTerminal",
+    "FrameBuilder",
+    # transports
+    "Transport",
+    "SerialTransport",
+    "MemoryTransport",
+    "DEFAULT_PORT",
+    "DEFAULT_BAUDRATE",
+    # protocol + geometry
+    "protocol",
+    "geometry",
+    "Flag",
+    "Bounds",
+    "DEFAULT_BOUNDS",
+    "DVG_RES_MIN",
+    "DVG_RES_MAX",
+    "DVG_RENDER_QUALITY",
+    "clip_line",
+    "vector_length",
+]

pyvterm/frame.py

@@ -0,0 +1,160 @@
+"""Stateful frame assembly.
+
+:class:`FrameBuilder` accumulates colour and vector commands and serialises a
+complete frame to bytes. It is **transport-agnostic and pure** — it never
+touches a serial port — so the exact wire output can be asserted in tests.
+
+The emitted frame layout matches ``zvgFrame.c``'s ``serial_send``::
+
+    [FRAME | total_vector_length]   <- header, written first
+    [RGB ...] [XY ...] [XY ...] ... <- body (colours and vectors)
+    [QUALITY | value]
+    [COMPLETE]
+"""
+
+from __future__ import annotations
+
+from . import protocol
+from .geometry import clip_line, vector_length
+from .protocol import DEFAULT_BOUNDS, DVG_RENDER_QUALITY, DVG_RES_MAX, DVG_RES_MIN, Bounds
+
+__all__ = ["FrameBuilder"]
+
+Window = tuple[int, int, int, int]
+
+
+def _clamp(value: int, low: int, high: int) -> int:
+    return max(low, min(high, value))
+
+
+class FrameBuilder:
+    """Accumulate a single frame of vectors and serialise it to bytes.
+
+    Parameters
+    ----------
+    bounds:
+        Host coordinate space mapped onto the device grid.
+    clip_window:
+        ``(x_min, y_min, x_max, y_max)`` clip rectangle in host coordinates.
+        Defaults to the full ``bounds`` (the C code requires the caller to set
+        this; we default it so drawing works out of the box).
+    quality:
+        Value sent in the per-frame ``QUALITY`` command.
+    monochrome:
+        Set the monochrome bit in the ``COMPLETE`` marker.
+    """
+
+    def __init__(
+        self,
+        bounds: Bounds = DEFAULT_BOUNDS,
+        clip_window: Window | None = None,
+        quality: int = DVG_RENDER_QUALITY,
+        monochrome: bool = False,
+    ) -> None:
+        self.bounds = bounds
+        self.quality = quality
+        self.monochrome = monochrome
+        if clip_window is None:
+            clip_window = (bounds.x_min, bounds.y_min, bounds.x_max, bounds.y_max)
+        self.clip_window: Window = clip_window
+        self.reset()
+
+    def reset(self) -> None:
+        """Discard all accumulated commands and start a fresh frame."""
+        self._body = bytearray()
+        self._vector_length = 0
+        self._last: tuple[int, int] | None = None  # last device-space endpoint
+        self._last_black = True  # colour starts at (0, 0, 0)
+        self._count = 0
+
+    # -- properties --------------------------------------------------------
+
+    @property
+    def vector_count(self) -> int:
+        """Number of vectors accepted into the current frame."""
+        return self._count
+
+    @property
+    def total_length(self) -> int:
+        """Accumulated beam-travel length (sent in the FRAME header)."""
+        return self._vector_length
+
+    def __len__(self) -> int:
+        return self._count
+
+    # -- drawing -----------------------------------------------------------
+
+    def set_clip_window(self, x_min: int, y_min: int, x_max: int, y_max: int) -> None:
+        """Set the clip rectangle in host coordinates (``zvgFrameSetClipWin``)."""
+        self.clip_window = (x_min, y_min, x_max, y_max)
+
+    def set_rgb(self, r: int, g: int, b: int) -> None:
+        """Set the colour of subsequent vectors from ~4-bit channels.
+
+        Mirrors ``zvgFrameSetRGB15``: each channel is scaled ``<< 4`` and
+        clamped to 255. A colour of ``(0, 0, 0)`` blanks subsequent draws.
+        """
+        r8 = protocol.scale_color(r)
+        g8 = protocol.scale_color(g)
+        b8 = protocol.scale_color(b)
+        self._last_black = r8 == 0 and g8 == 0 and b8 == 0
+        self._body += protocol.rgb(r8, g8, b8)
+
+    def vector(self, x0: float, y0: float, x1: float, y1: float) -> bool:
+        """Add a vector from ``(x0, y0)`` to ``(x1, y1)`` in host coordinates.
+
+        The line is clipped to the clip window; returns ``False`` (emitting
+        nothing) when it lies entirely off-screen. A beam-off reposition is
+        inserted automatically when the start does not continue the previous
+        vector, so connected polylines cost only one extra move overall.
+        """
+        clipped = clip_line(x0, y0, x1, y1, self.clip_window)
+        if clipped is None:
+            return False
+        cx0, cy0, cx1, cy1 = clipped
+
+        start = (
+            _clamp(self.bounds.conv_x(cx0), DVG_RES_MIN, DVG_RES_MAX),
+            _clamp(self.bounds.conv_y(cy0), DVG_RES_MIN, DVG_RES_MAX),
+        )
+        end = (
+            _clamp(self.bounds.conv_x(cx1), DVG_RES_MIN, DVG_RES_MAX),
+            _clamp(self.bounds.conv_y(cy1), DVG_RES_MIN, DVG_RES_MAX),
+        )
+
+        if self._last is not None:
+            self._vector_length += vector_length(self._last[0], self._last[1], *start)
+        self._vector_length += vector_length(start[0], start[1], end[0], end[1])
+
+        if self._last != start:
+            # Reposition the beam (always off) to the start of this vector.
+            self._body += protocol.xy(start[0], start[1], blank=True)
+        self._body += protocol.xy(end[0], end[1], blank=self._last_black)
+
+        self._last = end
+        self._count += 1
+        return True
+
+    def polyline(self, points: list[tuple[float, float]], closed: bool = False) -> int:
+        """Draw a connected sequence of points; returns the vectors emitted."""
+        emitted = 0
+        for (x0, y0), (x1, y1) in zip(points, points[1:]):
+            if self.vector(x0, y0, x1, y1):
+                emitted += 1
+        if closed and len(points) > 2:
+            x0, y0 = points[-1]
+            x1, y1 = points[0]
+            if self.vector(x0, y0, x1, y1):
+                emitted += 1
+        return emitted
+
+    # -- serialisation -----------------------------------------------------
+
+    def to_bytes(self) -> bytes:
+        """Serialise the accumulated frame (header + body + quality + complete)."""
+        out = bytearray()
+        out += protocol.frame_header(self._vector_length)
+        out += self._body
+        out += protocol.quality(self.quality)
+        out += protocol.complete(self.monochrome)
+        return bytes(out)

pyvterm/geometry.py

@@ -0,0 +1,81 @@
+"""Geometry helpers used by the frame builder.
+
+Pure functions only — no hardware or I/O. ``clip_line`` is a direct port of
+the Cohen-Sutherland clipper in ``zvgFrame.c`` (some games emit coordinates
+outside the view window, so vectors must be clipped before transmission).
+"""
+
+from __future__ import annotations
+
+import math
+
+__all__ = ["INSIDE", "LEFT", "RIGHT", "BOTTOM", "TOP", "clip_line", "vector_length"]
+
+# Region codes (matching zvgFrame.c).
+INSIDE = 0
+LEFT = 1
+RIGHT = 2
+BOTTOM = 4
+TOP = 8
+
+Window = tuple[float, float, float, float]  # (x_min, y_min, x_max, y_max)
+Point = tuple[float, float]
+Segment = tuple[float, float, float, float]
+
+
+def _region_code(x: float, y: float, window: Window) -> int:
+    x_min, y_min, x_max, y_max = window
+    code = INSIDE
+    if x < x_min:
+        code |= LEFT
+    elif x > x_max:
+        code |= RIGHT
+    if y < y_min:
+        code |= BOTTOM
+    elif y > y_max:
+        code |= TOP
+    return code
+
+
+def clip_line(x1: float, y1: float, x2: float, y2: float, window: Window) -> Segment | None:
+    """Cohen-Sutherland line clip.
+
+    Returns the clipped ``(x1, y1, x2, y2)`` segment, or ``None`` if the line
+    lies entirely outside ``window`` (``(x_min, y_min, x_max, y_max)``).
+    """
+    x_min, y_min, x_max, y_max = window
+    code1 = _region_code(x1, y1, window)
+    code2 = _region_code(x2, y2, window)
+
+    while True:
+        if code1 == 0 and code2 == 0:
+            return (x1, y1, x2, y2)
+        if code1 & code2:
+            return None
+
+        code_out = code1 or code2
+        x = y = 0.0
+        if code_out & TOP:
+            x = x1 + (x2 - x1) * (y_max - y1) / (y2 - y1)
+            y = y_max
+        elif code_out & BOTTOM:
+            x = x1 + (x2 - x1) * (y_min - y1) / (y2 - y1)
+            y = y_min
+        elif code_out & RIGHT:
+            y = y1 + (y2 - y1) * (x_max - x1) / (x2 - x1)
+            x = x_max
+        elif code_out & LEFT:
+            y = y1 + (y2 - y1) * (x_min - x1) / (x2 - x1)
+            x = x_min
+
+        if code_out == code1:
+            x1, y1 = x, y
+            code1 = _region_code(x1, y1, window)
+        else:
+            x2, y2 = x, y
+            code2 = _region_code(x2, y2, window)
+
+
+def vector_length(x0: float, y0: float, x1: float, y1: float) -> int:
+    """Integer Euclidean length of a segment (``vector_length`` in C)."""
+    return int(math.hypot(x1 - x0, y1 - y0))

pyvterm/preview.py

@@ -0,0 +1,149 @@
+"""Render pyvterm frames as a glowing vector display — previews without hardware.
+
+Optional module: needs the ``preview`` extra (``pip install "pyvterm[preview]"``,
+i.e. numpy + Pillow). It is **not** imported by ``pyvterm`` itself, so the core
+package stays dependency-light.
+
+Frames are decoded from the *actual wire bytes* back into beam segments, so a
+preview shows exactly what the device would draw. Capture frames with a
+:class:`PreviewTransport`, then save an animated PNG::
+
+    from pyvterm import VectorTerminal
+    from pyvterm.preview import PreviewTransport
+
+    preview = PreviewTransport(width=440, height=330)
+    vt = VectorTerminal(transport=preview)
+    for ...:
+        with vt.frame():
+            vt.polyline(points)
+    preview.save_apng("out.png", fps=25)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from . import protocol
+from .protocol import DVG_RES_MAX, Flag
+from .transport import Transport
+
+try:
+    import numpy as np
+    from PIL import Image, ImageDraw, ImageFilter
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(
+        "pyvterm.preview needs the 'preview' extra: pip install 'pyvterm[preview]'"
+    ) from exc
+
+__all__ = ["Segment", "PHOSPHOR", "decode_segments", "rasterize", "save_apng", "PreviewTransport"]
+
+#: A lit beam segment in device space: ``(x0, y0, x1, y1, intensity)``.
+Segment = tuple[int, int, int, int, int]
+Color = tuple[float, float, float]
+
+#: Default phosphor tint (green-cyan glow with white-hot cores).
+PHOSPHOR: Color = (0.18, 1.0, 0.55)
+
+
+def decode_segments(frame: bytes) -> list[Segment]:
+    """Decode a pyvterm frame into the lit segments the beam would draw.
+
+    Coordinates are device space (``0..DVG_RES_MAX``). Blanked moves reposition
+    the pen without producing a segment; a segment is emitted for each lit draw.
+    """
+    segments: list[Segment] = []
+    pen_x = pen_y = 0
+    intensity = 0
+    for offset in range(0, len(frame) - 3, 4):
+        info = protocol.decode_word(int.from_bytes(frame[offset : offset + 4], "big"))
+        flag = info["flag"]
+        if flag is Flag.RGB:
+            intensity = max(info["r"], info["g"], info["b"])
+        elif flag is Flag.XY:
+            x, y = info["x"], info["y"]
+            if not info["blank"] and intensity > 0:
+                segments.append((pen_x, pen_y, x, y, intensity))
+            pen_x, pen_y = x, y
+    return segments
+
+
+def rasterize(
+    segments: Sequence[Segment], width: int, height: int, color: Color = PHOSPHOR
+) -> Image.Image:
+    """Rasterize device-space ``segments`` into a glowing RGB frame."""
+    core = Image.new("L", (width, height), 0)
+    draw = ImageDraw.Draw(core)
+    sx = (width - 1) / DVG_RES_MAX
+    sy = (height - 1) / DVG_RES_MAX
+    for x0, y0, x1, y1, intensity in segments:
+        value = 90 + int(165 * intensity / 255)
+        # Device Y grows upward, image Y downward -> flip.
+        draw.line((x0 * sx, (height - 1) - y0 * sy, x1 * sx, (height - 1) - y1 * sy), fill=value)
+
+    base = np.asarray(core, dtype=np.float32) / 255.0
+    glow1 = np.asarray(core.filter(ImageFilter.GaussianBlur(2.0)), dtype=np.float32) / 255.0
+    glow2 = np.asarray(core.filter(ImageFilter.GaussianBlur(5.0)), dtype=np.float32) / 255.0
+    intensity_map = np.clip(base + 0.8 * glow1 + 0.5 * glow2 - 0.05, 0.0, 1.5)
+    hot = np.clip((base - 0.45) * 2.2, 0.0, 1.0)  # white-hot line cores
+
+    r, g, b = color
+    rgb = np.zeros((height, width, 3), dtype=np.float32)
+    rgb[..., 0] = r * intensity_map + 0.9 * hot
+    rgb[..., 1] = g * intensity_map + 0.5 * hot
+    rgb[..., 2] = b * intensity_map + 0.9 * hot
+    out = (np.clip(rgb, 0.0, 1.0) * 255).astype(np.uint8)
+    return Image.fromarray(out, mode="RGB")
+
+
+def save_apng(images: Sequence[Image.Image], path: str, fps: float = 25.0) -> int:
+    """Write ``images`` as an animated PNG; returns the number of frames."""
+    if not images:
+        raise ValueError("no frames to save")
+    duration = int(1000 / fps) if fps > 0 else 50
+    images[0].save(
+        path,
+        save_all=True,
+        append_images=list(images[1:]),
+        duration=duration,
+        loop=0,
+        format="PNG",
+    )
+    return len(images)
+
+
+class PreviewTransport(Transport):
+    """A :class:`~pyvterm.transport.Transport` that captures frames as images.
+
+    Drop it into a :class:`~pyvterm.VectorTerminal` in place of a serial port;
+    each ``send_frame`` is captured, and :meth:`save_apng` writes the animation.
+    """
+
+    def __init__(self, width: int = 480, height: int = 360, color: Color = PHOSPHOR) -> None:
+        self.width = width
+        self.height = height
+        self.color = color
+        self.frames: list[bytes] = []
+
+    def write(self, data: bytes) -> int:
+        self.frames.append(bytes(data))
+        return len(data)
+
+    def _frame_blobs(self) -> list[bytes]:
+        # Keep only real frames (skip the trailing EXIT-only write from close()).
+        return [
+            blob
+            for blob in self.frames
+            if len(blob) >= 4
+            and (int.from_bytes(blob[:4], "big") >> protocol.FLAG_SHIFT) == Flag.FRAME
+        ]
+
+    def images(self) -> list[Image.Image]:
+        """Rasterize every captured frame to a list of images."""
+        return [
+            rasterize(decode_segments(blob), self.width, self.height, self.color)
+            for blob in self._frame_blobs()
+        ]
+
+    def save_apng(self, path: str, fps: float = 25.0) -> int:
+        """Render captured frames and write them to ``path`` as an animated PNG."""
+        return save_apng(self.images(), path, fps=fps)

pyvterm/protocol.py

@@ -0,0 +1,236 @@
+"""Wire-level encoding for the USB-DVG / pitrex *vecterm* serial protocol.
+
+This module is **pure**: it has no I/O dependencies and can be imported and
+unit-tested without a serial port or any hardware. It mirrors the command
+encoding in `gtoal/pitrex`'s ``VMMenu/Win32/dvg/zvgFrame.c`` (the USB-DVG
+drivers written by Mario Montminy, 2020) and cross-checks against the
+canonical AdvanceMAME ``advance/osd/dvg.c`` implementation.
+
+Every command is a single 32-bit word transmitted **big-endian** (most
+significant byte first). The most significant three bits ``[31:29]`` select
+the command::
+
+    bit  31      29 28                                              0
+         +---------+------------------------------------------------+
+         |  flag   |  payload                                       |
+         +---------+------------------------------------------------+
+
+See ``docs/PROTOCOL.md`` for the full specification.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any
+
+__all__ = [
+    "Flag",
+    "Bounds",
+    "DEFAULT_BOUNDS",
+    "FLAG_SHIFT",
+    "BLANK_SHIFT",
+    "COORD_BITS",
+    "COORD_MASK",
+    "PAYLOAD_MASK",
+    "DVG_RES_MIN",
+    "DVG_RES_MAX",
+    "DVG_RENDER_QUALITY",
+    "COMPLETE_MONOCHROME",
+    "pack_word",
+    "scale_color",
+    "encode_rgb_word",
+    "encode_xy_word",
+    "encode_frame_word",
+    "encode_quality_word",
+    "encode_complete_word",
+    "encode_exit_word",
+    "decode_word",
+    "rgb",
+    "rgb_scaled",
+    "xy",
+    "frame_header",
+    "quality",
+    "complete",
+    "exit_command",
+]
+
+
+class Flag(IntEnum):
+    """Command selector occupying the top three bits of every word."""
+
+    COMPLETE = 0x0  #: End-of-frame marker (payload 0, or the monochrome bit).
+    RGB = 0x1  #: Set the colour/intensity of subsequent vectors.
+    XY = 0x2  #: Move (beam off) or draw (beam on) to a coordinate.
+    QUALITY = 0x3  #: Render-quality hint (pitrex/zvgFrame variant).
+    FRAME = 0x4  #: Frame header carrying total beam-travel length.
+    CMD = 0x5  #: Device command channel (AdvanceMAME; e.g. GET_DVG_INFO).
+    EXIT = 0x7  #: Tell the device the session is over.
+
+
+# --- Bit layout -----------------------------------------------------------
+
+FLAG_SHIFT = 29  #: The flag occupies bits [31:29].
+BLANK_SHIFT = 28  #: The XY blank (beam-off) bit.
+COORD_BITS = 14  #: Each XY coordinate is 14 bits wide.
+COORD_MASK = (1 << COORD_BITS) - 1  #: 0x3FFF.
+PAYLOAD_MASK = (1 << FLAG_SHIFT) - 1  #: 0x1FFFFFFF — bits available below the flag.
+
+# --- Device resolution ----------------------------------------------------
+
+DVG_RES_MIN = 0  #: Minimum DVG coordinate.
+DVG_RES_MAX = 4095  #: Maximum DVG coordinate (12-bit DAC range).
+DVG_RENDER_QUALITY = 5  #: Default quality value sent once per frame.
+
+#: OR'd into a ``COMPLETE`` word to flag a black & white game (AdvanceMAME).
+COMPLETE_MONOCHROME = 1 << 28
+
+
+@dataclass(frozen=True)
+class Bounds:
+    """The host coordinate space, mapped onto the device's ``0..4095`` grid.
+
+    The defaults match ``zvgFrame.h`` (a 1024x768 space centred on the
+    origin), which is the standard MAME vector resolution.
+    """
+
+    x_min: int = -512
+    x_max: int = 511
+    y_min: int = -384
+    y_max: int = 383
+
+    @property
+    def width(self) -> int:
+        return self.x_max - self.x_min
+
+    @property
+    def height(self) -> int:
+        return self.y_max - self.y_min
+
+    def conv_x(self, x: float) -> int:
+        """Map a host X coordinate onto ``0..DVG_RES_MAX`` (``CONVX`` in C)."""
+        return int(((x - self.x_min) * DVG_RES_MAX) // self.width)
+
+    def conv_y(self, y: float) -> int:
+        """Map a host Y coordinate onto ``0..DVG_RES_MAX`` (``CONVY`` in C)."""
+        return int(((y - self.y_min) * DVG_RES_MAX) // self.height)
+
+
+DEFAULT_BOUNDS = Bounds()
+
+
+# --- Word encoders --------------------------------------------------------
+
+
+def pack_word(word: int) -> bytes:
+    """Serialise a 32-bit command ``word`` as 4 big-endian bytes."""
+    return struct.pack(">I", word & 0xFFFFFFFF)
+
+
+def scale_color(value: int) -> int:
+    """Scale a ~4-bit colour channel to 8 bits, clamped to 255.
+
+    Matches ``zvgFrameSetRGB15``: the input is shifted left by 4 (so ``15``
+    maps to ``240``) and clamped, so values ``>= 16`` saturate at ``255``.
+    """
+    scaled = value << 4
+    return 255 if scaled > 255 else scaled
+
+
+def encode_rgb_word(r: int, g: int, b: int) -> int:
+    """Encode a raw 8-bit-per-channel ``RGB`` word."""
+    return (Flag.RGB << FLAG_SHIFT) | ((r & 0xFF) << 16) | ((g & 0xFF) << 8) | (b & 0xFF)
+
+
+def encode_xy_word(x: int, y: int, blank: bool) -> int:
+    """Encode an ``XY`` word.
+
+    ``blank`` selects beam-off (a move) when ``True`` and beam-on (a draw)
+    when ``False``.
+    """
+    return (
+        (Flag.XY << FLAG_SHIFT)
+        | ((1 if blank else 0) << BLANK_SHIFT)
+        | ((x & COORD_MASK) << COORD_BITS)
+        | (y & COORD_MASK)
+    )
+
+
+def encode_frame_word(vector_length: int) -> int:
+    """Encode the ``FRAME`` header carrying total beam-travel length."""
+    return (Flag.FRAME << FLAG_SHIFT) | (vector_length & PAYLOAD_MASK)
+
+
+def encode_quality_word(value: int = DVG_RENDER_QUALITY) -> int:
+    """Encode the ``QUALITY`` render hint."""
+    return (Flag.QUALITY << FLAG_SHIFT) | (value & PAYLOAD_MASK)
+
+
+def encode_complete_word(monochrome: bool = False) -> int:
+    """Encode the ``COMPLETE`` end-of-frame marker."""
+    return (Flag.COMPLETE << FLAG_SHIFT) | (COMPLETE_MONOCHROME if monochrome else 0)
+
+
+def encode_exit_word() -> int:
+    """Encode the ``EXIT`` (session over) command."""
+    return Flag.EXIT << FLAG_SHIFT
+
+
+def decode_word(word: int) -> dict[str, Any]:
+    """Decode a 32-bit word into a human-readable ``dict`` (for tests/debug)."""
+    flag = Flag((word >> FLAG_SHIFT) & 0x7)
+    info: dict[str, Any] = {"flag": flag}
+    if flag is Flag.RGB:
+        info.update(r=(word >> 16) & 0xFF, g=(word >> 8) & 0xFF, b=word & 0xFF)
+    elif flag is Flag.XY:
+        info.update(
+            blank=bool((word >> BLANK_SHIFT) & 0x1),
+            x=(word >> COORD_BITS) & COORD_MASK,
+            y=word & COORD_MASK,
+        )
+    elif flag is Flag.FRAME:
+        info["vector_length"] = word & PAYLOAD_MASK
+    elif flag is Flag.QUALITY:
+        info["value"] = word & PAYLOAD_MASK
+    elif flag is Flag.COMPLETE:
+        info["monochrome"] = bool(word & COMPLETE_MONOCHROME)
+    return info
+
+
+# --- Byte-producing convenience wrappers ----------------------------------
+
+
+def rgb(r: int, g: int, b: int) -> bytes:
+    """4 bytes setting a raw 8-bit-per-channel colour."""
+    return pack_word(encode_rgb_word(r, g, b))
+
+
+def rgb_scaled(r: int, g: int, b: int) -> bytes:
+    """4 bytes setting a colour from ~4-bit channels (``zvgFrameSetRGB15``)."""
+    return pack_word(encode_rgb_word(scale_color(r), scale_color(g), scale_color(b)))
+
+
+def xy(x: int, y: int, blank: bool) -> bytes:
+    """4 bytes moving (``blank=True``) or drawing (``blank=False``) to ``x,y``."""
+    return pack_word(encode_xy_word(x, y, blank))
+
+
+def frame_header(vector_length: int) -> bytes:
+    """4 bytes for the frame header."""
+    return pack_word(encode_frame_word(vector_length))
+
+
+def quality(value: int = DVG_RENDER_QUALITY) -> bytes:
+    """4 bytes for the quality hint."""
+    return pack_word(encode_quality_word(value))
+
+
+def complete(monochrome: bool = False) -> bytes:
+    """4 bytes for the end-of-frame marker."""
+    return pack_word(encode_complete_word(monochrome))
+
+
+def exit_command() -> bytes:
+    """4 bytes telling the device the session is over."""
+    return pack_word(encode_exit_word())