Contour Store Function

The contour store shader stores various information needed for contour computations. The input is the regular state after ray intersection and the call of material shader, and the color resulting from the material shader call. The output is the information the user deems necessary to compute contours, and the size of this information. There is only one global contour store shader for a scene. The contour store function's job is to collect all information that the contour contrast function needs to decide where to put contours and that the contour shaders need to draw a contour.

To give an example of a contour store shader, assume you have decided that to compute contours, you need the ray intersection point, the normal vector, the material, and the color at that point as computed by the material shader (which means the color is not just the color of the material with the given illumination; it also includes reflected and refracted light). Then define the data type MyInfo as

     typedef struct MyInfo {
        miVector   point;      /* ray intersection point */
        miVector   normal;     /* ray intersection normal */
        miTag      material;   /* material tag */
        miColor    color;      /* from material shader */
     } MyInfo;

Here is a contour store shader that fills in these fields of MyInfo:

     miBoolean my_contour_store_function(
        void     *info_void,
        int      *info_size,
        miState  *state,
        miColor  *color)
     {
        struct MyInfo *info = (MyInfo *)info_void;

        info->point    = state->point;
        info->normal   = state->normal;
        info->material = state->material;
        info->color    = *color;

        *info_size = sizeof(MyInfo);    /* for mental ray 2.x */

        return(miTRUE);
     }

mental ray will store a MyInfo data structure with every sample until the contour contrast shader is called. The number of stored MyInfo data structures grows up to the number of samples taken in an image task (typically a 32 × 32 pixel block).

Note that mental ray 3.x requires that the contour store shader is declared correctly:

     declare shader
         struct {
              vector    "point",
              vector    "normal",
              material  "material",
              color     "color"
         } "out_depthfade" (scalar "near", scalar "far")
         version 1
     end declare

mental ray 2.x ignored the return type and required that the shader assigns the size of the returned data in * info_size. This will no longer work with mental ray 3.x, which must know the return size in advance, and therefore requires a correct declaration. mental ray 3.x will print an error message if the return type declaration is missing and allocates space for one color, but in this case this would not be enough, so the shader would crash!