A small C++ library for pixel format conversion and test pattern generation, with a C API and Python bindings.
- Templated C++ core. Each pixel format is described once as a layout — component order, bit widths, plane shape — and the conversion code is generated from those descriptions by the C++ compiler. Adding a new format or component order is a few lines of layout, not a new conversion routine.
- 16-bit normalized pivot. Conversions don't go format-to-format. They unpack into a 16-bit RGB or YUV intermediate and pack from it, so cross-color-kind conversions (RGB ↔ YUV, with arbitrary matrix and range) cost the same as same-color-kind ones, precision is preserved when both endpoints are 8-bit, and the work scales as N+M instead of N×M.
- Built to drop into pipelines. Caller-owned buffers and a small
C ABI mean pixpat fits inside the inner loop of a DRM/KMS, V4L2, or
GPU-upload path without copies. Exceptions are used internally but
never cross the C ABI. Beyond libc, the only runtime dependency is
libstdc++.
- You need maximum throughput. Hand-tuned conversion paths —
OpenCV with its SIMD intrinsics, vendor-supplied codecs, ffmpeg's
swscale— still outrun pixpat on the heavily-trafficked format pairs. pixpat aims for "fast enough" out of a small generated codebase, not for raw peak speed. - You want a pure-Python library. The Python package is a thin
ctypeswrapper aroundlibpixpat.so. You need a native wheel matching your architecture; there is no pure-Python fallback. - You need GPU conversion. pixpat is CPU-only.
- Test patterns —
kmstest, SMPTE RP 219-1 bars,plainsolid fill, R/G/B/gray ramps, checkerboard, color-bar overlays, zone plate. All take a single per-pattern parameter string. - Format conversion between packed / semiplanar / planar YUV, RGB, raw Bayer, and grayscale. Each buffer states the color spec of its data: the BT.601 / BT.709 / BT.2020 matrix and the limited / full quantization range. Conversions honor it, and two YUV buffers with different specs are re-encoded. See Color spec.
- Caller-owned pixel memory. Callers pass plane pointers and strides; pixpat never allocates pixel buffers. The only internal allocation is a small per-thread normalized line buffer reused across cold-path calls.
- DRM / kms++ / pixutils format names (
XRGB8888,NV12, …) rather than DRM/V4L2 four-character codes (XR24, …). See Format names and byte order — the convention disagrees with OpenCV's. - Optional multi-threading via a single
num_threadsknob on both entry points. - Build-time tailoring. A small TOML config selects which formats and patterns are compiled in, which formats are read-only / write-only, and which formats get a fully-fused fast path.
The default build ships every format in the catalog. Each one works as
a pixpat_draw_pattern target, a pixpat_convert source, and a
pixpat_convert destination.
- RGB packed —
RGB332,RGB565,BGR565, the four 1555 permutations{XRGB,ARGB,XBGR,ABGR}1555, the six 4444 permutations{XRGB,ARGB,XBGR,ABGR,RGBX,RGBA}4444,RGB888,BGR888, the eight 8888 permutations{XRGB,ARGB,XBGR,ABGR,RGBX,RGBA,BGRX,BGRA}8888, the eight 10-bit permutations{XRGB,ARGB,XBGR,ABGR}2101010and{RGBX,RGBA,BGRX,BGRA}1010102, andABGR16161616.R8is a single-channel form; on read the unspecified channels are synthesized as G=B=R. - YUV packed —
YUYV,YVYU,UYVY,VYUY,Y210,Y212,Y216,VUY888,XVUY8888,XVUY2101010,AVUY16161616. - YUV semiplanar —
NV12,NV21,NV16,NV61,P030,P230. - YUV planar —
YUV444,YVU444,YUV422,YVU422,YUV420,YVU420,T430. - Grayscale —
Y8,Y10,Y12,Y16,XYYY2101010,Y10P,Y12P. - Bayer unpacked —
SRGGB/SBGGR/SGRBG/SGBRGat 8 / 10 / 12 / 16 bit. Reads use a bilinear demosaic. - Bayer MIPI-packed — the same four phases at 10P / 12P.
Format names follow the DRM / kms++ / pixutils convention:
components are listed MSB-first inside the storage word. So
XRGB8888 means a 32-bit word with X in the highest byte and B in
the lowest, and BGR888 is a 24-bit format with B at the highest
byte and R at byte 0.
OpenCV uses the opposite convention — its BGR is byte-order, so
OpenCV BGR and pixpat RGB888 describe the same in-memory layout.
Keep this in mind when comparing pipelines.
#include <pixpat/pixpat.h>
uint8_t pixels[1920 * 1080 * 4];
pixpat_buffer buf = {
.format = "XRGB8888",
.width = 1920,
.height = 1080,
.num_planes = 1,
.planes = { pixels },
.strides = { 1920 * 4 },
};
pixpat_draw_pattern(&buf, "smpte", NULL); /* NULL opts → auto thread count */A buffer also states the color spec of its samples. The fields default to the format's natural spec. An NV12 buffer that holds BT.709 limited-range samples states that, and the SMPTE bars, which are defined in BT.709 / Limited, are written into it unchanged:
uint8_t y_plane[1920 * 1080];
uint8_t uv_plane[1920 * 1080 / 2];
pixpat_buffer nv12 = {
.format = "NV12",
.width = 1920,
.height = 1080,
.num_planes = 2,
.planes = { y_plane, uv_plane },
.strides = { 1920, 1920 },
.rec = PIXPAT_REC_BT709,
.range = PIXPAT_RANGE_LIMITED,
};
pixpat_draw_pattern(&nv12, "smpte", NULL);A pixpat_convert(dst, src, opts) call has the same shape: two
pixpat_buffers plus a small options struct (also nullable). See the
public header at pixpat-native/inc/pixpat/pixpat.h, and
Color spec for what the color fields mean.
import pixpat
w, h = 1920, 1080
data = bytearray(w * h * 4)
buf = pixpat.Buffer(planes=[data], fmt='XRGB8888', width=w, height=h, strides=[w * 4])
pixpat.draw_pattern(buf, 'smpte')Buffer carries the color spec too, as rec and color_range:
y, uv = bytearray(w * h), bytearray(w * h // 2)
nv12 = pixpat.Buffer([y, uv], 'NV12', w, h, [w, w], pixpat.Rec.BT709, pixpat.Range.LIMITED)
pixpat.draw_pattern(nv12, 'smpte')The Python Buffer accepts anything that supports the buffer protocol
— bytearray, array.array, numpy.ndarray, mmap.mmap,
memoryview. Source buffers may be read-only; destination buffers
must be writable.
pixpat-conv: convert a raw frame file, a PNG file or a test pattern to a raw frame file or a PNG.
The tool needs the tools extra, which adds pixutils (plane geometry)
and Pillow (PNG):
pip install '.[tools]'
pipx install 'pixpat[tools] @ git+https://github.com/tomba/pixpat.git'pixpat-conv [options] SRC DST takes a raw frame file, a PNG file, -
for stdin, or a pattern name (smpte, kmstest, ...; see
--list-patterns) as the source, and a raw frame file, a PNG file, or
- for stdout as the destination. Size and formats come from --size WxH, --from FMT and --to FMT, or are parsed from the file names
when omitted, for example frame-640x480-NV12.raw. A name may also
carry bt601/bt709/bt2020 and full/limited, which describe
that file. --src-rec, --src-range, --dst-rec and --dst-range
set the same values. A side with no value takes the other side's
value, so naming one side keeps the conversion a repack. Naming both
sides with different values re-encodes the samples. An RGB or raw
format has no spec. A raw file holds the planes back to back,
tight unless --src-stride or --dst-stride says otherwise. A .gz
file is decompressed on read and compressed on write.
pixpat-conv smpte smpte-1920x1080-nv12-bt709.raw
pixpat-conv smpte-1920x1080-nv12-bt709.raw smpte.png
pixpat-conv smpte-1920x1080-nv12-bt709.raw smpte-1920x1080-nv12-bt601.raw
pixpat-conv --src-stride 2048 -f XRGB8888 -s 640x480 dump.raw dump-640x480-bgr888.raw
pixpat-conv --dst-stride 4096 smpte smpte-1920x1080-xrgb8888.rawlibpixpat— the C++ implementation, exposed through a small C ABI inpixpat-native/inc/pixpat/pixpat.h. Built with Meson; produces both shared and static libraries plus a pkg-config file.pixpat(Python) — thinctypesbindings over the C ABI. No CPython extension, so a single wheel works on any CPython ≥ 3.9 for a given architecture.pixbench— the measurement tooling inpixpat-bench/: builds the library from any tree or commit, digests every output byte, records throughput and size into JSON run files, and compares them across commits, compilers and build options.
libpixpat is built with Meson. A C++20
compiler and Python 3 (used by the build-time codegen) are required;
there are no third-party runtime dependencies.
meson setup build
meson compile -C buildMeson uses c++ unless CXX is set, which on most distros means gcc.
clang produces faster conversion code (see Compiler), and
meson never looks at versioned names such as clang++-20 on its own:
CXX=clang++-20 meson setup buildThis produces build/libpixpat.so (and .a), the public header at
pixpat-native/inc/pixpat/pixpat.h, and a pixpat.pc pkg-config
file. To install system-wide:
meson install -C buildA cross file for aarch64 Linux ships in the tree:
meson setup build-aarch64 --cross-file pixpat-native/cross/aarch64-linux-gnu.txt
meson compile -C build-aarch64meson test -C buildThese are smoke tests that exercise the public ABI from C and C++. Behavioral coverage (matrix correctness, threading, subsampling, Bayer demosaic, …) lives in the Python test suite.
The default profile compiles every format and pattern. To pick a
different one, point Meson at an alternate TOML file via the config
option:
meson setup build-min -Dconfig=pixpat-native/profiles/no_hotpath.tomlA few example profiles ship in pixpat-native/profiles/. See
Build-time configuration and codegen
below for what the TOML controls.
The Python package wraps the C ABI via ctypes, so installing it
just means compiling libpixpat.so and bundling it as package data.
For a native install:
pip install .setup.py invokes meson during the wheel build (into a temporary
directory), copies the resulting .so into the package, and stamps the
wheel for the host architecture. Requires meson, ninja, and a C++
compiler on the host. The build uses the newest clang++ found on
PATH, versioned names such as clang++-20 included, and falls back
to meson's default, normally gcc. Set CXX to choose the compiler
yourself. A cross build takes its compiler from the cross file.
To cross-compile a wheel for another architecture, use the helper:
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
pixpat-python/scripts/build_wheel.sh aarch64 # or x86_64Beyond the cross toolchain this needs only python3 and its venv
module: the script bootstraps a build environment in
pixpat-python/build-venv/ and lets PEP 517 build isolation provision
setuptools, meson and ninja from pyproject.toml. No pip install into your own environment is required, and the distro's
setuptools is not used (setup.py needs >= 70.1, which is newer than
some distros ship).
The resulting wheel lands in dist/, tagged for the chosen
architecture. Wheel builds are always clean: meson runs in a temporary
directory and nothing is cached between runs, so repeated builds are
reproducible. Only the repo-root build/ of the editable workflow below
is persistent.
The wheel is tagged linux_<arch>, not manylinux, so the .so
carries whatever glibc symbol versions your cross toolchain emits. If
the target's glibc is older, the wheel installs but fails to load —
check with readelf -V before deploying. The .so also links
libstdc++.so.6, which must be present on the target.
meson setup build
meson compile -C build
pip install -e .The editable install symlinks build/libpixpat.so into the
package, so rebuilding the native side is picked up without
re-installing.
pixpat_build_info() returns how the loaded library was built, as
pixpat.<key>=<value> lines: version, compiler, buildtype,
optimization level, whether asserts are compiled out, LTO, extra
cpp_args, the profile and the CPU family. pixpat.build_info()
returns the same as a dict. The text is stored verbatim in the library,
so a file on disk answers without being loaded:
strings build/libpixpat.so | grep '^pixpat\.'The Python package warns at import when the library's version differs
from the package metadata. Under an editable install that means a stale
build/, or a package installed before a version bump.
From the repo root, after an editable install:
pytest pixpat-python/testsFor throughput, library size and bit-exactness measurements across
builds, compilers and commits, see pixpat-bench/
(scripts/pixbench). This is a development tool, not part of the
supported API surface.
The rest of this document covers how libpixpat is put together
internally: how a conversion is structured, how formats are
described, how the build is configured, and the supported compiler
and runtime.
A conversion is the composition of three stages:
Source → ColorXfm → Sink
- A source unpacks caller-memory pixels into a normalized
pixel —
RGB16orYUV16, fouruint16_tcomponents. - A ColorXfm maps one normalized pixel type to another: identity for same-color-kind conversions; for cross-color-kind ones the matrix and range of the YUV buffer's color spec, whether that buffer is the source or the destination. Template-specialized, so the identity case vanishes at compile time.
- A sink packs normalized pixels into destination memory.
Each sink declares a block_h × block_w block matching its chroma
subsampling (1×1 for unsubsampled, e.g. 2×2 for NV12). The
converter materializes one block on the stack per iteration; under
-O3 it stays in registers for most sinks.
The normalized pixel type does double duty:
- On the hot path, with
-O3, the compiler keeps it in registers across the source / ColorXfm / sink boundary — no per-line buffer is involved. - On the cold path, two short legs — unpack to norm and pack from norm — share a per-thread normalized line buffer. Each leg is a templated function: one body per source, one per sink. Cross-color-kind conversions add an in-place ColorXfm pass over the buffer between the two legs, and a YUV re-encode adds its own.
Whether a particular conversion runs on the hot or cold path is decided by the dispatch tier described in Two-tier dispatch.
A buffer carries four color fields: primaries, xfer, rec (the
BT.601 / BT.709 / BT.2020 matrix) and range (limited or full). They
describe the data the buffer holds. pixpat decodes a source according
to the source's fields and encodes a destination according to the
destination's fields. DEFAULT means the format's natural spec:
BT.601 and limited range for a YUV-kind format, full range for an
RGB-kind format. The Y-only formats are YUV-kind; R8 and the Bayer
formats are RGB-kind. An RGB-kind buffer has no matrix, so its rec
is ignored. pixpat models RGB-kind buffers in full range only, so
limited range on such a buffer fails the call.
The two color kinds decide what a conversion does with the two specs:
- Cross-color-kind (RGB ↔ YUV) — the color math uses the spec of the YUV side, whether that is the source or the destination.
- RGB to RGB — no color math.
- YUV to YUV, equal specs — a repack of the samples.
- YUV to YUV, different specs — a re-encode.
The decode with the source spec and the encode with the destination spec are both affine maps on the normalized components. Their composition is one 3×3 matrix plus an offset. pixpat recovers the composition by evaluating decode-then-encode on the origin and the three unit vectors. The composition is applied once per pixel, with one rounding and no intermediate clamp to the RGB gamut. A sample outside the nominal range, such as a sub-black or super-white PLUGE step, keeps its value if the destination range has room for it.
A re-encode runs on the cold path. Dispatch routes it there before
the hot-pivot probes, because a fused arm between two YUV formats
carries an identity ColorXfm and cannot express it.
primaries and xfer accept only DEFAULT. The fields exist so
that a gamut or transfer-function conversion can be added without an
ABI change.
A pixel format is described once, declaratively, as a C++20 non-type-template-parameter (NTTP) value. Three small types are enough to describe any format:
enum class C : uint8_t { X, A, R, G, B, Y, U, V };
struct Comp { C c; uint8_t bits; uint8_t shift; };
template <typename Storage, Comp... Cs>
struct Plane;
template <ColorKind Kind, size_t Hsub, size_t Vsub, typename... Planes>
struct Layout;A Plane describes one storage word (uint32_t, uint16_t, …) and
the components packed into it at given bit offsets. A Layout lists
the planes, the color kind (RGB or YUV), and the chroma subsampling
factors. Two named formats for comparison:
using XRGB8888 = Layout<ColorKind::RGB, 1, 1,
Plane<uint32_t, Comp{C::B,8,0}, Comp{C::G,8,8},
Comp{C::R,8,16}, Comp{C::X,8,24}>>;
using NV12 = Layout<ColorKind::YUV, 2, 2,
Plane<uint8_t, Comp{C::Y,8,0}>,
Plane<uint16_t, Comp{C::U,8,0}, Comp{C::V,8,8}>>;Plane exposes constexpr helpers — find_pos<C>, pack(values),
unpack(word), bytes_per_pixel, … — that the I/O templates use to
emit per-format read and write code.
A pattern is a synthetic source: a small C++ struct exposing
sample(x, y, W, H) that returns one normalized pixel. The list of
supported names and their parameters is in
pixpat-native/inc/pixpat/pixpat.h.
Dispatch is intentionally simple: every (pattern, sink) pair takes one normalized-pivot path. The per-pattern fill writes the normalized line buffer in the pattern's own color kind. A color pass over the buffer then converts it to the destination's kind and spec, and the per-sink pack encodes the line into the destination memory layout. Total cost is O(N + M): adding a pattern is one fill specialization, adding a format is automatic.
A pattern may have both an RGB-native and a YUV-native variant, as
hbar and vbar have. The sink's color kind picks the variant, and
the color pass then has nothing to convert.
A pattern may also declare the color spec of its samples. The SMPTE bars do: RP 219-1 defines their code values in BT.709 / Limited. A YUV destination receives them re-encoded to its own rec and range. A destination declared BT.709 / Limited receives the exact code values of the spec. An RGB destination receives them decoded from BT.709 / Limited. A YUV-native pattern that declares no spec is constructed with the destination's spec and builds its colors in it, so the color pass has nothing to do.
pixpat_pattern_opts::params is parsed once at the C entry point
into a Params instance, then handed to the pattern constructor;
patterns query keys by name and never see raw strings. The Python
wrapper accepts either the wire string or a Mapping[str, Any].
The naïve approach — instantiate Converter<Source, Sink> for every
source/sink pair — produces an N×N matrix of fully-fused inner loops.
With this many formats the binary balloons quickly. So pixpat splits
the conversion table into two tiers.
Hot pivot. A small set of pivot formats gets the fully-fused
treatment. Real-world conversion paths almost always have a common
interchange format on at least one endpoint — OpenCV, Qt,
framebuffers, and video pipelines all gravitate toward a single
8-bit RGB form. Picking that form as the pivot makes the typical
user path fully inlined; the rarer hardware-to-hardware path stays
on the cold path. The default profile uses BGR888 as its
single pivot, the format OpenCV, Qt, and framebuffers all use. Each
pivot covers itself as both source and destination, paired with
every other format.
Cold path. Every other source/sink pair walks each row group through the per-thread normalized line buffer:
for each row group:
unpack_to_norm<Source>(buf, src, ...)
if RGB ↔ YUV:
in-place ColorXfm pass over buf
else if the two YUV specs differ:
in-place re-encode pass over buf
pack_from_norm<Sink>(dst, buf, ...)
unpack_to_norm<Source> and pack_from_norm<Sink> are plain
templated functions — one body per source, one per sink, not per
pair. With ~2N legs plus three in-place color passes, the cold path fits
in a small fixed code budget independent of the number of pairs.
Adding a hot pivot is mechanical (one entry in the build config — see the next section). Whether a pivot is worth the code size depends on whether real workloads actually use that format on one endpoint, so the choice is workload-driven.
Internally the I/O templates are grouped by iteration shape. Every
format reuses one of these template shapes, plus its own Layout:
- Packed (RGB or YUV) —
XRGB8888,BGR888, … - Packed-YUV —
YUYVgroup. - Semiplanar —
NV12group. - Multi-pixel semiplanar —
P030,P230. Sink uses the streaming entry point. - Planar —
YUV420,YUV444, … - Multi-pixel planar —
T430. - Gray — single-component YUV; chroma synthesized at neutral on read.
- Mono RGB — RGB counterpart of Gray (
R8); G=B=R synthesized on read. - Multi-pixel gray —
XYYY2101010. - Gray MIPI-packed —
Y10P,Y12P. - Bayer — phase-aware R/G/B selection. Reads use a 3×3 bilinear demosaic; edges clamp.
- Bayer MIPI-packed — the 10P / 12P byte layout, hand-rolled
because the bit packing doesn't fit
Plane<Storage, Comp...>.
Adding a new format usually means one of: writing a new Layout and
reusing one of these templates verbatim; adding a new layout shape to
an existing template group; or, rarely, adding a new template group.
A worker fan-out helper splits the image into row stripes — one
disjoint [start, end) row range per worker — and runs the same
converter body on each stripe. Stripe boundaries are aligned to the
destination's vertical subsampling so chroma blocks aren't split
across workers. Workers are joined before the call returns.
num_threads = 0 selects a sensible default (one per online CPU,
capped); 1 runs the conversion inline on the calling thread with
no thread-spawn overhead; N > 1 uses exactly N workers.
Color math runs in float. Normalized components are uint16_t;
N-bit stored values bit-replicate to 16 bits on decode (so 0xFF → 0xFFFF) and truncate via norm >> (16 - N) on encode. Per-component
decode→encode at the same bit depth is exact; full conversions are
not — they go through float color math and, where bit depths differ,
truncation.
A YUV to YUV re-encode (Color spec) runs its composed matrix in float as well. The result is rounded half up once and clamped to the normalized 16-bit range. There is no clamp to the RGB gamut in between.
Alpha rules:
- Source without A →
a = 0. - Same-color-kind ColorXfm →
aunchanged. - Cross-color-kind ColorXfm →
areset to0xFFFF. - YUV re-encode → same color kind, so
aunchanged. - Sinks with A encode
a; sinks with X write zero.
Which formats and patterns are compiled in, which formats are
read-only / write-only, and which formats get the fully-fused
hot-pivot treatment are all decided at build time by a small TOML
config. The default lives at pixpat-native/profiles/pixpat.toml; pick
a different one with Meson's -Dconfig=… option.
The TOML options:
hot_pivots = ["BGR888"] # which formats get fully-fused arms
patterns = ["kmstest", "smpte"] # which patterns to compile in
[features]
pattern = true # toggle the draw-pattern entry point
convert = true # toggle the convert entry point
default_format_caps = "rw" # default per-format read/write
[formats]
# RGB888 = "r" # readable only
# YUV420 = "off" # not in this buildAt configure time, a Python codegen step reads the TOML and the format and pattern catalogs and emits two generated files:
pixpat_config.h— the C-side feature flags.pixpat_caps.inc— two parallel arrays,FormatCaps[]andPatternCaps[]. Each entry carries booleans likereadable,writable,hot_src,hot_dst(formats) orenabled(patterns).
The dispatch code reads those caps inside if constexpr guards, so a
disabled format / pattern / hot arm produces no template
instantiation at all — the corresponding code is never generated.
This is how a constrained target shrinks the binary: turn off the
patterns and formats it doesn't need; the rest disappears from the
output.
Three example profiles ship in pixpat-native/profiles/
illustrating the knobs (no hot path, pattern-only, hot pivot moved
to a different format).
Hot-path performance depends heavily on the inlined inner loop being auto-vectorized. CI builds and tests under both gcc and clang; both work, but performance differs:
- Under clang 18 (built with
-O3 -march=native) the templated inner loops vectorize cleanly and the normalized pixel stays register-resident. - Under gcc 13 the same loops vectorize for some shapes but not others — RGB→RGB in particular drops considerably.