Data Structures | Macros | Typedefs | Functions
Volume Plugin API

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;
Node methods.
Definition: ai_node_entry.h:78
Definition: ai_volume.h:184

Volume node methods exporter.

#define volume_create
Value:
static bool VolumeCreate(const AtNode* node, \
AtVolumeData* data)
This represents a node in Arnold.
Volume data, as returned by AtVolumeCreate.
Definition: ai_volume.h:49
#define volume_update
Value:
static bool VolumeUpdate(const AtNode* node, \
AtVolumeData* data)
This represents a node in Arnold.
Volume data, as returned by AtVolumeCreate.
Definition: ai_volume.h:49
#define volume_cleanup
Value:
static bool VolumeCleanup(const AtNode* node, \
AtVolumeData* data)
This represents a node in Arnold.
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)
3D point (single precision)
Definition: ai_vector.h:29
Volume data, as returned by AtVolumeCreate.
Definition: ai_volume.h:49
#define volume_sample
Value:
static bool VolumeSample(const AtVolumeData* data, \
const AtString channel, \
const AtShaderGlobals* sg, \
int interp, \
AtParamValue *value, \
uint8_t *type)
Arnold String allows for fast string comparisons.
Definition: ai_string.h:45
Shader globals data structure.
Definition: ai_shaderglobals.h:41
Actual parameter value for each supported type.
Definition: ai_params.h:102
Volume data, as returned by AtVolumeCreate.
Definition: ai_volume.h:49
#define volume_gradient
Value:
static bool VolumeGradient(const AtVolumeData* data, \
const AtString channel, \
const AtShaderGlobals* sg, \
int interp, \
AtVector* gradient)
Arnold String allows for fast string comparisons.
Definition: ai_string.h:45
3D point (single precision)
Definition: ai_vector.h:29
Shader globals data structure.
Definition: ai_shaderglobals.h:41
Volume data, as returned by AtVolumeCreate.
Definition: ai_volume.h:49

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
nodeOwner node where the volume was requested
[out]dataVolume 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
nodeOwner node where the volume was requested
[out]dataVolume 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
dataVolume 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
dataVolume data returned from AtVolumeCreate
channelData channel name from the volume or implicit surface
sgShader globals for the sampling context
interpVolume interpolation quality, one of AI_VOLUME_INTERP_*
[out]valueResulting sampled value, matching the type output in out_type
[out]typeResulting 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
dataVolume data returned from AtVolumePluginCreateVolume
channelData channel name from the volume or implicit surface
sgShader globals for the sampling context
interpVolume interpolation quality, one of AI_VOLUME_INTERP_*
[out]gradientResulting 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
dataVolume data returned from AtVolumeCreate
infoOpaque ptr to intersection info passed to AiVolumeAddIntersection
tidCurrent thread ID, use for thread-local access as needed
timeTime at which the volume is being sampled (for motion blur)
originRay origin in object space
directionRay direction, normalized and in object space
t0Start of the master ray interval in which to check for extents
t1End 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
infoPrivate intersection information
t0Beginning of ray extent
t1End 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
infoPrivate intersection information
t0Beginning of ray extent
t1End of ray extent
prim_idPrimitive 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
filenamePath 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
filenamePath to volume file.
channelsString array of channel names.
Returns
Bounding box.

© 2009-2018 Solid Angle SL · all rights reserved · www.solidangle.com