Zireael

https://rtlzeromemory.github.io/Zireael/
Admin
Zireael is a deterministic terminal rendering engine in C designed for embedding into higher-level...
Tokens:39,566
Snippets:493
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run example programs

Source: https://rtlzeromemory.github.io/Zireael/examples

Run the compiled example binaries from the build output directory. Each command launches a separate example program.

```bash
./out/build/posix-clang-debug/zr_example_minimal_render_loop
./out/build/posix-clang-debug/zr_example_input_echo
./out/build/posix-clang-debug/zr_example_resize_redraw

```

--------------------------------

### Run Input Echo Example

Source: https://rtlzeromemory.github.io/Zireael/examples/input-echo

Command to run the compiled Input Echo example from the build directory.

```bash
./out/build/posix-clang-debug/zr_example_input_echo

```

--------------------------------

### Run Minimal Example on Windows

Source: https://rtlzeromemory.github.io/Zireael/getting-started/quickstart

Execute the minimal render loop binary on Windows systems.

```powershell
.\out\build\windows-clangcl-debug\zr_example_minimal_render_loop.exe
```

--------------------------------

### Build examples with CMake presets

Source: https://rtlzeromemory.github.io/Zireael/examples

Build the example programs using the posix-clang-debug preset. Run these commands from the project root.

```bash
cmake --preset posix-clang-debug
cmake --build --preset posix-clang-debug

```

--------------------------------

### Run Minimal Example on POSIX

Source: https://rtlzeromemory.github.io/Zireael/getting-started/quickstart

Execute the minimal render loop binary on POSIX systems.

```bash
./out/build/posix-clang-debug/zr_example_minimal_render_loop
```

--------------------------------

### File header comment example (src/core/zr_drawlist.c)

Source: https://rtlzeromemory.github.io/Zireael/CODE_STANDARDS

Required file header comment for every .c/.h file. It explains the file's purpose, invariants, and failure modes. The example shows the expected format for a drawlist validator and executor.

```c
/*
  src/core/zr_drawlist.c — Drawlist validator and executor.

  Why: Validates wrapper-provided bytes and executes drawing into the framebuffer safely.
  Invariants:
    - No OOB reads; all offsets/sizes validated before access.
    - No partial effects: validate fully before mutating the framebuffer.
  Failure modes:
    - Invalid format -> ZR_ERR_FORMAT / ZR_ERR_UNSUPPORTED.
    - Caps exceeded -> ZR_ERR_LIMIT.
*/
```

--------------------------------

### zr_engine_config_t structure

Source: https://rtlzeromemory.github.io/Zireael/modules/CONFIG_AND_ABI_VERSIONING

The primary configuration structure passed to engine_create() for initial setup and ABI negotiation.

```c
typedef struct zr_engine_config_t {
  uint32_t requested_engine_abi_major;
  uint32_t requested_engine_abi_minor;
  uint32_t requested_engine_abi_patch;

  uint32_t requested_drawlist_version;
  uint32_t requested_event_batch_version;

  zr_limits_t limits;
  plat_config_t plat;

  uint32_t tab_width;
  uint32_t width_policy;
  uint32_t target_fps;

  uint8_t enable_scroll_optimizations;
  uint8_t enable_debug_overlay;
  uint8_t enable_replay_recording;
  uint8_t wait_for_output_drain;

  uint32_t cap_force_flags;
  uint32_t cap_suppress_flags;

  uint32_t inline_rows;
} zr_engine_config_t;
```

--------------------------------

### Event Batch Parsing Skeleton

Source: https://rtlzeromemory.github.io/Zireael/abi/event-batch-format

Example implementation for iterating through records in a buffer, including bounds validation and 4-byte alignment handling.

```c
const zr_evbatch_header_t* hdr = (const zr_evbatch_header_t*)buf;
uint32_t off = (uint32_t)sizeof(*hdr);

while (off + (uint32_t)sizeof(zr_ev_record_header_t) <= hdr->total_size) {
  const zr_ev_record_header_t* rec = (const zr_ev_record_header_t*)(buf + off);
  if (rec->size < sizeof(*rec) || off + rec->size > hdr->total_size) {
    break; /* malformed */
  }

  const uint8_t* payload = buf + off + (uint32_t)sizeof(*rec);
  /* switch(rec->type) ... */

  off += (rec->size + 3u) & ~3u;
}
```

--------------------------------

### High-Level Batch Layout

Source: https://rtlzeromemory.github.io/Zireael/abi/event-batch-format

Visual representation of the event batch structure, starting with a 24-byte header followed by sequential records.

```text
+--------------------------------+
| zr_evbatch_header_t (24 bytes) |
+--------------------------------+
| record 0                        |
+--------------------------------+
| record 1                        |
+--------------------------------+
| ...                             |
+--------------------------------+
```

--------------------------------

### Build for Windows (clang-cl)

Source: https://rtlzeromemory.github.io/Zireael/getting-started/quickstart

Commands to set up the environment and build the project using CMake on Windows.

```powershell
.\scripts\vsdev.ps1
cmake --preset windows-clangcl-debug
cmake --build --preset windows-clangcl-debug
```

--------------------------------

### Cleanup pattern using goto

Source: https://rtlzeromemory.github.io/Zireael/CODE_STANDARDS

Demonstrates the standard cleanup pattern for multi-resource functions to ensure no partial effects on failure.

```c
zr_result_t rc = ZR_OK;
resource_t* r = NULL;

r = alloc_resource();
if (!r) { rc = ZR_ERR_OOM; goto cleanup; }

cleanup:
free_resource(r);
return rc;
```

--------------------------------

### Windows debug workflow

Source: https://rtlzeromemory.github.io/Zireael/dev/build-system

Commands to initialize the environment and build the project using the windows-clangcl-debug preset.

```powershell
.\scripts\vsdev.ps1
cmake --preset windows-clangcl-debug
cmake --build --preset windows-clangcl-debug
ctest --preset windows-clangcl-debug --output-on-failure
```

--------------------------------

### Configure, build, and test on Windows (clang-cl) with windows-clangcl-debug preset

Source: https://rtlzeromemory.github.io/Zireael/getting-started/install-build

Run these commands in order to configure, build, and test the project on Windows using the windows-clangcl-debug preset. The first command loads the Visual Studio developer environment, and the final ctest command runs tests with output on failure.

```powershell
.\scripts\vsdev.ps1
cmake --preset windows-clangcl-debug
cmake --build --preset windows-clangcl-debug
ctest --test-dir out/build/windows-clangcl-debug --output-on-failure
```

--------------------------------

### C++ example for Doxygen graph legend

Source: https://rtlzeromemory.github.io/Zireael/api/graph_legend.html

Defines classes with public, protected, private inheritance, a template class, and a used class to illustrate Doxygen graph conventions. The resulting graph uses filled gray for the target class, black borders for documented classes, gray borders for undocumented classes, and red borders for truncated graphs. Blue, dark green, dark red, purple dashed, and yellow dashed arrows indicate public, protected, private, containment, and template instantiation relations respectively.

```cpp
/*! Invisible class because of truncation */
class Invisible { };
/*! Truncated class, inheritance relation is hidden */
class Truncated : public Invisible { };
/* Class not documented with doxygen comments */
class Undocumented { };
/*! Class that is inherited using public inheritance */
class PublicBase : public Truncated { };
/*! A template class */
template<class T> class Templ { };
/*! Class that is inherited using protected inheritance */
class ProtectedBase { };
/*! Class that is inherited using private inheritance */
class PrivateBase { };
/*! Class that is used by the Inherited class */
class Used { };
/*! Super class that inherits a number of other classes */
class Inherited : public PublicBase,
protected ProtectedBase,
private PrivateBase,
public Undocumented,
public Templ<int>
{
private:
Used *m_usedClass;
};
```

--------------------------------

### Build documentation with docs script

Source: https://rtlzeromemory.github.io/Zireael/getting-started/install-build

Run the docs build script to generate documentation. It runs strict MkDocs and, when available, Doxygen generation, reusing the .venv-docs environment and honoring the $PYTHON variable.

```bash
bash scripts/docs.sh build
```

--------------------------------

### Fast local debug workflow for POSIX

Source: https://rtlzeromemory.github.io/Zireael/dev/build-system

Commands to configure, build, and test the project using the posix-clang-debug preset.

```bash
cmake --preset posix-clang-debug
cmake --build --preset posix-clang-debug
ctest --preset posix-clang-debug --output-on-failure
```

--------------------------------

### Zireael Wrapper Integration Skeleton

Source: https://rtlzeromemory.github.io/Zireael/abi/c-abi-reference

Basic engine initialization and shutdown sequence for a wrapper. Configure the engine with the requested ABI major, minor, and patch, plus drawlist and event batch versions, then call engine_create; check the returned zr_result_t and fail early if not ZR_OK. After the frame loop, destroy the engine with engine_destroy.

```c
zr_engine_config_t cfg = zr_engine_config_default();
cfg.requested_engine_abi_major = ZR_ENGINE_ABI_MAJOR;
cfg.requested_engine_abi_minor = ZR_ENGINE_ABI_MINOR;
cfg.requested_engine_abi_patch = ZR_ENGINE_ABI_PATCH;
cfg.requested_drawlist_version = ZR_DRAWLIST_VERSION_V2;
cfg.requested_event_batch_version = ZR_EVENT_BATCH_VERSION_V1;

zr_engine_t* e = NULL;
zr_result_t rc = engine_create(&e, &cfg);
if (rc != ZR_OK) {
  /* fail early */
}

/* frame loop... */

engine_destroy(e);

```

--------------------------------

### engine_create()

Source: https://rtlzeromemory.github.io/Zireael/api/zr__engine_8h.html

Creates a new engine instance with the given configuration.

```APIDOC
## engine_create()

### Description
Creates a new engine instance.

### Signature
```c
zr_result_t engine_create(zr_engine_t **_out_engine_, const zr_engine_config_t *_cfg_);
```

### Parameters
- `_out_engine_` (zr_engine_t**) - Required - Pointer to receive the created engine instance.
- `_cfg_` (const zr_engine_config_t*) - Required - Configuration for the engine.

### Returns
- `zr_result_t` - Result code indicating success or failure.
```

--------------------------------

### Build for POSIX (Linux/macOS)

Source: https://rtlzeromemory.github.io/Zireael/getting-started/quickstart

Commands to configure and build the project using CMake on POSIX systems.

```bash
cmake --preset posix-clang-debug
cmake --build --preset posix-clang-debug
```

--------------------------------

### Configure, build, and test Windows debug build with windows-clangcl-debug preset

Source: https://rtlzeromemory.github.io/Zireael/BUILD_TOOLCHAINS_AND_CMAKE

Typical Windows debug build using clang-cl. First runs the PowerShell script .\scripts\vsdev.ps1 to set up the environment, then cmake configure, build, and ctest with --output-on-failure.

```powershell
# PowerShell
.\scripts\vsdev.ps1
cmake --preset windows-clangcl-debug
cmake --build --preset windows-clangcl-debug
ctest --test-dir out/build/windows-clangcl-debug --output-on-failure
```

--------------------------------

### Run full test preset

Source: https://rtlzeromemory.github.io/Zireael/dev/testing

Executes the full test suite using the specified CTest preset.

```bash
ctest --preset posix-clang-debug --output-on-failure
```

--------------------------------

### Configure and build POSIX libFuzzer harness with posix-clang-fuzz preset

Source: https://rtlzeromemory.github.io/Zireael/BUILD_TOOLCHAINS_AND_CMAKE

Optional POSIX libFuzzer harness build using the posix-clang-fuzz preset. Runs cmake configure and build; no ctest command is shown.

```bash
cmake --preset posix-clang-fuzz
cmake --build --preset posix-clang-fuzz
```

--------------------------------

### Run guardrails and drift checks

Source: https://rtlzeromemory.github.io/Zireael/dev/testing

Executes project guardrails and version pin verification scripts alongside the test suite.

```bash
bash scripts/guardrails.sh
python3 scripts/check_version_pins.py
```

--------------------------------

### Configure, build, and test POSIX debug build with posix-clang-debug preset

Source: https://rtlzeromemory.github.io/Zireael/BUILD_TOOLCHAINS_AND_CMAKE

Typical POSIX debug build using the posix-clang-debug preset. Runs cmake configure, build, and ctest with --output-on-failure.

```bash
cmake --preset posix-clang-debug
cmake --build --preset posix-clang-debug
ctest --test-dir out/build/posix-clang-debug --output-on-failure
```

--------------------------------

### Run tests by build directory

Source: https://rtlzeromemory.github.io/Zireael/dev/testing

Executes tests located within a specific build directory.

```bash
ctest --test-dir out/build/posix-clang-debug --output-on-failure
```

--------------------------------

### Configure, build, and test POSIX ThreadSanitizer build with posix-clang-tsan preset

Source: https://rtlzeromemory.github.io/Zireael/BUILD_TOOLCHAINS_AND_CMAKE

Optional POSIX ThreadSanitizer build using the posix-clang-tsan preset. Runs cmake configure, build, and ctest with --output-on-failure.

```bash
cmake --preset posix-clang-tsan
cmake --build --preset posix-clang-tsan
ctest --test-dir out/build/posix-clang-tsan --output-on-failure
```

--------------------------------

### Sanitizer pass workflow for POSIX

Source: https://rtlzeromemory.github.io/Zireael/dev/build-system

Commands to configure, build, and test the project with address and undefined behavior sanitizers enabled via the posix-clang-asan-ubsan preset.

```bash
cmake --preset posix-clang-asan-ubsan
cmake --build --preset posix-clang-asan-ubsan
ctest --preset posix-clang-asan-ubsan --output-on-failure
```
Tokens:
Raw