Pass Rendering Functions

mi_renderpass_sample_get
mi_renderpass_sample_put
mi_renderpass_samplerect_flush
mi_renderpass_samplerect_black

Pass Rendering Functions

void *mi_renderpass_access(
    miState         *state,
    int             pass,
    int             fb)

This function is used by pass rendering merge functions to retrieve a pointer to sampling data. The merge function is called once for each sample, and has to merge all render pass samples for the same coordinate into the result sample. The pass argument is -1 for obtaining a pointer to the result sample, or 0 … state→options→npasses−1 for obtaining a pointer to the sample rendered in that pass. If a null pointer is returned, the pass did not cast this sample; this happens only if the corresponding area of the pass image is completely blank or the frame buffer specified by fb was not rendered. (The shader may assume an all-null sample in this case.) The fb argument specifies the frame buffer to access, and must be one of the miRC_IMAGE_* macros. miRC_IMAGE_RGBA and miRC_IMAGE_Z are always available; others may return 0.

mi_renderpass_sample_get

miBoolean mi_renderpass_sample_get(
    void            *result,
    int             resultsize,
    miState         *state,
    int             fb,
    int             x,
    int             y)

This function is intended exclusively for pass preprocessing functions. It returns the sample data from a single frame buffer fb at the specified sample coordinate x, y. The sample is copied to result. At most resultsize bytes are copied. For example, if fb is miRC_IMAGE_RGBA, result should be a pointer to a miColor and resultsize should be sizeof(miColor). Since miRC_IMAGE_RGBA is always the first frame buffer, it is possible to copy the entire sample by specifying a larger resultsize. A size that is too large will be truncated to the actual sample size. This assumes that the prep shader knows the actual sample layout, which makes such a shader nonportable to other projects. The imf_info -m command-line tool can be used to determine the sample layout of a pass sample file.

mi_renderpass_sample_put

miBoolean mi_renderpass_sample_put(
    void            *result,
    int             resultsize,
    miState         *state,
    int             fb,
    int             x,
    int             y)

This function is intended exclusively for pass preprocessing functions. It is the reverse function to the previous, and writes a sample to the output pass file. Written samples cannot be read again; the get and put functions access different pass files according to the read and write file names specified in the pass prep statement in the options block.

mi_renderpass_resolution(
    int             *xl,
    int             *yl,
    int             *xs,
    int             *ys,
    int             *xres,
    int             *yres,
    miState         *state,
    int             x,
    int             y)

This function is intended exclusively for pass preprocessing functions. It returns information about the rectangle that the sample coordinate x, y is in. Pass files are organized in the same rectangles that become visible as rendering units when attaching the imf_disp tool to a running mental ray render. They generally have a fixed size depending on oversampling, but may be smaller or larger near the edges of the image. The lower left sample coordinate xl, yl, the rectangle size in samples xs, ys, and the resolution of the entire image in samples xres, yres is returned. Any of these pointers may be null if the corresponding count is not needed. Note that rectangles may overlap. It is often useful to consider rectangles when preprocessing even though the get and put functions seem sufficient, because the following flush and black functions allow optimizations based on rectangles.

mi_renderpass_samplerect_flush

miBoolean mi_renderpass_samplerect_flush(
    miState         *state,
    int             pass,
    int             x,
    int             y)

This function is intended exclusively for pass preprocessing functions. If applied to the read pass file ( pass is 1), this announces that the rectangle that the coordinate x, y is in will not be read from for a while, which removes it from the cache. If applied to the write pass file ( pass is 0), this announces that the prep shader is definitely finished with writing this rectangle. It is ok to read again from a flushed rectangle, but writes to flushed rectangle will be ignored and must be avoided. The flush function reduces the memory required for preprocessing a pass file.

mi_renderpass_samplerect_black

miBoolean mi_renderpass_samplerect_black(
    miBoolean       *result,
    miState         *state,
    int             x,
    int             y)

This function is intended exclusively for pass preprocessing functions. It returns miTRUE if all samples in the rectangle that the coordinate x, y is in are entirely black (all null bytes). Calling this function can avoid a lot of unnecessary computation in the prep shader.