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

Copyright © 1986-2010 by mental images GmbH