Visual engine
libfreedome_engine is the L1 visual engine of the FreeDome ecosystem: it decodes media, warps, blends and
colour-corrects frames for every display of a dome (projectors, fisheye, prism units, LED / flat panels) and presents
them on physical or virtual outputs on a shared frame clock. freedome-engined hosts the library in its own process
and exposes it as the gRPC API freedome.engine.v1 (L2).
Build and run instructions for users: the repository README. Platform status per target: flows/ARCHITECTURE_CPU_OS_GPU.md.
Boundaries
Section titled “Boundaries”| Boundary | Who uses it |
|---|---|
gRPC freedome.engine.v1 (proto/freedome/engine/*.proto, buf module) over a Unix socket or mTLS TCP |
all external clients — the media server (L3), tests in tests/grpc_conformance/ |
C ABI 3 (include/freedome/engine.h, SONAME libfreedome_engine.so.3) |
internal: freedome-engined, freedome-engine-cli, in-process tests, embedded targets, output plugins (include/freedome/output_plugin.h) |
Owner decision A1: the engine is a separate process; pixels never cross gRPC (content arrives by path / URI, large buffers only as shared memory referenced by handle). The engine has no GUI (operator UI = Manager via the media server), no audio (it publishes a media clock that the audio engines follow) and no show logic.
Source layout
Section titled “Source layout”| Directory | Contents |
|---|---|
include/freedome/ |
public C ABI 3 (engine.h, engine_types.h), output plugin ABI |
src/abi/ |
ABI implementation, tools API used by the CLI |
src/core/ |
director, command queue, render state, state machine, error store, events, stats, recovery |
src/hal/cpu/, src/hal/os/ |
CPU detection for x86_64 / arm64 / riscv64 / loongarch64 / e2k, runtime SIMD dispatch; OS HAL Linux distros (Astra, BOSS, Kylin, Loongnix, RED OS, Debian / Ubuntu), Windows, macOS |
src/hal/gpu/ |
GPU HAL: software (reference renderer, always available), vulkan (incl. vendor quirks table and external memory), metal (macOS; MSL generated from the common shaders) |
src/pipeline/ |
frame pipeline compose → warp → blend → colour, effects, stereo, offline render, shaders |
src/projection/ |
dome mesh, content mappings, display models (projector, fisheye, prism unit / pyramidal optics, smartphone_lens, LED / flat), FDMESH / blend PNG / .cube I/O |
src/calibration/ |
patterns, structured-light decode, camera models, mesh / blend / colour solve, points, manual grid, model-only, report |
src/media/ |
demux, HAP family, still images / sequences, software H.264 / H.265 / ProRes, hardware decode (VAAPI, NVDEC, V4L2-M2M, D3D11VA, VideoToolbox), live inputs (SRT / RTSP / UDP, capture) |
src/output/ |
DRM/KMS, Wayland, X11, Win32, macOS outputs; virtual outputs (file, preview stream, display stream, shared memory) |
src/sync/ |
frame clock, output-group scheduler, present timing, PTP clock source, drift model, media clock (PTP notes) |
engined/ |
freedome-engined: gRPC services, config, metrics (Prometheus), health, logging |
tools/freedome-engine-cli/ |
offline tools: patterns, mesh, render-offline, bench, list-outputs |
plugins/ndi/ |
optional NDI output plugin (vendor SDK, off by default) |
tests/ |
unit, golden renders, ABI, media, integration, gRPC conformance, fuzz, HIL descriptions |
There is no ECS and no CUDA backend; GPU work runs through Vulkan (Linux / Windows), Metal (macOS) or the software renderer.
CMake options
Section titled “CMake options”| Option | Default | Description |
|---|---|---|
FREEDOME_BUILD_TESTS |
ON | unit, golden and ABI tests |
FREEDOME_BUILD_ENGINED |
ON | freedome-engined (gRPC host) |
FREEDOME_BUILD_TOOLS |
ON | freedome-engine-cli |
FREEDOME_OPENCV |
ON | OpenCV-assisted calibration (built-in solver otherwise) |
FREEDOME_FFMPEG |
ON | FFmpeg media decode (LGPL-only build) |
FREEDOME_VULKAN |
ON | Vulkan GPU backend |
FREEDOME_METAL |
ON on macOS | Metal GPU backend |
FREEDOME_HWDEC_VAAPI / _NVDEC / _V4L2M2M / _VIDEOTOOLBOX / _D3D11VA |
per platform | hardware decoders |
FREEDOME_NDI |
OFF | NDI plugin (user-enabled, vendor SDK) |
FREEDOME_BUILD_FUZZERS |
OFF | libFuzzer targets (Clang) |
FREEDOME_COVERAGE |
OFF | coverage instrumentation |
Normally the options are set by ci/build.sh --target <target> (toolchain files in cmake/toolchains/).
Building and testing
Section titled “Building and testing”All builds run in Docker images freedome/engine-build:<target> (Dockerfiles in ci/docker/, see
ci/docker/README.md):
docker run --rm -u 1000:1000 -v $PWD:/w -w /w -e HOME=/tmp \ freedome/engine-build:linux-x86_64 ci/build.sh --target linux-x86_64docker run --rm -u 1000:1000 -v $PWD:/w -w /w -e HOME=/tmp \ freedome/engine-build:linux-x86_64 ctest --test-dir build/linux-x86_64 --output-on-failureci/build.sh --list prints the targets: linux-x86_64, linux-arm64, linux-riscv64, linux-loongarch64,
linux-e2k, windows-x86_64, macos-universal, android-arm64. Cross targets run their tests under QEMU; targets
without a runner are released as “built, untested”. Sanitizers: ci/build.sh --target linux-x86_64 --sanitize address|thread.
Using the C ABI (internal)
Section titled “Using the C ABI (internal)”#include <freedome/engine.h>
if (freedome_engine_abi_version() != FREEDOME_ENGINE_ABI_VERSION) { /* refuse: different ABI major */ }Functions return an FDResult; details via freedome_last_error_code() / freedome_last_error_message().
Exceptions never cross the ABI and the library never writes to stdout / stderr (logging through
freedome_engine_set_log_callback). New clients should not link the library directly — use the gRPC API.
Licence
Section titled “Licence”NativeMindNONC (LICENSE); third-party notices in NOTICE. Support: [email protected].