This API is used to interact with custom volumes, implicit surfaces and formats at render time. More...

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

struct	AtVolumeNodeMethods

Macros
#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

Typedefs
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...

Functions
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...

Volume interpolation quality
#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

Detailed Description

This API is used to interact 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

#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.

#define volume_create

Value:

static bool VolumeCreate(const AtNode* node, \

AtVolumeData* data)

AtNode

This represents a node in Arnold.

AtVolumeData

Volume data, as returned by AtVolumeCreate.

Definition: ai_volume.h:49

#define volume_update

Value:

static bool VolumeUpdate(const AtNode* node, \

AtVolumeData* data)

AtNode

This represents a node in Arnold.

AtVolumeData

Volume data, as returned by AtVolumeCreate.

Definition: ai_volume.h:49

#define volume_cleanup

Value:

static bool VolumeCleanup(const AtNode* node, \

AtVolumeData* data)

AtNode

This represents a node in Arnold.

AtVolumeData

Volume data, as returned by AtVolumeCreate.

Definition: ai_volume.h:49

#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)

#define volume_sample

Value:

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

#define volume_gradient

Value:

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

Typedef Documentation

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

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

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

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

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

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 master ray interval in which to check for extents
t1	End of the master ray interval in which to check for extents

Function Documentation

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

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.

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.

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.

Data Structures

Macros

Typedefs

Functions

Volume interpolation quality

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation