|
AI_API AtUInt8 | 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 AtUInt16 | AiQuantize16bit (int x, int y, int i, float value, bool dither) |
| Quantize a floating point number down to a 16-bit integer. More...
|
|
|
#define | driver_supports_pixel_type static bool DriverSupportsPixelType(const AtNode* node, AtByte 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, int 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, int 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, int 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...
|
|
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 | ) |
|
Value:
driver_extension; \
driver_open; \
driver_needs_bucket; \
driver_prepare_bucket; \
driver_process_bucket; \
driver_write_bucket; \
driver_close; \
DriverSupportsPixelType, \
DriverExtension, \
DriverOpen, \
DriverNeedsBucket, \
DriverPrepareBucket, \
DriverProcessBucket, \
DriverWriteBucket, \
DriverClose, \
}; \
&ai_common_mtds, \
&ai_driver_mtds \
Output Driver node methods exporter.
#define driver_supports_pixel_type static bool DriverSupportsPixelType(const AtNode* node, AtByte 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
-
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, int 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
#define driver_prepare_bucket static void DriverPrepareBucket(AtNode* node, int bucket_xo, int bucket_yo, int bucket_size_x, int bucket_size_y, int 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 |
#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, int 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 |
#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 |
#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) |
AI_API AtUInt8 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:
- 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
AI_API AtUInt16 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
AI_API void AiDriverInitialize |
( |
AtNode * |
node, |
|
|
bool |
supports_multiple_outputs, |
|
|
void * |
data |
|
) |
| |
Allocates and initializes the driver structure.
This function creates an internal AtDriverNode structure and sets its data parameter to point to the incoming data
pointer. This is the same data pointer that will be returned by the AiDriverGetLocalData() function.
- Parameters
-
node | pointer to the driver node |
supports_multiple_outputs | does this driver support more than one output routed to it? |
data | pointer to the driver's local data |
AI_API void AiRawDriverInitialize |
( |
AtNode * |
node, |
|
|
const char ** |
required_aovs, |
|
|
bool |
requires_depth, |
|
|
void * |
data |
|
) |
| |
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 |
data | pointer to the driver's local data |
- See Also
- AiDriverInitialize
AI_API void AiDriverDestroy |
( |
AtNode * |
node | ) |
|
Destroys an allocated driver structure.
- Parameters
-
node | pointer to the driver node |
AI_API void* AiDriverGetLocalData |
( |
const AtNode * |
node | ) |
|
Get the driver's local data pointer.
- Parameters
-
node | pointer to the driver node |
- Returns
- local data pointer, as passed to 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_camera | world to camera transformation matrix (looking down +Z) |
[out] | world_to_screen | world 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.
- 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
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 |
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