Rerun C++ SDK

The Rerun C++ SDK allows logging data to Rerun directly from C++.

Getting started

Read the getting started guide on how to use the Rerun C++ SDK.

Logging

After you've installed the viewer and added the SDK to your project, you can jump right in and try logging some data.

You first create a rerun::RecordingStream stream and spawn a viewer. You then use it to log some archetypes to a given entity path using rerun::RecordingStream::log:

// Create a recording stream.
rerun::RecordingStream rec("rerun_example_app");
// Spawn the viewer and connect to it.
rec.spawn().exit_on_failure();
 
std::vector<rerun::Position3D> points = create_positions();
std::vector<rerun::Color> colors = create_colors();
std::vector<uint8_t> image_data = create_image();
 
// Log a batch of points.
rec.log("path/to/points", rerun::Points3D(points).with_colors(colors));
 
// Log an image.
rec.log("path/to/image", rerun::Image::from_rgba32(image_data, {786, 1024}));

Streaming to disk

Streaming data to a file on disk using the .rrd format:

rerun::RecordingStream rec("rerun_example_app");

rec.save("example.rrd").exit_on_failure();

Connecting

Instead of spawning a new viewer, you can also try to connect to an already open one.

rerun::RecordingStream rec("rerun_example_app");
auto result = rec.connect_tcp(); // Connect to local host with default port.
if (result.is_err()) {
    // Handle error.
}

Buffering

As long as you haven't called rerun::RecordingStream::save/rerun::RecordingStream::connect/rerun::RecordingStream::spawn any data will be kept in memory until you call one of these.

rerun::RecordingStream rec("rerun_example_app");
 
// Log data to the internal buffer.
rec.log("path/to/points", rerun::Points3D(points).with_colors(colors));
 
// Spawn & connect later.
auto result = rec.spawn();
if (result.is_err()) {
    // Handle error.
}

Examples

As general entry point for Rerun examples check the examples page on our website. All C++ examples can be found directly in the Rerun repository. Additionally, each archetype's documentation comes with at least one small self-contained code example.

Building blocks

The most important type in the SDK is the rerun::RecordingStream. It allows you to connect to the Rerun Viewer and send data.

The built-in types are distributed to the respective namespaces:

If you include rerun.hpp, all archetypes and most component types become part of the rerun namespace.

Check the general doc page on types to learn more.

Build & distribution

Overview

From a build system perspective, the SDK consists of three dependencies:

C++ SDK source
- This includes both source and header files!
- To avoid compatibility issues across different platforms, compiler versions and C++ standard library versions we recommend to build the C++ SDK directly from source. Note that this also what happens when you follow the CMake setup in the quickstart guide.
rerun_c static libraries
- Rerun C is a minimal C SDK and forms the bridge to the shared Rust codebase
- Due to the rigidity of the C ABI and lack of complex standard library types in the interface, compatibility issues between compilers are less of a concern which is why we offer pre-built libraries with every release for all major platforms
Apache Arrow C++ library
- The SDK uses this library to perform all serialization before handing data over to rerun_c
- See Install arrow-cpp for how to install this library

SDK bundle (rerun_cpp_sdk.zip)

For convenience, Rerun provides a C++ SDK bundle with every release. (this includes our regular Development Builds!)

This is a simple zip archive containing the SDK from the repository (excluding the tests folder) and a lib folder with prebuilt rerun_c libraries for all major desktop platforms. The rerun_c libraries follow a simple name schema that the CMake script can pick up.

Building with CMake

See CMake Setup in Detail for deeper dive on how to use the SDK's CMakeLists.txt and an overview over all CMake configuration options.

Without CMake

We don't have first class support for other build systems yet, but it should be possible to setup Rerun C++ without CMake fairly easily:

You have to add all files from the src/ folder either directly to your project or a library. In addition, you need to link the rerun_c libraries and the Arrow C++ library. For more information on how to install Arrow, see Install arrow-cpp.

Make sure to compile with C++17 or newer.

Bazel

There's a user provided minimal Bazel example here: https://github.com/kyle-figure/bazel-minimal-rerun/

Install with conda package

If you are using a package manager that supports conda packages such as conda or pixi to manage your C++ dependencies, the Rerun C++ SDK is available from conda-forge channel in the [librerun-sdk package](). After you installed the librerun-sdk package. The Rerun Viewer is instead provided by the rerun-sdk package, and you can install both with:

conda install -c conda-forge librerun-sdk rerun-sdk

or

pixi add librerun-sdk rerun-sdk

Once the package is available, you can find and consume it in your CMake project as you consume any other installed C++ library that provides a CMake config file:

find_package(rerun_sdk REQUIRED)
 
# …
 
target_link_libraries(<yourtarget> PRIVATE rerun_sdk)

Development in the Rerun repository

Refer to the build instruction at the repo root.

Keep in mind that all archetypes/components/datatypes are mostly generated by the Rerun types builder. Use pixi run codegen to run code generation. Generally, all generated code files are part of the repository, so you only have to do that if you change the data definition or make changes to _ext.cpp files which extend generated types.

Tested compilers

The Rerun C++ SDK requires a C++17 compliant compiler.

As of writing we tested the SDK against:

Apple Clang 14, 15
GCC 9, 10, 12
Visual Studio 2022

Table of Contents