Candlewick: a WIP renderer based on SDL_gpu

Warning

Candlewick is still under active development. Support will be limited, and the API might break unexpectedly and repeatedly.

Candlewick is a WIP library for a renderer based on SDL3's new GPU API.

Features

Candlewick comes with a set of graphical, interaction, and utility features.

Graphical features

• Shadow mapping using directional shadow maps
• Screen-space ambient occlusion (SSAO)
• WIP: Screen-space shadows (SSS)

Interactivitity

• Integration with ImGui
• (optional) Record videos from the main window using FFmpeg

Pinocchio visualizer

Candlewick visualization utilities for robotics based on Pinocchio.

You can load a Pinocchio model, its geometry model, and create a visualizer that can be used similar to the other visualizers included in pinocchio.visualize. Here's a Python example:

import example_robot_data as erd
import pinocchio as pin
import numpy as np
from candlewick.multibody import Visualizer, VisualizerConfig

robot = erd.load("ur10")
model: pin.Model = robot.model
data: pin.Data = robot.data
visual_model = robot.visual_model

config = VisualizerConfig()
config.width = 1280
config.height = 720
viz = Visualizer(config, model, visual_model)

q0 = pin.neutral(model)
viz.setCameraPose(pin.SE3.Identity())
viz.display(q0)

Installation

Dependencies

Candlewick depends mainly on:

• SDL3 for windowing, processing input events, and of course SDL GPU.
• EnTT for the entity-component system (ECS)
• nlohmann/json for processing JSON files
• the Eigen linear algebra template library
• the Coal collision algorithms library
• magic_enum (enum reflection library)
• Open Asset Importer Library (assimp) for loading meshes

These dependencies can be installed from Conda as follows:

conda install sdl3 eigen magic_enum assimp entt nlohmann_json

Optional dependencies

• eigenpy for Python bindings.
• FFmpeg for support for recording videos from the rendered graphics. The CMake finder module also requires pkg-config.

  conda install ffmpeg pkg-config

• GoogleTest for the tests | conda install gtest
• CLI11 for the examples and tests | conda install cli11
• The Pinocchio rigid-body dynamics library (required for the candlewick::multibody classes and functions). Pinocchio must be built with collision support. | conda-forge

Building

For building the library, you will need CMake (version at least 3.20) and a C++17-compliant compiler. These can also be obtained through Conda.

In the directory where you have checked out the code, perform the following steps:

# 1. Create a CMake build directory
cmake -S . -B build/ -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_PINOCCHIO_VISUALIZER:BOOL=ON \  # For Pinocchio support
  -DBUILD_PYTHON_BINDINGS:BOOL=ON \ # For Python bindings
  -GNinja \ # or -G"Unix Makefiles" to use Make
  -DCMAKE_INSTALL_PREFIX=<your-install-prefix> # e.g. ~/.local/, or $CONDA_PREFIX
# 2. Move into it and build (generator-independent)
cd build/ && cmake --build . -j<num-parallel-jobs>
# 3. Install
cmake --build . --target install

Credits

Many of the design choices of this library are heavily inspired by other, more mature work in the open-source 3D graphics middleware space.

Here are some of the resources I've looked at:

• the Magnum graphics middleware (the design ideas around mesh layouts, how to load geometry primitives, and the type-erased MeshData type)
• bgfx
• Sascha Willems' Vulkan examples: https://github.com/SaschaWillems/Vulkan/