Display Callbacks

mi_disp_stream_pipe_begin
mi_disp_stream_socket_begin
mi_disp_stream_cb_begin
mi_disp_stream_jpeg_cb_begin
mi_disp_stream_end

Display Callbacks

Image data callbacks must be installed and uninstalled with the following two functions. Unlike the file descriptor and socket methods, the calling application is aware of when frames begin and end, and has access to the result of output shaders, because it calls mi_rc_run and has access to all data before and after mi_rc_run. Therefore, only image tile data is transferred during rendering, but not after output shading. Also, there are no notifications when frames begin and end, and what the resolution and gamma values are (all this is already known by the caller of mi_rc_run). The callback is intended for showing rendering progress within parent application windows.

Display Functions

mental ray uses the notion of a stream for all realtime image display methods. For each method, there is a begin function that creates the stream, and the is a single end function that destroys a stream. Streams are identified by an identifier of type miStream. While a stream is open, it propagates frame begin/end and tile begin/end information, in a format that depends on the stream method.

Note that mental ray runs the DISP module in a separate thread. This means that display callbacks are not called in the thread that set up the callback stream. Also, there may be a small delay before a terminated stream stops sending rectangles; this needs careful attention if streams are created and terminated in the middle of rendering.

mi_disp_stream_pipe_begin

miStream mi_disp_stream_pipe_begin(
    int             fd)

Create a pipe stream that sends messages of type 5 when a frame begins, 4 when a frame ends, and 2 for every finished rectangle, as described in this table. Messages are written to the file descriptor fd. The returned miStream code identifies the stream and must be used for terminating the stream using mi_disp_stream_end. The stream will remain open until it is explicitly terminated.

mi_disp_stream_socket_begin

miStream mi_disp_stream_socket_begin(
    int             fd)

Create a socket stream that sends messages of type 6 when a frame begins, 4 when a frame ends, and 2 for every finished rectangle, as described in this table. Except for the type of the frame begin message, the stream is similar to a pipe stream.

mi_disp_stream_cb_begin

typedef void (*miDisp_cb)(
    void            *arg,
    miRc_mapfb      *fbmap,
    int             xl,
    int             yl,
    int             xh,
    int             yh);

miStream mi_disp_stream_cb_begin(
    void            *arg,
    miDisp_cb       rcb)

Create a callback stream. The callback will be called in four situations:

when the frame begins,
image, xl, and yl will be 0 and xh and yh contain the image resolution from the camera,
when the frame ends,
all arguments except arg are 0,
when a rectangle begins
image is 0 and xl, yl, xh, and yh describe the position of the lower left and upper right corner of the rectangle in image pixel coordinates,
when the rectangle is finished,
same values except image contains valid image rectangle tags.

The distinction between rectangle begin and end is available only for callback streams (although later versions may make it available for sockets and pipes as well). It allows previewers to announce that a rectangle has started rendering using little cross-hair markers or similar, to give the user better feedback. For all calls, the arg argument is an opaque pointer that always has the value given to mi_disp_stream_cb_begin; it can be used to pass a this pointer to a C++ method.

The fbmap is an opaque miRc_mapfb pointer. It is either zero (see above) or points to a structure in memory. A frame buffer image can be accessed using the mi_disp_fbmap and mi_disp_fbunmap functions (address by index, like one of the miRC_IMAGE_* indices for standard frame buffers). 3.6New integrations may use the mi_disp_fbmap_name and mi_disp_fbunmap_name functions with named frame buffers.

mi_disp_stream_jpeg_cb_begin

typedef void (*miDisp_jpeg_cb)(
    void            *arg,
    void            *data,
    int             size);

miStream mi_disp_stream_jpeg_cb_begin(
    void            *arg,
    miDisp_jpeg_cb  jcb,
    int             q)

Create a JPEG callback stream. The callback will be called in two situations: when the frame ends (data and size are 0), and when enough rectangles have been rendered and compressed to send more JPEG data ( data points to a buffer containing size bytes). Due to the nature of JPEG compression, there is no direct association between pixel rectangles and buffers. If all data passed by the callback is written to a file in sequence, a complete JFIF image results. The arg pointer is again an opaque user-defined pointer.

As a side effect, mi_disp_stream_jpeg_cb_begin sets the tile order to top-down to optimize streaming. It can be restored to another order with mi_rc_set_taskorder.

mi_disp_stream_end

miStream mi_disp_stream_end(
    miStream        vstr)

Terminate a stream. vstr is the stream identifier returned by the function that created the stream. No more data will be sent down this stream. However, since the DISP module runs in a separate thread, there may be calls still scheduled or in progress.