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 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... | |
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.
| #define AI_DRIVER_NODE_EXPORT_METHODS | ( | tag | ) |
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.
| #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.
| #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.
| 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 |
| #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.
| 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 |
| #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.
| 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 |
| #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.
| 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 |
| #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.
| 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 |
| #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.
| node | pointer to the driver node itself |
| iterator | output iterator (loops over connected outputs for regular drivers) |
| 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:
| 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 |
| 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.
| 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 |
| AI_API void AiDriverInitialize | ( | AtNode * | node, |
| bool | supports_multiple_outputs | ||
| ) |
Allocates and initializes the driver structure.
This function creates an internal DriverNode structure.
| node | pointer to the driver node |
| supports_multiple_outputs | does 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.
| 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 |
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,...).
| [out] | world_to_camera | world to camera transformation matrix (looking down +Z) |
| [out] | world_to_screen | world to screen transformation matrix |
| AI_API const AtNodeEntry * AiFindDriverType | ( | const char * | extension | ) |
Get correct driver node type from an extension.
| extension | a string containing the file extension, e.g. "tiff" |
extension