Data Structures | Macros
Output Driver Nodes

Construction and manipulation of driver nodes. More...

Data Structures

struct  AtDriverNodeMethods
 Driver Node methods structure. More...
 

Macros

#define AI_DRIVER_NODE_EXPORT_METHODS(tag)
 Output Driver node methods exporter. More...
 

Quantization and Dithering

AI_API AI_CONST uint8_t AiQuantize8bit (int x, int y, int i, float value, bool dither)
 Quantize a floating point number down to an 8-bit integer. More...
 
AI_API AI_CONST uint16_t AiQuantize16bit (int x, int y, int i, float value, bool dither)
 Quantize a floating point number down to a 16-bit integer. More...
 

Node Method Declarations

#define driver_supports_pixel_type   static bool DriverSupportsPixelType(const AtNode* node, uint8_t pixel_type)
 Driver's driver_supports_pixel_type declaration. More...
 
#define driver_extension   static const char** DriverExtension()
 Driver's driver_extension method declaration. More...
 
#define driver_open   static void DriverOpen(AtNode* node, struct AtOutputIterator* iterator, AtBBox2 display_window, AtBBox2 data_window, int bucket_size)
 Driver's driver_open method declaration. More...
 
#define driver_needs_bucket   static bool DriverNeedsBucket(AtNode* node, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y, uint16_t tid)
 Driver's driver_needs_bucket method declaration. More...
 
#define driver_prepare_bucket   static void DriverPrepareBucket(AtNode* node, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y, uint16_t tid)
 Driver's driver_prepare_bucket method declaration. More...
 
#define driver_process_bucket   static void DriverProcessBucket(AtNode* node, struct AtOutputIterator* iterator, struct AtAOVSampleIterator* sample_iterator, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y, uint16_t tid)
 Driver's driver_process_bucket method declaration. More...
 
#define driver_write_bucket   static void DriverWriteBucket(AtNode* node, struct AtOutputIterator* iterator, struct AtAOVSampleIterator* sample_iterator, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y)
 Driver's driver_write_bucket method declaration. More...
 
#define driver_close   static void DriverClose(AtNode* node, struct AtOutputIterator* iterator)
 Driver's driver_close method declaration. More...
 

API for Driver Writers

AI_API void AiDriverInitialize (AtNode *node, bool supports_multiple_outputs)
 Allocates and initializes the driver structure. More...
 
AI_API void AiRawDriverInitialize (AtNode *node, const char **required_aovs, bool requires_depth)
 Allocates and initializes the driver structure. More...
 
AI_API void AiDriverGetMatrices (AtMatrix &world_to_camera, AtMatrix &world_to_screen)
 Get Renderman compliant matrices from the active camera for use in file headers. More...
 
AI_API const char ** AiDriverExtension (const AtNodeEntry *node_entry)
 Invokes a driver's driver_extension method which returns a NULL-terminated array of filename extensions supported by this driver (note: uses the node_entry as this is a "static" method)
 
AI_API bool AiOutputIteratorGetNext (struct AtOutputIterator *iter, const char **output_name, int *pixel_type, const void **bucket_data)
 Get information about the next output connected to a driver. More...
 
AI_API void AiOutputIteratorReset (struct AtOutputIterator *iter)
 Reset an output iterator. More...
 
AI_API const AtNodeEntryAiFindDriverType (const char *extension)
 Get correct driver node type from an extension. More...
 

Detailed Description

Construction and manipulation of driver nodes.

Arnold supports pluggable output-file writers called "drivers". This output driver mechanism provides a pluggable architecture for writing output image files using Arnold's built-in AOV pipeline. It is also possible to write to arbitrary devices, such as a window display.

AOVs (Arbitrary Output Values) are organized into "layers", with each layer having a particular type (such as FLOAT or RGBA).

Drivers receive AOVs one bucket at a time which is perfectly suited to image-formats that are tiled. An iterator allows the driver to iterate through all the AOV layers contained in the bucket.

Macro Definition Documentation

#define AI_DRIVER_NODE_EXPORT_METHODS (   tag)
Value:
static AtDriverNodeMethods ai_driver_mtds = { \
DriverSupportsPixelType, \
DriverExtension, \
DriverOpen, \
DriverNeedsBucket, \
DriverPrepareBucket, \
DriverProcessBucket, \
DriverWriteBucket, \
DriverClose, \
}; \
static AtNodeMethods ai_node_mtds = { \
&ai_common_mtds, \
&ai_driver_mtds \
}; \
const AtNodeMethods *tag = &ai_node_mtds;
#define driver_process_bucket
Driver's driver_process_bucket method declaration.
Definition: ai_drivers.h:177
#define driver_needs_bucket
Driver's driver_needs_bucket method declaration.
Definition: ai_drivers.h:137
Node methods.
Definition: ai_node_entry.h:83
#define driver_prepare_bucket
Driver's driver_prepare_bucket method declaration.
Definition: ai_drivers.h:156
#define driver_open
Driver's driver_open method declaration.
Definition: ai_drivers.h:119
Driver Node methods structure.
Definition: ai_drivers.h:45
#define driver_supports_pixel_type
Driver's driver_supports_pixel_type declaration.
Definition: ai_drivers.h:95
#define driver_write_bucket
Driver's driver_write_bucket method declaration.
Definition: ai_drivers.h:196
#define driver_extension
Driver's driver_extension method declaration.
Definition: ai_drivers.h:104
#define driver_close
Driver's driver_close method declaration.
Definition: ai_drivers.h:207

Output Driver node methods exporter.

#define driver_supports_pixel_type   static bool DriverSupportsPixelType(const AtNode* node, uint8_t pixel_type)

Driver's driver_supports_pixel_type declaration.

Can the driver handle buckets of pixels of the specified type? This function is not called for raw mode drivers.

Returns
true if the driver can write pixels of the given type
#define driver_extension   static const char** DriverExtension()

Driver's driver_extension method declaration.

Returns
a NULL-terminated array of filename extensions which this driver is capable of writing. For example, a 'jpeg' driver might return the following array: { "jpeg", "jpg", NULL }
#define driver_open   static void DriverOpen(AtNode* node, struct AtOutputIterator* iterator, AtBBox2 display_window, AtBBox2 data_window, int bucket_size)

Driver's driver_open method declaration.

This function is called before rendering starts and can make any preparations the driver needs, like opening a file or allocating memory. The list of connected outputs is passed in using an output iterator.

Parameters
nodepointer to the driver node itself
iteratoroutput iterator for outputs connected to this driver
display_windowthis is a 2D bounding box for the actual resolution
data_windowthis is the actual region of pixels that will be rendered
bucket_sizemaximum width in pixels of a bucket
#define driver_needs_bucket   static bool DriverNeedsBucket(AtNode* node, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y, uint16_t tid)

Driver's driver_needs_bucket method declaration.

This function is called to determine if a bucket will be rendered. It can be used to continue work on partial images without re-rendering already present buckets.

Parameters
nodepointer to the driver node itself
bucket_xox coordinate of the bucket (upper-left)
bucket_yoy coordinate of the bucket (upper-left)
bucket_size_xwidth of the bucket in pixels
bucket_size_yheight of the bucket in pixels
tidthread ID that will render this bucket
Returns
true if the bucket needs to be rendered, false if the bucket can be skipped
#define driver_prepare_bucket   static void DriverPrepareBucket(AtNode* node, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y, uint16_t tid)

Driver's driver_prepare_bucket method declaration.

This function is called before a bucket is rendered. It can be used to display bucket corners for interactive rendering drivers to show which buckets are being processed, for example. The renderer locks around this function so the contained code is not required to be thread safe. The bucket size may be smaller than what was given to driver_open because buckets are clamped to the edge of the render region.

Parameters
nodepointer to the driver node itself
bucket_xox coordinate of the bucket (upper-left)
bucket_yoy coordinate of the bucket (upper-left)
bucket_size_xwidth of the bucket in pixels
bucket_size_yheight of the bucket in pixels
tidthread ID that will render this bucket
#define driver_process_bucket   static void DriverProcessBucket(AtNode* node, struct AtOutputIterator* iterator, struct AtAOVSampleIterator* sample_iterator, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y, uint16_t tid)

Driver's driver_process_bucket method declaration.

This function is called after a bucket has been rendered, but before it is written out. It provides the rendered pixels of each output to the driver, or the raw AOV samples if this is a raw driver. The renderer does not lock around this function, to allow for lengthy bucket preprocessing to happen in parallel. The contained code should not require any thread synchornization. The bucket size may be smaller than what was given to driver_open because buckets are clamped to the edge of the render region.

Parameters
nodepointer to the driver node itself
iteratoroutput iterator (loops over connected outputs for regular drivers)
sample_iteratorraw AOV sample iterator (loops over connected AOVs for raw drivers)
bucket_xox coordinate of the bucket (upper-left)
bucket_yoy coordinate of the bucket (upper-left)
bucket_size_xwidth of the bucket in pixels
bucket_size_yheight of the bucket in pixels
tidthread ID that rendered this bucket
#define driver_write_bucket   static void DriverWriteBucket(AtNode* node, struct AtOutputIterator* iterator, struct AtAOVSampleIterator* sample_iterator, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y)

Driver's driver_write_bucket method declaration.

This function is called after a bucket has been rendered. It provides the rendered pixels of each output to the driver, or the raw AOV samples if this is a raw driver. The renderer locks around this function so the contained code is not required to be thread safe. The bucket size may be smaller than what was given to driver_open because buckets are clamped to the edge of the render region.

Parameters
nodepointer to the driver node itself
iteratoroutput iterator (loops over connected outputs for regular drivers)
sample_iteratorraw AOV sample iterator (loops over connected AOVs for raw drivers)
bucket_xox coordinate of the bucket (upper-left)
bucket_yoy coordinate of the bucket (upper-left)
bucket_size_xwidth of the bucket in pixels
bucket_size_yheight of the bucket in pixels
#define driver_close   static void DriverClose(AtNode* node, struct AtOutputIterator* iterator)

Driver's driver_close method declaration.

This function is called after the image has finished rendering. It is responsible for any final tasks such as flushing or closing open files.

Parameters
nodepointer to the driver node itself
iteratoroutput iterator (loops over connected outputs for regular drivers)

Function Documentation

AI_API AI_CONST uint8_t AiQuantize8bit ( int  x,
int  y,
int  i,
float  value,
bool  dither 
)

Quantize a floating point number down to an 8-bit integer.

This function is typically used in an output driver to prepare pixel values before sending them to the output device. For example, we may want to send the continuous floating point image to a standard display with a limited color resolution of 8 bits per component.

Pixel quantization is a lossy process that can introduce distracting banding artifacts in the rendered image. This function optionally uses random dithering, which breaks the banding up into almost imperceptible noise. The input parameters x,y are used to lock the dither noise to the location of each pixel to prevent it from flickering in animation.

Usage example:

1 AtUInt8 r = AiQuantize8bit(x, y, 0, color.r, 1.0f);
2 AtUInt8 g = AiQuantize8bit(x, y, 1, color.g, 1.0f);
3 AtUInt8 b = AiQuantize8bit(x, y, 2, color.b, 1.0f);
Parameters
xhorizontal coordinate of the pixel to be quantized
yvertical coordinate of the pixel to be quantized
iinstance number in 0..n-1, when part of a sequence of n calls
valueinput floating point value to be quantized, in the [0,1] range
ditheruse random dithering
Returns
quantized value, in 0..255
AI_API AI_CONST uint16_t AiQuantize16bit ( int  x,
int  y,
int  i,
float  value,
bool  dither 
)

Quantize a floating point number down to a 16-bit integer.

Parameters
xhorizontal coordinate of the pixel to be quantized
yvertical coordinate of the pixel to be quantized
iinstance number in 0..n-1, when part of a sequence of n calls
valuefloating point value, in the [0,1] range
ditheruse random dithering
Returns
quantized value, in 0..65535
See also
AiQuantize8bit
AI_API void AiDriverInitialize ( AtNode node,
bool  supports_multiple_outputs 
)

Allocates and initializes the driver structure.

This function creates an internal DriverNode structure.

Parameters
nodepointer to the driver node
supports_multiple_outputsdoes this driver support more than one output routed to it?
AI_API void AiRawDriverInitialize ( AtNode node,
const char **  required_aovs,
bool  requires_depth 
)

Allocates and initializes the driver structure.

This function works just like AiDriverInitialize() but should only be used for raw drivers.

Parameters
nodepointer to the driver node
required_aovsNULL-terminated array of AOV descriptors ("TYPE name") to route to this driver
requires_depthshould input AOVs be tracked with depth
See also
AiDriverInitialize
AI_API void AiDriverGetMatrices ( AtMatrix world_to_camera,
AtMatrix world_to_screen 
)

Get Renderman compliant matrices from the active camera for use in file headers.

This fetches the camera and screen matrices from the currently active camera so they can be placed in an output file's header. Note that unlike the camera API functions, the world to camera transform looks down +Z for compatibility with most file formats (TIFF,OpenEXR,dshd,...).

Parameters
[out]world_to_cameraworld to camera transformation matrix (looking down +Z)
[out]world_to_screenworld to screen transformation matrix
AI_API bool AiOutputIteratorGetNext ( AtOutputIterator *  iter,
const char **  output_name,
int *  pixel_type,
const void **  bucket_data 
)

Get information about the next output connected to a driver.

This method is meant to be called in a loop, though drivers that are designed to only accept a single output may call it just once. Each parameter is optional, and will only be written to when not NULL. The bucket_data parameter can only be obtained when writing a bucket. If this method returns false, the return values should not be used.

If any outputs connected to the driver have a denoise_optix_filter the iterator will receive outputs in two successive calls of driver_process_bucket/driver_write_bucket. The first call the iterator will point to all outputs that do not use the denoise_optix_filter with the second successive call pointing to all outputs with the denoise_optix_filter.

Parameters
iterpointer to the iterator
[out]output_namethe name of the AOV corresponding to this output
[out]pixel_typethe type of the pixel data (AI_TYPE_INT, AI_TYPE_RGB, etc)
[out]bucket_datapointer to the start of the bucket data, pixel values will be stored in row major order
Returns
true if a valid output was present, false if the end of the output list was reached
AI_API void AiOutputIteratorReset ( AtOutputIterator *  iter)

Reset an output iterator.

This method resets an output iterator so that the user may iterate over the outputs again.

Parameters
iterpointer to the iterator
AI_API const AtNodeEntry* AiFindDriverType ( const char *  extension)

Get correct driver node type from an extension.

Parameters
extensiona string containing the file extension, e.g. "tiff"
Returns
the AtNodeEntry corresponding to extension

© 2021 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com