Image Functions

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.

mi_img_put_color

    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.

mi_img_get_color

    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.

mi_img_put_scalar

    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.

mi_img_get_scalar

    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.

mi_img_put_vector

    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!

mi_img_get_vector

    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.

mi_img_put_depth

    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.

mi_img_get_depth

    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.

mi_img_put_normal

    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.

mi_img_get_normal

    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.

mi_img_put_label

    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.

mi_img_get_label

    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.

mi_img_tonemap

    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

ref gives a reference intensity. The input color will be scaled by this value before any transformation is performed. Unless there is a specific reaason to the contrary the default value of 1 should be used.
tolerance gives an error tolerance for the tone-mapping calculations. A good value is 0.01.
low_out gives the lowest non-black intensity to be contained in the output image.
hi_out gives the highest intensisty to be contained in the output image.
low_in gives the highest intensity of the input image on which the color transformation is to be based. All greater intensities are mapped to white.
hi_in gives the lowest intensity in the input image to be considered. All intensities below are mapped to black.
lum_weight gives the weights used to compute luminance from a color.
n_bins gives the number of bins into which color intensity values of an image are to be sorted. If the number of bins is 1, then a linear mapping of color intensities is performed, which is local and does not involve information from neighboring pixels. For non-local tone mapping values of around 100 are a good choice.
x_res, y_res gives the size of a rectangle over which the color values are averaged before they are tone mapped. The default values of zero for both fields is a good choice for most cases.
x_lo, y_lo, x_hi, y_hi give a sub-rectangle within the image. Tone mapping is only applied to this rectangle.
linear. If this flag is set, then local linear tone mapping is performed.
desaturate flags whether the resulting tone-mapped color values should be desaturated such that no color component is above the hi_out value.
map is a reference to a one-dimensional scalar array decribing how color intensities are mapped for tone mapping. This field allows overriding the internal mapping calculations of the tone map routines and is optional. The default value is a null tag.