Volume Plugin API

Interaction with custom volumes, implicit surfaces and formats at render time. More...

Data Structures
struct	AtVolumeData
	Volume data, as returned by AtVolumeCreate. More...
struct	AtVolumeNodeMethods

Variables
void *	AtVolumeData::private_info
	Volume plugin private data, used how the plugin likes.
AtBBox	AtVolumeData::bbox
	Bounding box for this volume, plugin is responsible for also including volume_padding from the node.
float	AtVolumeData::auto_step_size
	Recommended step size for ray marching through this data.
AtVolumeCreate	AtVolumeNodeMethods::Create
	This method is called to load/create a volume.
AtVolumeUpdate	AtVolumeNodeMethods::Update
	This method is called to update a volume before render passes or on scene changes.
AtVolumeCleanup	AtVolumeNodeMethods::Cleanup
	This method is called to clean up a volume when it's no longer needed.
AtVolumeRayExtents	AtVolumeNodeMethods::RayExtents
	This method is called to get all tightly-bounded extents along a ray where the volume exists.
AtVolumeSample	AtVolumeNodeMethods::Sample
	This method is called to sample a volume's named channel using a given point and interpolation.
AtVolumeGradient	AtVolumeNodeMethods::Gradient
	This method is called to sample the gradient of a volume's named channel using a given point and interpolation.

Volume interpolation quality
typedef bool(*	AtVolumeCreate) (const AtNode *node, AtVolumeData *data)
	Volume plugin volume creation. More...
typedef bool(*	AtVolumeUpdate) (const AtNode *node, AtVolumeData *data)
	Volume plugin volume update. More...
typedef bool(*	AtVolumeCleanup) (const AtNode *node, AtVolumeData *data)
	Volume plugin volume cleanup method. More...
typedef bool(*	AtVolumeSample) (const AtVolumeData *data, const AtString channel, const AtShaderGlobals *sg, int interp, AtParamValue *value, uint8_t *type)
	Volume plugin sample method. More...
typedef bool(*	AtVolumeGradient) (const AtVolumeData *data, const AtString channel, const AtShaderGlobals *sg, int interp, AtVector *gradient)
	Volume plugin gradient method. More...
typedef void(*	AtVolumeRayExtents) (const AtVolumeData *data, const AtVolumeIntersectionInfo *info, uint16_t tid, float time, const AtVector *origin, const AtVector *direction, float t0, float t1)
	Volume plugin method for submitting extents along a ray where there is data. More...
AI_API void	AiVolumeAddIntersection (const AtVolumeIntersectionInfo *info, float t0, float t1)
	Submit a ray interval/extent for volume integration. More...
AI_API void	AiVolumeMergeIntersection (const AtVolumeIntersectionInfo *info, float t0, float t1, uint32_t prim_id)
	Submit a ray interval/extent for volume integration. More...
AI_API AtArray *	AiVolumeFileGetChannels (const char *filename)
	Get list of channel names in a volume file. More...
AI_API AtBBox	AiVolumeFileGetBBox (const char *filename, const AtArray *channels)
	Get bounding box for specified channels in a volume file. More...
#define	AI_VOLUME_INTERP_CLOSEST   0
	closest data from the volume
#define	AI_VOLUME_INTERP_TRILINEAR   1
	trilinearly sampled volume
#define	AI_VOLUME_INTERP_TRICUBIC   2
	tricubicly sampled volume
#define	AI_VOLUME_NODE_EXPORT_METHODS(tag)
	Volume node methods exporter. More...
#define	volume_create
#define	volume_update
#define	volume_cleanup
#define	volume_ray_extents
#define	volume_sample
#define	volume_gradient

Detailed Description

Interaction with custom volumes, implicit surfaces and formats at render time.

This is accomplished by providing the renderer some callback functions which are called as needed (when the object is hit by a ray). The plugins are intended to provide tight ray intervals surrounding actual volumetric or implicit surface data, as well as sampling methods for sampling data channels from the volume or implicit surface.

Note that the plugins have a thread-locked part: init and cleanup, while the rest of the callbacks may be called concurrently from multiple threads.

Macro Definition Documentation

AI_VOLUME_NODE_EXPORT_METHODS

#define AI_VOLUME_NODE_EXPORT_METHODS

(

tag

)

Value:

AI_INSTANCE_COMMON_SHAPE_METHODS             \
volume_create;                               \
volume_update;                               \
volume_cleanup;                              \
volume_ray_extents;                          \
volume_sample;                               \
volume_gradient;                             \
static AtVolumeNodeMethods ai_vol_mtds = {   \
   VolumeCreate,                             \
   VolumeUpdate,                             \
   VolumeCleanup,                            \
   VolumeRayExtents,                         \
   VolumeSample,                             \
   VolumeGradient                            \
};                                           \
static AtNodeMethods ai_node_mtds = {        \
   &ai_common_mtds,                          \
   &ai_vol_mtds                              \
};                                           \
const AtNodeMethods* tag = &ai_node_mtds;

Volume node methods exporter.

volume_create

#define volume_create

Value:

static bool VolumeCreate(const AtNode* node,   \
                         AtVolumeData* data)

volume_update

#define volume_update

Value:

static bool VolumeUpdate(const AtNode* node,   \
                         AtVolumeData* data)

volume_cleanup

#define volume_cleanup

Value:

static bool VolumeCleanup(const AtNode* node,  \
                          AtVolumeData* data)

volume_ray_extents

#define volume_ray_extents

Value:

static void VolumeRayExtents(const AtVolumeData* data,             \
                             const AtVolumeIntersectionInfo* info, \
                             uint16_t tid,                         \
                             float time,                           \
                             const AtVector* origin,               \
                             const AtVector* direction,            \
                             float t0,                             \
                             float t1)

volume_sample

#define volume_sample

Value:

static bool VolumeSample(const AtVolumeData* data,   \
                         const AtString channel,     \
                         const AtShaderGlobals* sg,  \
                         int interp,                 \
                         AtParamValue *value,        \
                         uint8_t *type)

volume_gradient

#define volume_gradient

Value:

static bool VolumeGradient(const AtVolumeData* data,   \
                           const AtString channel,     \
                           const AtShaderGlobals* sg,  \
                           int interp,                 \
                           AtVector* gradient)

Typedef Documentation

AtVolumeCreate

typedef bool(* AtVolumeCreate) (const AtNode *node, AtVolumeData *data)

Volume plugin volume creation.

This method will be called for each volume node before usage.

Parameters

	node	Owner node where the volume was requested
[out]	data	Volume data with all fields to be set by the callback

Returns

true if volume creation succeeded

AtVolumeUpdate

typedef bool(* AtVolumeUpdate) (const AtNode *node, AtVolumeData *data)

Volume plugin volume update.

This method will be called for each volume node before each render pass or scene change, so that the volume can be update accordingly. If not provided, the volume will be destroyed and recreated.

Parameters

	node	Owner node where the volume was requested
[out]	data	Volume data with all fields to be set by the callback

Returns

true if volume data was modified

AtVolumeCleanup

typedef bool(* AtVolumeCleanup) (const AtNode *node, AtVolumeData *data)

Volume plugin volume cleanup method.

This method will be called once for each volume that was created by a call to AtVolumeCreate to allow a chance to clean up any private data.

Parameters

data	Volume data returned from AtVolumeCreate

Returns

true upon success

AtVolumeSample

typedef bool(* AtVolumeSample) (const AtVolumeData *data, const AtString channel, const AtShaderGlobals *sg, int interp, AtParamValue *value, uint8_t *type)

Volume plugin sample method.

This method will be called concurrently to sample data from a given channel with the specified interpolation. Implementors should use sg->Po as the sampling position.

Parameters

	data	Volume data returned from AtVolumeCreate
	channel	Data channel name from the volume or implicit surface
	sg	Shader globals for the sampling context
	interp	Volume interpolation quality, one of AI_VOLUME_INTERP_*
[out]	value	Resulting sampled value, matching the type output in out_type
[out]	type	Resulting value type, one of AI_TYPE_FLOAT, AI_TYPE_VECTOR2, AI_TYPE_RGB, AI_TYPE_RGBA, or AI_TYPE_VECTOR

Returns

true upon success

AtVolumeGradient

typedef bool(* AtVolumeGradient) (const AtVolumeData *data, const AtString channel, const AtShaderGlobals *sg, int interp, AtVector *gradient)

Volume plugin gradient method.

This method will be called concurrently to sample the gradient from a given channel with the specified interpolation. Implementors should use sg->Po as the sampling position. Note that this is generally only used for implicit surfaces, so if the plugin is only outputting density volume data this method can just return false and do no other work. Also note that this will also only make sense for scalar channels, such as signed distance fields.

Parameters

	data	Volume data returned from AtVolumePluginCreateVolume
	channel	Data channel name from the volume or implicit surface
	sg	Shader globals for the sampling context
	interp	Volume interpolation quality, one of AI_VOLUME_INTERP_*
[out]	gradient	Resulting sampled gradient

Returns

true upon success

AtVolumeRayExtents

typedef void(* AtVolumeRayExtents) (const AtVolumeData *data, const AtVolumeIntersectionInfo *info, uint16_t tid, float time, const AtVector *origin, const AtVector *direction, float t0, float t1)

Volume plugin method for submitting extents along a ray where there is data.

For each ray interval where there is volumetric data to be integrated this callback should call AiVolumeAddIntersection to submit the extent along the ray. Any extra distance from the node's volume_padding parameter must be accounted for and added to each interval. Note that for implicits, the ray extents should encompass the interval where there is data such as signed-distance field values, like in narrow-band level sets. The implicit solver will then find the true ray intersection with the surface.

Warning

Any ray extents submitted that overlap will have the shaders run more than once for each extent. If shaders should only be run once, then those extents should be merged and submitted just once to AiVolumeAddIntersection instead.

Parameters

data	Volume data returned from AtVolumeCreate
info	Opaque ptr to intersection info passed to AiVolumeAddIntersection
tid	Current thread ID, use for thread-local access as needed
time	Time at which the volume is being sampled (for motion blur)
origin	Ray origin in object space
direction	Ray direction, normalized and in object space
t0	Start of the source ray interval in which to check for extents
t1	End of the source ray interval in which to check for extents

Function Documentation

AiVolumeAddIntersection()

AI_API void AiVolumeAddIntersection	(	const AtVolumeIntersectionInfo *	info,
		float	t0,
		float	t1
	)

Submit a ray interval/extent for volume integration.

This is only useable from AtVolumeRayExtents, where a valid pointer to AtVolumeIntersectionInfo is provided. This call may be made as many times as necessary to tightly describe where the volume data exists along the ray, but note that if overlapping extents are submitted they will be independently integrated (and shaded more than once in the overlapping areas). If you need them integrated just once, you should use AiVolumeMergeIntersection instead.

Note that this same function is used to find implicit surface intersections, when the plugin provides such surfaces instead of heterogeneous volumes.

Parameters

info	Private intersection information
t0	Beginning of ray extent
t1	End of ray extent

AiVolumeMergeIntersection()

AI_API void AiVolumeMergeIntersection	(	const AtVolumeIntersectionInfo *	info,
		float	t0,
		float	t1,
		uint32_t	prim_id
	)

Submit a ray interval/extent for volume integration.

This is only useable from AtVolumeRayExtents, where a valid pointer to AtVolumeIntersectionInfo is provided. This call may be made as many times as necessary to tightly describe where the volume data exists along the ray, but note that if overlapping extents are submitted they will be merged and integrated just once over any overlapping ranges that match in primitive ID and step size. If you want overlapping ranges to be integrated and shaded separately, you should use AiVolumeAddIntersection instead.

Note that this same function is used to find implicit surface intersections, when the plugin provides such surfaces instead of heterogeneous volumes.

Parameters

info	Private intersection information
t0	Beginning of ray extent
t1	End of ray extent
prim_id	Primitive ID or index for the part of the object, where separate parts will not be merged together. If in doubt, use zero.

AiVolumeFileGetChannels()

AI_API AtArray * AiVolumeFileGetChannels

(

const char *

filename

)

Get list of channel names in a volume file.

Currently supports the OpenVDB file format.

Parameters

filename

Path to volume file.

Returns

String array of channel names, must be freed with AiArrayDestroy.

AiVolumeFileGetBBox()

AI_API AtBBox AiVolumeFileGetBBox	(	const char *	filename,
		const AtArray *	channels
	)

Get bounding box for specified channels in a volume file.

Currently supports the OpenVDB file format.

Parameters

filename	Path to volume file.
channels	String array of channel names.

Returns

Bounding box.