From 884512745787b7f0fcb19784ed3d5a9f12a85cb0 Mon Sep 17 00:00:00 2001 From: Jefferson Amstutz Date: Mon, 25 Nov 2024 11:00:53 -0600 Subject: [PATCH] update readme docs --- README.md | 17 +++++++++++------ src/helium/README.md | 41 ++++++++++++++++++++++++++++++----------- 2 files changed, 41 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 2c1eff21..25e3a363 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ This repository contains the source for the ANARI API SDK. This includes: - [Front-end library + implementation guide](src/anari) - [Device implementation utilties for implementations](src/helium) -- [Example device implementation](src/helide) (not intended for production use) +- [Example device implementation](src/devices/helide) (not intended for production use) - [Example applications](examples/) - [Interactive sample viewer](examples/viewer) - [Render tests](tests/render) @@ -71,14 +71,19 @@ CMake. This can be invoked from your build directory with (on any platform): The 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` : main library target to link with `libanari` -- `anari::helium` : (static) library target containing base device implementation abstractions +- `anari::anari` : dynamically link the main ANARI API library target +- `anari::anari_static` : statically link the main ANARI API library target +- `anari::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](examples/simple). -The follwoing additional helper library components can be requested by listing +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 target `anari::anari_viewer` for building small viewer apps @@ -124,7 +129,7 @@ the viewer to select/override which library is loaded at runtime. ### SDK provided example implementation -An example device implementation [helide](src/helide) is provided as a +An example device implementation [helide](src/devices/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, @@ -133,7 +138,7 @@ the SDK. (see below) ### Using the debug device layer -The ANARI-SDK ships with a [debug layer](src/debug_device) implemented as an +The ANARI-SDK ships with a [debug layer](src/devices/debug) 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 diff --git a/src/helium/README.md b/src/helium/README.md index 15406702..67cc2a4f 100644 --- a/src/helium/README.md +++ b/src/helium/README.md @@ -22,10 +22,10 @@ choices) ought to instead directly implement the ANARI API interface. ### Example implementation (Helide) -The [helide device](../helide) is a minimal implementation which combines -helium and Embree to do very basic CPU rendering with ray tracing. Potential -helium library users can use helide as a guide for how helium abstractions are -intended to be used. +The [helide device](../devices/helide) is a minimal implementation which +combines helium and Embree to do very basic CPU rendering with ray tracing. +Potential helium library users can use helide as a guide for how helium +abstractions are intended to be used. ### Where did the name "Helium" come from? @@ -48,6 +48,10 @@ target_link_libraries(anari_device_myDevice PRIVATE anari::helium) # ... ``` +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 sections will outline various design choices relevent to implementors using helium. @@ -65,12 +69,12 @@ object commits need to occur or can be skipped. The [helium::BaseDevice](BaseDevice.h) class implements a subset of the main API class that the C API forward to ([anari::DeviceImpl](../anari/include/anari/backend/DeviceImpl.h)). -Implementations are mostly responsible for implementing all the `new*()` methods +Subclasses are mostly responsible for implementing all the `new*()` methods of `anari::DeviceImpl` as helium doesn't know how to create concrete objects. -Some implementations may desire to still "intercept" all base implemented API -calls, which can easily be done by overriding the method found in -`helium::BaseDevice` and then call it when appropriately. This may look like: +Some subclasses may desire to still "intercept" all base implemented API calls, +which can easily be done by overriding the method found in `helium::BaseDevice` +and then call it when appropriately. This may look like: ```cpp void MyDevice::setParameter( @@ -99,8 +103,9 @@ All parameter handling is done through [helium::ParameterizedObject](utility/ParameterizedObject.h). Helium uses a 'pull' based model for handling parameters -- all parameter values are generically stored in the object and are expected to be read on -`helium::BaseObject::commit()`. See comments on `ParameterizedObject` methods -for a further explanation. +`helium::BaseObject::commit()`. See comments on +[ParameterizedObject](utility/ParameterizedObject.h) methods for a further +explanation. Object commits are deferred until the device chooses to flush the [DefferedCommitBuffer](utiltiy/DeferredCommitBuffer.h) that lives in the @@ -111,7 +116,7 @@ values are queried. Finally, objects can use `helium::BaseObject::reportMessage()` to generically report status messages through the application provided callbacks (setup and -managed by `helium::BaseDevice`). +managed for you in `helium::BaseDevice`). ### BaseArray + BaseFrame @@ -137,6 +142,12 @@ accordingly based on what the implementation may require. Note that using exclusively using it will cleanly divide application ref count changes vs. internal ref counts. +Additionally, there are basic (host-only) array implementations provided that +can be used out-of-the-box for many implementations. Their common functionality +is found in [Array](array/Array.h), with complete interfaces in +[Array1D](array/Array1D.h), [Array2D](array/Array2D.h), +[Array3D](array/Array3D.h), and [ObjectArray](array/ObjectArray.h) respectively. + ### BaseGlobalDeviceState [helium::BaseGlobalDeviceState](BaseGlobalDeviceState.h) is a struct containing @@ -149,3 +160,11 @@ Implementations must construct the protected `BaseDevice::m_state` variable so that status callback output can function properly. Devices which extend `BaseGlobalDeviceState` instead should initialze `m_state` with their own derived type which the downstream implementation can safely cast to. + +### Math + shading utility functions + +Helium uses the [ANARI provided math +types](../anari/include/anari/anari_cpp/ext/linalg.h) extensively, as well as +providing various common functions that can be useful for implementing ANARI. +All such functionality is found in the single [helium_math.h](helium_math.h) +header.