The IMG module of mental ray provides functions that deal with images. There are functions to read and write image files in various formats, and to access in-core frame buffers such as image textures. First, the functions that access frame buffers are listed. These functions are typically used by texture shaders, which can obtain an image pointer by calling mi_db_access with the image tag as an argument. All these functions do nothing or return defaults if the image pointer is 0, or if the x or y coordinate is out of bounds. They do not check whether the frame buffer has the correct data type. All these functions are available in all shaders, including displacement, geometry, and output shaders.
void mi_img_put_color( miImg_image *image, miColor *color, int x, int y)
Store the color color in the color frame buffer image at coordinate x y, after performing desaturation or color clipping, gamma correction, compensating for premultiplication, and dithering. Not all of these steps may be performed, and the behavior is dependent on the options colorclip, premultiply, desaturate, gamma, and dither as given on the command line or in the .mi file. This function works with 1, 2, or 4 components per pixel, and with 8, 16, or 32 (float) bits per component. The normal range for the R, G, B, and A color components is [0, 1] inclusive. For 32 bit (float) frame buffers only compensation for premultiplication is done.
void mi_img_get_color( miImg_image *image, miColor *color, int x, int y)
This is the reverse function to mi_img_put_color. It returns the color stored in a frame buffer at the specified coordinates. Gamma compensation and premultiplication, if enabled by mi_img_mode, are applied in reverse. The returned color may differ from the original color given to mi_img_put_color because of color clipping and color quantization.
void mi_img_put_scalar ( miImg_image *image, float scalar, int x, int y)
Store the scalar scalar in the scalar frame buffer image at coordinate x y, after clipping to the range [0, 1]. Scalars are stored as 8-bit or 16-bit unsigned values. This function is intended for scalar texture files of type miIMG_S or miIMG_S_16.
void mi_img_get_scalar ( miImg_image *image, float *scalar, int x, int y)
This is the reverse function to mi_img_put_scalar. It returns the scalar stored in a frame buffer at the specified coordinates, converted to a scalar in the range [0, 1]. If the frame buffer pointer is 0, or if the x or y coordinate is out of bounds, the scalar is set to 0.
void mi_img_put_vector ( miImg_image *image, miVector *vector, int x, int y)
Store the X and Y components of the vector vector in the vector frame buffer image at coordinate x y, after clipping to the range [-1, 1]. Vectors are stored as 16-bit signed values. This function is intended for vector texture files of type miIMG_VTA or miIMG_VTS. Warning: this function accesses 16-bit UV vectors, not the floating-point XYZ normal and motion vectors stored in frame buffers. This means it's largely obsolete because hardly anyone still uses explicit bump basis vectors, and output shaders should almost certainly use mi_img_put_normal instead!
void mi_img_get_vector ( miImg_image *image, miVector *vector, int x, int y)
This is the reverse function to mi_img_put_vector. It returns the UV vector stored in a frame buffer at the specified coordinates, with coordinates converted to the range [-1, 1]. The Z component of the vector is always set to 0. If the frame buffer pointer is 0, or if the x or y coordinate is out of bounds, all components are set to 0. Again, make sure you should not be using mi_img_get_normal.
void mi_img_put_depth( miImg_image *image, float depth, int x, int y)
Store the depth value depth in the frame buffer
image at the coordinates x y. The depth value is not
changed in any way. The standard interpretation of the depth is the
(positive) distance of objects from the camera origin. mental ray
uses this function internally to store
−(state→dist)
if the depth frame buffer is
enabled with an appropriate output statement. By
convention, the value 0.0 signifies infinite distance.
void mi_img_get_depth( miImg_image *image, float *depth, int x, int y)
Read the depth value to the float pointed to by depth from frame buffer image at the coordinates x y. If the image pointer is 0, or if the x or y coordinate is out of bounds, return the MAX_FLT constant from limits.h.
void mi_img_put_normal( miImg_image *image, miVector *normal, int x, int y)
Store the normal vector normal in the frame buffer image at the coordinates x y. The normal vector is not changed in any way. This function can also be used for the motion vector frame buffer.
void mi_img_get_normal( miImg_image *image, miVector *normal, int x, int y)
Read the normal vector normal from frame buffer image at the coordinates x y. If the image pointer is 0, or if the x or y coordinate is out of bounds, return a null vector. This function can also be used for the motion vector frame buffer.
void mi_img_put_label( miImg_image *image, miUint label, int x, int y)
Store the label value label in the label frame buffer image at the coordinates x y. The label value is not changed in any way.
void mi_img_get_label( miImg_image *image, miUint *label, int x, int y)
Read the label value to the unsigned integer pointed to by label from frame buffer image at the coordinates x y. If the image pointer is 0, or if the x or y coordinate is out of bounds, return 0.
int mi_img_get_width( miImg_image *image)
Return the actual resolution of the image as number of pixels in x direction. This function should be used to determine the image size during rendering instead of directly accessing the field in the image structure, which may be changed by mental ray for texture caching.
int mi_img_get_height( miImg_image *image)
Return the actual resolution of the image as number of pixels in y direction. This function should be used to determine the image size during rendering instead of directly accessing the field in the image structure, which may be changed by mental ray for texture caching.
miImg_image *mi_img_pyramid_get_level( miImg_image *image int level)
Return the subimage at level of the image pyramid.
If level is out of range the image of the closest level is returned.
The number of available pyramid images is stored
in image→dirsize
.
miBoolean mi_img_tonemap( miImg_image *outimage, miImg_image *inimage, miImg_tonemap *para)
performs a tone mapping on the provided input image and stores the result in the given output image. Tone mapping is commonly performed from an output shader. The input and output image pointer may refer to the same image. The behaviour of the tone mapper is determined by the provided parameters. The structure is given as
struct miImg_tonemap { miScalar ref; miScalar tolerance; miScalar low_out; miScalar hi_out; miScalar low_in; miScalar hi_in; miColor lum_weight; int n_bins; int x_res; int y_res; int x_lo; int y_lo; int x_hi; int y_hi; miBoolean linear; miBoolean desaturate; miTag map; };
The fields of the miImg_tonemap structure have the following meanings
Copyright © 1986-2009 by mental images GmbH