This repository contains the source for the ANARI API SDK. This includes:
- Front-end library + implementation guide
- Device implementation utilties for implementations
- Example device implementation (not intended for production use)
- Example GPU device implementation (in-progress, requires SDL3)
- Embree/ISPC CPU device with a path tracer (requires ISPC)
- Device rendering through OpenUSD Hydra render delegates (requires OpenUSD)
- Device that captures committed scene state as text, plus a capture diff tool (for testing what an application hands ANARI)
- MPI data-parallel compositing device that wraps another device (requires MPI and oneTBB)
- Example applications
- Interactive sample viewer
- Render tests
- OpenUSD Hydra plugin
The ANARI specification can be found on the Khronos website here.
The SDK is tested on Linux, but is also intended to be usable on other operating systems such as macOS and Windows.
If you find any problems with the SDK, please do not hesitate to open an issue on this project!
The ANARI-SDK is available as the anari package in
vcpkg. Simply follow these
instructions for setting up your
environment to use vcpkg, then run the following to get ANARI:
% vcpkg install anariThe repository uses CMake 3.11+ to build the library, example implementation, sample apps, and tests. For example, to build (must be in a separate directory from the source directory), you can do:
% cd /path/to/anari
% mkdir build
% cd build
% cmake ..Using a tool like ccmake or cmake-gui will let you see which options are
available to enable. The following CMake options are offered:
BUILD_SHARED_LIBS: build everything as shared libraries or static librariesBUILD_CAT: build the capability analysis toolBUILD_CTS: build the conformance test suiteBUILD_TESTING: build unit and regression test binariesBUILD_HELIDE_DEVICE: build the provided examplehelidedevice implementationBUILD_HELIDE_GPU_DEVICE: build the provided examplehelide_gpuGPU device (needs SDL3)BUILD_HALCYON_DEVICE: build thehalcyonEmbree/ISPC CPU device (needs an ISPC compiler)BUILD_HYDRA_DEVICE: build thehydradevice, which renders through OpenUSD Hydra render delegates (needs OpenUSD)BUILD_CAPTURE_DEVICE: build thecapturedevice and theanariCaptureDifftool (on by default)BUILD_PTC_DEVICE: build theptcMPI data-parallel compositing device (needs MPI and oneTBB 2021.6+)BUILD_REMOTE_DEVICE: build the provided experimentalremotedevice implementationBUILD_EXAMPLES: build example applicationsBUILD_VIEWER: build viewer too (needs SDL3) if building examplesBUILD_HDANARI: build (experimental) OpenUSD Hydra delegate plugin
Once built, the library can be installed via the install target created by
CMake. This can be invoked from your build directory with (on any platform):
% cmake --build . -t installThe ANARI SDK exports CMake targets for the main front-end library and utilities helper library. The targets which are exported are as follows:
anari::anari: dynamically link the main ANARI API library targetanari::anari_static: statically link the main ANARI API library targetanari::helium: library containing base device implementation abstractions (static)
These targets can be found with CMake via find_package(anari). The examples
are written such that they can be built stand alone from the SDK source tree.
The simplest usage can be found here.
Note that anari::helium will still require linking either anari::anari or
anari::anari_static to give consumers the option whether to link the ANARI
API dynamically or statically.
The following additional helper library components can be requested by listing
them under find_pacakge(anari):
viewer: Source library targetanari::anari_viewerfor building small viewer appscode_gen: Enable the use of code generation CMake functions downstream
Both of these libraries are optionally installed and are not available to
downstream projects unless they are explicitly requested. To request one of
these components, simply add them to the COMPONENTS portion of find_package:
find_package(anari COMPONENTS viewer code_gen)The basic tutorial app (built by default) uses the helide device as an
example, which can be run with:
% ./anariTutorialN
8000
ote that running the tutorial will require that the helide device is enabled
in your build with the CMake option BUILD_HELIDE_DEVICE=ON.
The viewer application (enabled with BUILD_VIEWER=ON) by default uses the
environment library, which reads ANARI_LIBRARY as an environment variable to
get the library to load. For example it can be run with:
% export ANARI_LIBRARY=helide
% ./anariViewerAlternatively, either --library or -l can be used on the viewer's command
line to override the ANARI library to be loaded.
The regression test binary (anariRenderTests) used to render the test scenes
without a window (results saved out as PNG images) uses the same mechanisms as
the viewer to select/override which library is loaded at runtime.
An example device implementation helide is provided as a starting point for users exploring the SDK and for implementors to see how the API might be implemented. It implements a very simple ray tracing implementation using Embree for intersection. Users should look to use vendor provided, hardware-optimized ANARI implementations which are shipped independently from the SDK. (see below)
A GPU-accelerated example device helide_gpu is also
available. It uses SDL3's cross-platform GPU abstraction layer for rendering and
is currently in-progress. Build it with BUILD_HELIDE_GPU_DEVICE=ON (requires
SDL3 3.2+ and glslangValidator in PATH).
The halcyon device is a CPU device built on Embree and
ISPC, with a preview renderer modelled on helide and a quality path tracer
ported from Typhoon with MaterialX materials. Build it with
BUILD_HALCYON_DEVICE=ON (requires an ISPC compiler and CMake 3.19; built and
tested on Linux only so far).
The hydra device renders ANARI scenes through OpenUSD
Hydra render delegates (Storm, HdEmbree, ...), one device subtype per
delegate. It is the reverse of the hdAnari plugin, which renders
Hydra scenes through ANARI. Build it with BUILD_HYDRA_DEVICE=ON (requires
OpenUSD, found through CMAKE_PREFIX_PATH).
The capture device renders nothing. On each frame it
writes a canonical text snapshot of the committed object graph the frame can
reach, so an application can test exactly what it hands ANARI without depending
on any device's pixels. The anariCaptureDiff tool (and the anari_capture_diff
library) compares two captures with optional float tolerances. It is built by
default (BUILD_CAPTURE_DEVICE); see its
README for the format.
The ptc device makes an ANARI application data-parallel
with MPI: each rank renders its own data with a wrapped device (helide by
default) and ptc composites the ranks' images by depth onto one rank. Build it
with BUILD_PTC_DEVICE=ON (requires MPI and oneTBB 2021.6 or newer); see its
README for usage and compositing semantics.
The ANARI-SDK ships with a debug layer implemented as an
ordinary ANARIDevice which wraps a device (set as the wrappedDevice
parameter on the debug device). This device uses the object queries reported by
the wrapped device to validate correct usage of object subtypes, parameters, and
properties, as well as validate correct object lifetimes. The wrapped device is
then used to actually implement the ANARI API to allow applications to still
function normally.
The device can be created by using the normal library loading mechanics using
anariLoadLibrary("debug", ...), creating a the debug device instances with,
anariNewDevice(debugLibrary, "default"), and then creating a device to use
and set it on the device with
anariSetParameter(debugDevice, "wrappedDevice", ANARI_DEVICE, &wrappedHandle).
As a convenience, users can use the ANARI_DEBUG_WRAPPED_LIBRARY environment
variable to have the debug device do the mechanics of loading and creating the
underlying wrapped library. For example, you can do the following to run the
viewer with the debug device wrapping helide:
% ANARI_LIBRARY=debug ANARI_DEBUG_WRAPPED_LIBRARY=helide ./anariViewer
Or using the -l syntax for specifying the library:
% ANARI_DEBUG_WRAPPED_LIBRARY=helide ./anariViewer -l debug
See the simple debug device turorial for how to setup the debug device without using environment variables.
Note that if ANARI_DEBUG_WRAPPED_LIBRARY is set, it will take priority over
programatically set wrapped devices.
Tracing features of the debug device can be set using the following environment variables:
ANARI_DEBUG_TRACE_MODEsets the tracing mode, onlycodeis supported for now.ANARI_DEBUG_TRACE_DIRset the folder where the trace will be dumped.
- ANARI-WebGPU
- Cycles (Blender's path tracer)
- halcyon (Embree/ISPC CPU device with a path tracer)
- Halogen (built on Filament)
- helide
- helide_gpu
- hydra (OpenUSD Hydra render delegates)
- Intel OSPRay
- NVIDIA Barney (MPI distributed renderer)
- NVIDIA USD
- NVIDIA VisRTX
- Photon
- ptc (MPI data-parallel compositing over another device)
- Visionaray
- Viskores
If you implement a backend to the ANARI SDK, please open a PR to add it to this list!
- ANARI-Java (Java language bindings)
- Blender (via Python addon)
- COVISE
- HayStack
- OVITO
- OpenUSD (via hdAnari plugin)
- ParaView
- pynari (Python language bindings)
- Sneeze (Open Metaverse Browser Initiative)
- Vela
- VisIt
- Viskores
- Vistle
- VTK
If you integrate ANARI into your application, please open a PR to add it to this list!