ANARI^™ 1.0.0 – Specification

The ANARI specification is intended for use by both implementors of the API and application developers seeking to make use of the API, forming a contract between these parties. Specification text may address either party; typically the intended audience can be inferred from context, though some sections are defined to address only one of these parties. Any requirements, prohibitions, recommendations or options defined by normative terminology are imposed only on the audience of that text.

The ANARI API is specified as a C99 API in order to provide compiler-independent linkage, thereby supporting easy integration into a broad range of applications based on a variety of compiled languages, including C, C++, Fortran, and dynamic languages such as Python and Julia, among others. C99 provides improved IEEE-754 floating point rounding behavior, integer types in common with C++, and other refinements relative to ANSI C.

ANARI is specified as a common API header and front-end library (using either static or dynamic linkage) capable of loading available ANARI back-end device implementations at runtime, known as devices. ANARI back-end devices are created by standard implementors and are expected to be distributed, installed, or upgraded independently of the standard API header and front-end library.

The ANARI API is designed to encapsulate scene data and rendering operations as opaque object handles using string-value pairs to parameterize them. This facilitates a dominantly unidirectional flow of scene information from the application to the instantiated ANARI device. As a result, the vast majority of ANARI API calls have a write-only behavior pattern to minimize imposed implementation requirements.

An application can create ANARI objects and set named inputs on them called parameters. However, no mechanism is provided to subsequently query parameter data, since even the existence of a query mechanism would impose additional performance and storage restrictions for back-end renderer implementations (e.g. distributed rendering contexts). Object introspection can be used to query object subtypes and information about their parameters.

Additionally, ANARI objects can publish named outputs called properties. Such output is specific to the type and semantics of the object, but has a generic interface function for access.

The ANARI specification defines a set of usable extensions exposed via the C API. Extensions are loosely defined as observable behavior from a particular use of the ANARI API. This most commonly is the existence of usable object subtypes, but also can be pre/post conditions on a function call, specific behavior of an object parameter, or guaranteed availability of a property.

Applications can query extensions made available by a device implementation through queries either on the library or the live device instance. Querying available extensions via the library represents the list of extensions implemented by the vendor at all, while querying extensions on a live device instance will also factor in the runtime environment (i.e. available underlying hardware to the device). In either case, extension queries are intended to be the way an application determines if the device is acceptable in meeting the application’s requirements, or if the application wants to adapt itself to what extensions are available.

Extensions are extensions that have not yet made it into the ANARI specification. These extensions are reported in the same list as core extensions, but have vendor specific names, which may exist in more than one device from that vendor. This is a good way for vendors to agree upon and get experience with a extension prior to bring it officially into the specification.

All extensions represent functionality which provides additional capabilities to the application. A reported extension should never represent a reduction in capability.

Testable extension names are inlined in the specification alongside their definition. All extensions follow the prefix convention of ANARI_[VENDOR]_[NAME], where ratified extensions use KHR as the vendor string.

Implemented extensions may be queried via Object Introspection functions. Currently available extensions for devices and renderers may be queried via Object Properties functions.

A full list of ANARI extensions can be found in the Extension Index appendix.

ANARI is designed to be compatible with applications which are distributed across multiple processes which may reside on multiple machines. ANARI implementors provide distributed rendering capabilities using existing API semantics relevant to running in distributed environments, such as multiple processes invoking API calls in lock-step.

The ANARI API may be called from any thread but calls that share objects must be synchronized and may not overlap. By default, this includes the device. Therefore, calls to the same device must be externally synchronized.

Expensive operations can be implemented asynchronously, which avoids blocking the calling application. Each asynchronous operation is specified as to what API calls are legal to make while the operation has not yet completed.

Devices that implement extension KHR_DEVICE_SYNCHRONIZATION relax synchronization requirements by excluding the device from the external synchronization requirement if the device is passed as the first argument only. Calls that are operating on the device as the object must still be synchronized with all other calls involving the same device. Likewise anariRenderFrame must be synchronized with all other ANARI calls as well. This only applies to the anariRenderFrame call itself, not the asynchronous render operations which remain subject to asynchronous rendering restrictions.

This lowers the scope of required synchonization to individual ANARI objects allowing different threads to operate concurrently on different objects within the same device.

ANARI scenes are represented as hierarchies of objects. This section describes their relationship to each other.

The Frame is the root object of the scene. It holds the framebuffer configuration and the World, Camera, and Renderer objects. The Camera configures the projection of the rendering used to view the World. The Renderer holds parameters relating to the rendering algorithm. The World holds arrays of the drawable objects of the scene such as Surface, Volume, and Light either directly or via an array of Instance containing Group. A Group holds arrays of Surface, Volume, and Light to be instanced together. An Instance combines a Group with a transform for placement of the same collection of objects at multiple locations within the same World. A Surface represents drawable surfaces containing a Geometry and a Material. A Geometry specifies drawable primitives and data associated with them. A Material specifies the surface’s appearance related to the data from the Geometry. A Volume represents volumetric drawable objects and may contain Spatial Field objects. A Spatial Field represents a field of values in 3D space. A Light represents sources of illumination.

The following diagram illustrates the relationships described above:

All objects are characterized by the following items

Objects and devices in ANARI are represented by opaque 64-bit handles. The NULL handle never represents a valid object. Handles are only valid for the device from which they were created, and using handles with other devices leads to undefined behavior.

Objects are created by calling an anariNew factory function (for example anariNewGeometry). Each object type has its own corresponding factory function. All objects, including devices, are only valid in the process in which they are created.

Object lifetime is managed by opaque reference counting. Objects have a public and internal reference count. Objects are created with a public reference count of 1, which can be increased with anariRetain and decreased with anariRelease. Once the public reference count has been decreased to 0, the object becomes inaccessible to host code, where using its handle in subsequent API calls is invalid and results in undefined behavior.

The signatures to anariRelease and anariRetain are as follows

Calling anariRelease with a NULL object-handle for the second argument is not an error. The internal reference count is managed by the API and will keep objects alive for as long as the implementation needs them. Therefore, user code may release objects as soon as it no longer requires access to them.

Objects are configured by parameters, which are identified by a string name and are set using anariSetParameter. Multiple types can be valid for a parameter, but only one type can be set for a particular parameter name at any given time. Setting a parameter with a different type overwrites its previous value and type. Attempting to set a parameter that is unknown to the implementation has no effect on object state, but may cause an ANARI device implementation to emit warnings. The same applies if an unsupported type for a parameter is used.

The signatures to anariSetParameter is as follows

The ANARI_STRING valued parameter named name on all object types is reserved across all implementations and can optionally be used by applications to inject human readable identifiers into the command stream. This can be useful for debugging purposes, for example. Implementations are allowed to ignore this parameter and must not emit warnings when it is present.

Changes to parameter values must only take effect once anariCommitParameters has been called on the object:

Uncommitted parameters must have no effect on the behavior of the object during rendering operations.

Data types passed to and returned from ANARI are specified using the ANARIDataType enum. The enum values identify ANARI object data types and C data types. Types starting with ANARI are provided by the ANARI headers. All other types refer to C99 types. See Table 1 below for a complete list.

Values set on objects are passed as a void * in anariSetParameter, which points to the value to be read. The type is encoded by the passed in ANARIDataType enum. For example, this means that, given ANARI_INT, the implementation casts the input void * value to int * and dereferences it accordingly. There are, however, two exceptions: ANARI_STRING and ANARI_VOID_POINTER (const char * and void * respectively) are object pointer based types, so they are instead passed by value.

Object parameters can be unset using anariUnsetParameter, which returns the named parameter back to a state as if it had not been set. Just like with setting parameters, changes made by anariUnsetParameter must only be applied when the object is committed.

The signature to anariUnsetParameter is as follows

Similarly, all parameters on an object can be simultaneously unset using anariUnsetAllParameters, which returns the object back to a state as if no parameters had been set at all. Just like with unsetting individual parameters, changes made by anariUnsetAllParameters must only be applied when the object is committed.

The signature to anariUnsetAllParameters is as follows

Floating point number (data types with FLOAT) layout and behaviour are as specified in [ieee-754].

ANARI supports introspection of objects, i.e., querying supported extensions, object subtypes and information about their parameters, which is particularly useful to enumerate and inspect implementation-specific object extensions. The intended use is to allow for building a graphical user interface for, e.g., specific renderers or materials, and to provide hints for the debug layer to aid in validating extensions.

The information queried with the following functions is static and will reflect what the implementation is capable of supporting. If a extension is unavailable for runtime dependent reasons, for example due to missing hardware support, the device may still advertise the associated parameters and object subtypes. The dynamic runtime extension availability can be queried using properties.

Device subtypes and their implemented extensions can be queried from a library before instantiating a device. Object and parameter specific information can be queried from an instantiated device object.

A list of device subtypes implemented in a library is retrieved by calling anariGetDeviceSubtypes. It returns NULL if there are no devices, or a NULL-terminated list of 0-terminated C-strings with the names of the devices. The first (if any) device is the default device.

The list extensions implemented by a device is retrieved by calling anariGetDeviceExtensions with a device subtype returned by anariGetDeviceSubtypes. It returns a NULL-terminated list of 0-terminated C-strings with the names of the implemented extensions.

To enumerate the subtypes of type objectType supported by device deviceSubtype call function anariGetObjectSubtypes. It returns NULL if there are no subtypes, or a NULL-terminated list of 0-terminated C-strings with the names of the subtypes. The following object types are expected to have subtypes:

An object (sub)type objectType/objectSubtype can be queried for information with anariGetObjectInfo (passing NULL or an empty string for objectSubtype to query an object type directly that does not have subtypes). The function returns the result for infoName of type infoType, or NULL if the info cannot be retrieved. The following infos of objects can be queried:

Parameters that can be of multiple types are reported multiple times (once for each supported variant: with the same name, but different type).

Finally, a parameter can be inspected with anariGetParameterInfo, returning the result for infoName of type infoType, or NULL if the info cannot be retrieved. The following infos of parameters can be queried:

Implementations may expose object properties through the object query interface.

Properties are identified by a string name and type. The waitMask indicates whether the property query will wait for the value to become available or should return instantly.

If the property is available, the value will be written to memory, and the function returns 1. Otherwise, the value is not written to memory, and the return value is 0.

The length of a string property can be queried as an ANARI_ULONG by appending .size to the property name.

At most size bytes will be written to memory.

There are two methods of expressing array data on objects: directly mapping array elements on an object parameter in order to write data elements, or creating array objects represented by a handle.

The first method lets applications directly map a device’s internally-managed one, two, or three dimensional array data on any given object using

Each of these functions return a write-only array for the application to fill, where the number of elements numElementsN must be positive (there cannot be an empty mapped array). Whenever an array is directly mapped, any previous array configuration (size, dimensionality, etc.) is discarded in favor of the currently mapped array configuration.

Devices are only required to allocate directly mapped arrays for parameters corresponding to extensions that the device implements. In cases where the parameter is unknown by the device, the device is permitted to return NULL.

Devices are permitted to have a non-dense element stride, which is returned by writing to elementStride. The elementStride argument must not be NULL.

Once the array has been filled, applications signal that the device is free to consume the data with

Directly mapped arrays behave like normal parameters in that the underlying array data will not be used in the next rendered frame until the object itself is committed with anariCommitParameters. Furthermore, using anariUnsetParameter will subsequently reset the parameter to an unset state, effectively clearing the previously mapped array on the object. Using anariSetParameter, anariMapParameterArray, or anariUnsetParameter on an array that is still mapped is an error – applications must first unmap the array before altering the parameter through other means. Writing to the mapped pointer after calling anariUnmapParameterArray is undefined behavior and should be avoided.

The second method of expressing array data on objects uses handles. ANARIArray handles represent data arrays in memory, which are shared with device implementations. The memory shared with ANARI can be either owned by the application, have ownership transferred to the device via a deleter callback, or be managed by the device.

The signature of the deleter is provided in anari.h as

To create a data array, use any of the following API calls based on the desired dimension:

The number of elements numElementsN must be positive (there cannot be an empty array object).

In each creation function a deleter can be passed in (with an associated pointer to any needed application data or state), which ANARI will use to free the original pointer passed during construction. If the application passes NULL, ANARI will fully rely on the application to free the memory.

When appMemory is not NULL, then the array is considered to be a shared array, where both the application and device observe the same memory. Passing NULL in appMemory creates a managed array. The backing memory of the array is managed by the device and is only writable via mapping.

Applications are permitted to release ANARIArray objects even if the device still contains internal references to it. When releasing a shared array object ANARI relinquishes shared ownership of the memory, which may result in the creation of internal copies. When a shared array is created with a deleter callback, it is implementation defined when an implementation frees host memory after the array object has been released. Deleter callbacks are never called for managed arrays.

Applications are only permitted to write to the memory visible to ANARIArray objects if all array objects involved are mapped. Mapping a shared array object indicates that the device should not execute any rendering operations (or internal state updates, such as building acceleration structures) of any parent objects to the mapped array object which is directly referencing mapped memory.

Array objects are mapped using

Mapped array objects are unmapped using

Mapping a shared array will always result in the same address originally used when constructing the array object. Mapping a managed array may return a different pointer each time it is mapped. The contents of memory mapped from managed arrays is undefined until written to and the entire mapped range must be specified before unmapping to avoid populating the array with undefined values.

ANARIArray objects containing object handles increase the ref count of all objects in the array. Reference counts are updated on creation of the array object and when unmapping the array.

Use of the arrays inside ANARI may cause accesses at indices derived from parameters or other arrays (for example when drawing an indexed geometry). Out of bounds accesses caused this way have undefined behavior.

Arrays define a valid region of elements, which by default is always the full capacity of the array. Implementations can allow applications to keep a singular allocation of data, but use a parameter to tell the implementation only to use a subset of elements. This gives applications the ability to more efficiently change the number of elements used by parent objects at the cost of memory size efficiency.

Implementations provide this functionality by implementing extension KHR_ARRAY1D_REGION, which adds the following parameter to ANARIArray1D:

If region is not set, all elements are used as specified when the array was constructed. When region is set, it is clamped to the range of the array’s constructed size respectively and warnings should be emitted by the debug layer if region.upper is larger than capacity.

The values specified by region are clamped such that the array will always be a valid range containing at least one element. Thus region is clamped according to the following:

Mapping an array always returns the full capacity, regardless of the elements specified by region. Object handles within region must always be valid. Object arrays can be constructed with invalid handles, as long as the array region contains only valid handles by the time the array is used in a render operation.

ANARI libraries are the mechanism that applications use to manage API device implementations. Libraries are solely responsible for creating instances of devices. Implementors may use a library to cache data or objects which are truly global to their device implementations, such as contexts from underlying APIs. Libraries are generally the first thing loaded by an application and the last thing cleaned up. While libraries are represented by an opaque handle, they are not considered an object per the given definition of an object and are thus only usable in API calls which explicitly take ANARILibrary handles.

To load a library, use

This will look for a shared library named anari_library_[name], open it, and look for entry points for (implementation defined) initialization. The status callback passed is used as the default value for the statusCallback parameter on devices created from the returned library object. Similarly, the user pointer passed is used as the default value for the statusCallbackUserData device parameter.

To unload a library (where library resource cleanup occurs), use

It is undefined behavior to unload a library while instances of devices from that library have not been released.

ANARI coordinates the use of one or more devices. A device is an object which provides the implementation of all ANARI API calls outside of libraries. Devices represent the global state which an implementor may reuse between different objects to render images. It is common for applications to only use one device at a time, but the API permits concurrent use of multiple devices to independently render from each other.

The ANARI device is responsible for coordinating the sharing of execution resources with the calling application, such as a CPU thread pool or GPU kernel queues.

ANARI devices are represented by an ANARIDevice handle and created using

Version information can be queried as properties on the ANARIDevice using anariGetProperty.

Errors and other messages (warnings, validation messages, debug information etc.) from the device are reported via a status callback. The status callback function can be set using

The following values for ANARIStatusCode are defined:

The following values for ANARIStatusSeverity are defined:

Statuses may be reported at an undefined time after the API call causing them is made. Furthermore, these callbacks must themselves be thread safe as they can be called on any thread.

Attributes are quantities that are passed between objects during rendering. Attributes are identified by strings.

Surface attributes are passed from geometries to materials and samplers. Attributes are either set explicitly by user-provided data as array parameters (and may be interpolated in a geometry-specific way) or implicitly by the surface. Unspecified (components of) attributes default to zero for the first three components and to one for the fourth component.

The frame contains all the objects necessary to render and holds the resulting rendered 2D image (and optionally auxiliary information associated with pixels). To create a new frame, use

The frame uses parameters to encode size, color format, and which channels to use. Channels are identified by string channel names beginning with channel.. The frame object has an identically named parameter for each reported channel. Setting these parameters to one of the allowed data types enables the channel and determines the data type it can be mapped as. The same channel names are used to map the channel contents with anariMapFrame. Each channel has its own associated extension name.

The world, camera, renderer, and size parameters are required, size must be positive.

The extension KHR_FRAME_ACCUMULATION indicates that implementations use progressive rendering techniques like Monte Carlo integration and thus that multiple subsequent calls to anariRenderFrame without changes to Frame improve the image quality (e.g., reduce noise levels).

The following information can be queried as properties on the ANARIFrame using anariGetProperty.

Devices which implement extension KHR_FRAME_COMPLETION_CALLBACK add two parameters to Frame: a callback invoked as a continuation after the frame completes, and an associated pointer to application state to be passed to the invoked continuation. This continuation must be complete before returning from anariFrameReady() when called with ANARI_WAIT.

The signature of the continuation is provided in anari.h as

Cameras express viewpoint and viewport projection information for rendering a scene. To create a new camera of given type subtype use

All cameras sources accept the following parameters:

The camera is placed and oriented in the world with position, direction and up. ANARI uses a right-handed coordinate system.

The region of the camera sensor that is rendered to the image can be specified in normalized screen-space coordinates with imageRegion. This can be used, for example, to crop the image, to achieve asymmetrical view frusta, or to horizontally flip the image to view scenes which are specified in a left-handed coordinate system. Note that values outside the default range of [0–1] are valid, which is useful to easily realize overscan or film gate, or to emulate a shifted sensor.

The externsion KHR_CAMERA_DEPTH_OF_FIELD indicates that cameras support depth of field via the apertureRadius and focusDistance parameters.

The extension KHR_CAMERA_STEREO indicates that a renderer permits 3D stereo rendering, which is enabled by setting stereoMode and interpupillaryDistance.

Extension KHR_CAMERA_MOTION_TRANSFORMATION: Uniformly (in time) distributed transformation keys can be set with motion.transform to achieve camera motion blur (in combination with extension KHR_CAMERA_SHUTTER). Alternatively, the transformation keys can also be given as decomposed motion.scale, motion.rotation and motion.translation.

The extension KHR_CAMERA_ROLLING_SHUTTER depends on extension KHR_CAMERA_SHUTTER.

A renderer is the central object for rendering in ANARI. Different renderers implement different extensions, rendering algorithms, and support different materials. To create a new renderer of given subtype subtype use

Every ANARI device offers a default renderer, which works without setting any parameters (i.e., all parameters, if any, have meaningful defaults). Thus, passing default as subtype string to anariNewRenderer will result in a usable renderer. Further renderers and their parameters can be enumerated with the Object Introspection API. The default renderer is an alias to an existing renderer that is returned first in the list by anariGetObjectSubtypes when queried for RENDERER. Also refer to the documentation of ANARI implementations.

Extension support information can be queried as properties on the ANARIRenderer using anariGetProperty.

Extension: KHR_RENDERER_BACKGROUND_COLOR

Extension: KHR_RENDERER_BACKGROUND_IMAGE

The background image will be rescaled to the size of the Frame by linear filtering.

If both KHR_RENDERER_BACKGROUND_COLOR and KHR_RENDERER_BACKGROUND_IMAGE are supported the background parameter can accept either type.

Extension: KHR_RENDERER_AMBIENT_LIGHT

The ambient light is a light with an invisible source which surrounds the scene and illuminates it from infinity.

Worlds are a container of scene data represented by instances. Worlds are created with

Objects are placed in the world through an array of instances, geometries, volumes, or lights. Similar to instances, each array of objects is optional; there is no need to create empty arrays if there are no instances (though there might be nothing to render).

Instances apply transforms to groups for placement in the World. Instances are created with

All instances take an array of [group] representing all the objects which share the instances world-space transform. They also always take a generic FLOAT32_MAT4 transform which serves as a fall back but may be overriden by subtype specific transform definitions.

The matrix transform represents an affine transformation which is applied to homogeneous coordinates.

Groups in ANARI represent collections of [surface], [volume], and [light] which share a common local-space coordinate system. Groups are created with

Each array on a group is optional; there is no need to create empty arrays if there are no surfaces, no volumes, or no lights instanced.

Lights in ANARI are virtual objects that emit light into the world and thus illuminate objects. To create a new light object of given subtype subtype use

All light sources accept the following parameters:

The transformation of an instance apply only to vectors like position or direction of a light, but not to affect sizes like radius (extension KHR_AREA_LIGHTS).

Geometries are matched with appearance information through Surfaces. These take a geometry, which defines the spatial representation, and applies either full-object or per-primitive color and material information. Surfaces are created with

Surfaces require a valid Geometry to be set as the geometry parameter and a valid Material to be set as the material parameter.

Geometries in ANARI are objects that describe the spatial representation of a surface. To create a new geometry object of given subtype subtype use

All geometries support the following attribute setting parameters.

Values in primitive.id must be at most device limit geometryMaxIndex. If geometries have additional per-vertex parameters specifying the same attribute, then the geometry specific vertex.* parameters take precedence.

ANARI sampler objects map attribute data into other object inputs such materials. To create a new sampler use

Materials describe how light interacts with surfaces to give objects their appearance. Materials are created with

Most material parameters can be set to a constant, ANARISampler or string value. Unless otherwise noted, the string selects the surface attribute that will be used to source the parameter during rendering.

Volumes in ANARI represent volumetric objects (complementing surfaces), encapsulating spatial data as well as appearance information. To create a new volume object of given subtype subtype use

ANARI spatial field objects define collections of data values spread throughout a local coordinate system in order to be sampled in space. Spatial fields are created with

Extensions may need to introduce custom object types. To create such an object use

Consult the extension documentation for supported type and subtype values.

The ANARI Advisory Panel members provided important real-world usage information and advice that helped guide design decisions.

Administrative support to the Working Group for ANARI 1.0 was provided by Khronos staff.

Technical support was provided by James Riordon, webmaster of Khronos.org.