Ri Control

Ri Control


The Ric (Ri Control) APIs facilitate integration of the prman renderer into applications. These APIs are primarily targeted toward the control of a prman process that is running asynchronously with respect to an application. The Ric API is defined in the Ric.h header file.

The Ric API operates in concert with three other APIs: the ability to launch prman as a separate process through RiBegin; use of an in-process display driver through DspyRegisterDriverTable, described in Direct-linked Display Driver Registration; and use of an in-process error handler regsitered with RiErrorHandler. Please refer to RiBegin for the details of configuring a detached prman.

When writing an interactive application that takes advantage of an in-process display driver or error handler, it is especially important to use RicProcessCallbacks correctly. To ensure timely delivery of pixels and error messages, place a call to this function in the idle loop of your application.

C Entrypoints

void RicFlush (RtString marker, RtBoolean synchronous, RtToken flushmode )

RicFlush provides a mechanism to synchronize a client application and a detached prman process at a particular point in an Ri stream. When prman is operating in a separate process, Ri calls can be issued much faster by the client application than they are consumed by the renderer.

This is particularly important when re-rendering. Since edits can be sent much faster than they can be consumed, it is important that the renderer be interruptable. The queue of edits can be flushed by marking a place in the Ri stream with an id and subsequently calling RicFlush() to advance the renderer to that place in the stream.

marker is the stream marker tha has been inserted in the Ri stream. synchronous determines whether or not the call blocks waiting for the renderer to complete the flush: if 1 the call blocks; if 0 it returns immediately. flush mode tells the renderer whether or not it should do any rendering while advancing through the Ri stream. RI_SUSPENDRENDERING tells the renderer to stop rendering if it is doing so, go back to parsing rib, and not to do any more rendering until the stream marker has been found. RI_FINISHRENDERING tells the renderer to proceed as normal, performing rendering at RiWorldEnd() and RiEditEnd().

The four combinations of synchronous and flushmode produce:

Asynchronous combined with suspended rendering is the typical use when issuing edits during rerendering. The editing application tells the renderer to stop what it is doing and advance to the marker while the application, in parallel, issues another edit.

Synchronous and suspend stops rendering and blocks the client application until the renderer has consumed all Ri calls up to and including the marker. This is the mode to be used to synchronize the renderer with a client application that is changing a resource used by the renderer, like shadow maps.

Asynchronous and finish is a noop - it is what the renderer is doing anyway.

Synchronous and finish blocks until rendering is done. This is useful if the client application wants to ensure that a rendering is not interrupted.

To mark a place in the Ri stream we use the archive record mechanism. Assuming your application maintains a string current_editid:

RiArchiveRecord( "structure", "%s%d", RI_STREAMMARKER, m_editId, RI_NULL );

To flush the renderer to this point:

RicFlush( current_editId, 0, RI_SUSPENDRENDERING );

Flushing to a marker that does not exist, in combination with suspended rendering, will stop the renderer, and it will not render again until it receives an archive record with that marker. To turn off flushing, simply send an empty string to RicFlush().

RtInt RicGetProgress ();
This returns the percentage done of the current render. From the time prman is started until the first render starts (the first world of a regular render, EditWorldBegin() in a re-render), progress will be 0. During a rendering it will be the appropriate value. After a render has finished and before the next one starts (in between worlds in a regular prman render, in between edits in a re-render), progress will be 100.

void RicProcessCallbacks ()

Error messages and pixels can arrive in the client application's process at any time. To give the application control over the timing of the delivery of these messages, they are queued and delivery to the Ri error handler and user-supplied display driver is delayed until RicProcessCallbacks() is called.

The typical use of this function is to place it in the idle loop of the application.

Python Entrypoints

The python binding of Ric is provided by the prman.py module:

prman.RicFlush(marker, synchronous, flushmode);

See also:

PRMan for Python