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

Variables
bool(*	AtDriverNodeMethods::DriverSupportsPixelType )(const AtNode *, uint8_t)

const char *(	AtDriverNodeMethods::DriverExtension )()

void(*	AtDriverNodeMethods::DriverOpen )(AtNode , struct AtOutputIterator , AtBBox2, AtBBox2, int)

bool(*	AtDriverNodeMethods::DriverNeedsBucket )(AtNode *, int, int, int, int, uint16_t)

void(*	AtDriverNodeMethods::DriverPrepareBucket )(AtNode *, int, int, int, int, uint16_t)

void(*	AtDriverNodeMethods::DriverProcessBucket )(AtNode , struct AtOutputIterator , struct AtAOVSampleIterator *, int, int, int, int, uint16_t)

void(*	AtDriverNodeMethods::DriverWriteBucket )(AtNode , struct AtOutputIterator , struct AtAOVSampleIterator *, int, int, int, int)

void(*	AtDriverNodeMethods::DriverClose )(AtNode , struct AtOutputIterator )

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

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, AtString 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 AtNode *	AiOutputIteratorGetFilter (struct AtOutputIterator *iter)
	Get the filter associated with the current output. More...

AI_API bool	AiOutputIteratorIsHalf (struct AtOutputIterator *iter)
	Is the current output is half format. More...

AI_API AtString	AiOutputIteratorGetLayerName (struct AtOutputIterator *iter)
	Get the name of the targer layer of the current output. More...

AI_API AtNode *	AiOutputIteratorGetCamera (struct AtOutputIterator *iter)
	Get the camera associated with the current output. More...

AI_API const AtNodeEntry *	AiFindDriverType (const char *extension)
	Get correct driver node type from an extension. 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...

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

◆ AI_DRIVER_NODE_EXPORT_METHODS

#define AI_DRIVER_NODE_EXPORT_METHODS ( tag )

Value:

AI_INSTANCE_COMMON_METHODS                         \
driver_supports_pixel_type;                        \
driver_extension;                                  \
driver_open;                                       \
driver_needs_bucket;                               \
driver_prepare_bucket;                             \
driver_process_bucket;                             \
driver_write_bucket;                               \
driver_close;                                      \
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;

Output Driver node methods exporter.

◆ driver_supports_pixel_type

#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

◆ driver_extension

#define driver_extension static const char** DriverExtension()

Driver's driver_extension method declaration.

If the extension is empty (returned array is {NULL} then arnold will assume the driver could be a "view" type driver as opposed to just a file writing driver. Both view and file drivers will apply imagers at the end of the render, but view drivers will also apply imagers during rendering so that there is a quicker preview of what the final image will look like. This extra imager processing can slow the render, so view drivers have the option of returning an arbitrary extension so that the faster code path is used.

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 }

◆ driver_open

#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

node	pointer to the driver node itself
iterator	output iterator for outputs connected to this driver
display_window	this is a 2D bounding box for the actual resolution
data_window	this is the actual region of pixels that will be rendered
bucket_size	maximum width in pixels of a bucket

◆ driver_needs_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

node	pointer to the driver node itself
bucket_xo	x coordinate of the bucket (upper-left)
bucket_yo	y coordinate of the bucket (upper-left)
bucket_size_x	width of the bucket in pixels
bucket_size_y	height of the bucket in pixels
tid	thread ID that will render this bucket

Returns: true if the bucket needs to be rendered, false if the bucket can be skipped

◆ driver_prepare_bucket

#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

node	pointer to the driver node itself
bucket_xo	x coordinate of the bucket (upper-left)
bucket_yo	y coordinate of the bucket (upper-left)
bucket_size_x	width of the bucket in pixels
bucket_size_y	height of the bucket in pixels
tid	thread ID that will render this bucket

◆ driver_process_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

node	pointer to the driver node itself
iterator	output iterator (loops over connected outputs for regular drivers)
sample_iterator	raw AOV sample iterator (loops over connected AOVs for raw drivers)
bucket_xo	x coordinate of the bucket (upper-left)
bucket_yo	y coordinate of the bucket (upper-left)
bucket_size_x	width of the bucket in pixels
bucket_size_y	height of the bucket in pixels
tid	thread ID that rendered this bucket

◆ driver_write_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

node	pointer to the driver node itself
iterator	output iterator (loops over connected outputs for regular drivers)
sample_iterator	raw AOV sample iterator (loops over connected AOVs for raw drivers)
bucket_xo	x coordinate of the bucket (upper-left)
bucket_yo	y coordinate of the bucket (upper-left)
bucket_size_x	width of the bucket in pixels
bucket_size_y	height of the bucket in pixels

◆ driver_close

#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

node	pointer to the driver node itself
iterator	output iterator (loops over connected outputs for regular drivers)

Function Documentation

◆ AiQuantize8bit()

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:

AtUInt8 r = AiQuantize8bit(x, y, 0, color.r, 1.0f);
AtUInt8 g = AiQuantize8bit(x, y, 1, color.g, 1.0f);
AtUInt8 b = AiQuantize8bit(x, y, 2, color.b, 1.0f);

Parameters

x	horizontal coordinate of the pixel to be quantized
y	vertical coordinate of the pixel to be quantized
i	instance number in 0..n-1, when part of a sequence of n calls
value	input floating point value to be quantized, in the [0,1] range
dither	use random dithering

Returns: quantized value, in 0..255

◆ AiQuantize16bit()

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

x	horizontal coordinate of the pixel to be quantized
y	vertical coordinate of the pixel to be quantized
i	instance number in 0..n-1, when part of a sequence of n calls
value	floating point value, in the [0,1] range
dither	use random dithering

Returns: quantized value, in 0..65535

See also: AiQuantize8bit

◆ AiDriverInitialize()

AI_API void AiDriverInitialize	(	AtNode *	node,
		bool	supports_multiple_outputs
	)

Allocates and initializes the driver structure.

This function creates an internal DriverNode structure.

Parameters

node	pointer to the driver node
supports_multiple_outputs	does this driver support more than one output routed to it?

◆ AiRawDriverInitialize()

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

node	pointer to the driver node
required_aovs	NULL-terminated array of AOV descriptors (`"TYPE name"`) to route to this driver
requires_depth	should input AOVs be tracked with depth

See also: AiDriverInitialize

◆ AiDriverGetMatrices()

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_camera	world to camera transformation matrix (looking down +Z)
[out]	world_to_screen	world to screen transformation matrix

◆ AiOutputIteratorGetNext()

AI_API bool AiOutputIteratorGetNext	(	AtOutputIterator *	iter,
		AtString *	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.

Parameters

	iter	pointer to the iterator
[out]	output_name	the name of the AOV corresponding to this output
[out]	pixel_type	the type of the pixel data (`AI_TYPE_INT`, `AI_TYPE_RGB`, etc)
[out]	bucket_data	pointer 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

◆ AiOutputIteratorReset()

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

iter	pointer to the iterator

◆ AiOutputIteratorGetFilter()

AI_API AtNode * AiOutputIteratorGetFilter ( struct AtOutputIterator * iter )

Get the filter associated with the current output.

Parameters

iter	pointer to the iterator

Returns: pointer to filter associated with current output, nullptr if none associated

◆ AiOutputIteratorIsHalf()

AI_API bool AiOutputIteratorIsHalf ( struct AtOutputIterator * iter )

Is the current output is half format.

Parameters

iter	pointer to the iterator

Returns: true if the output is of half format

◆ AiOutputIteratorGetLayerName()

AI_API AtString AiOutputIteratorGetLayerName ( struct AtOutputIterator * iter )

Get the name of the targer layer of the current output.

Parameters

iter	pointer to the iterator

Returns: name of the target layer the output will be associated with, empty string if no association

◆ AiOutputIteratorGetCamera()

AI_API AtNode * AiOutputIteratorGetCamera ( struct AtOutputIterator * iter )

Get the camera associated with the current output.

Parameters

iter	pointer to the iterator

Returns: pointer to camera associated with current output, nullptr if none associated

◆ AiFindDriverType()

AI_API const AtNodeEntry * AiFindDriverType ( const char * extension )

Get correct driver node type from an extension.

Parameters

extension a string containing the file extension, e.g. "tiff"

Returns: the AtNodeEntry corresponding to extension

Data Structures

Macros

Variables

Quantization and Dithering

API for Driver Writers

Node Method Declarations

Detailed Description

Macro Definition Documentation

◆ AI_DRIVER_NODE_EXPORT_METHODS

◆ driver_supports_pixel_type

◆ driver_extension

◆ driver_open

◆ driver_needs_bucket

◆ driver_prepare_bucket

◆ driver_process_bucket

◆ driver_write_bucket

◆ driver_close

Function Documentation

◆ AiQuantize8bit()

◆ AiQuantize16bit()

◆ AiDriverInitialize()

◆ AiRawDriverInitialize()

◆ AiDriverGetMatrices()

◆ AiOutputIteratorGetNext()

◆ AiOutputIteratorReset()

◆ AiOutputIteratorGetFilter()

◆ AiOutputIteratorIsHalf()

◆ AiOutputIteratorGetLayerName()

◆ AiOutputIteratorGetCamera()

◆ AiFindDriverType()