The RenderMan Interface provides a facility for editing and re-rendering a scene. A previously defined scene is given to RiEditWorldBegin, and a series of RiEditBegin \ RiEditEnd blocks are issued to perform edits.

Additional information is provided in the documentation for RiHider.

Edit Sessions

RiEditWorldBegin ( RtToken bakedb, ... parameterlist ... )
RiEditWorldEnd ()

When RiEditWorldBegin is invoked a scene is loaded and the renderer is put in re-rendering mode. There are two supported re-renderers, configured by the optional parameters:

"string rerenderer" ["reyes"]: The REYES re-renderer is the default. It interprets bakedb as the directory of a scene baked for re-rendering. By default the first world in the bake database will be the one loaded (see RiWorldBegin. If there are multiple worlds in the bake database, one may be chosen using the parameter "string bakedbname" ["worldname"].

"string rerenderer" ["raytrace"]: The ray tracing re-renderer renders a scene from scratch on every edit using the raytrace hider. This re-renderer does not require a pre-processing bake pass, so bakedb is interpreted as either a RIB file/archive suitable for ReadArchive, or a path to a bake directory initially created for REYES re-rendering. The most recent settings to the raytrace hider may also affect raytrace re-rendering. In addition, this re-renderer accepts three other settings from the parameter list:

  • "string screenorder" ["variance"|"bucket"] determines the order in which the image will be updated. The default, variance, attempts to prioritize edges and regions with strong contrasts. Alternatively, bucket forces it to respect the currently active bucket order.
  • "int progressive" [1] controls whether the re-renderer displays a rapid low-resolution preview before resolving finer detail. The preview may be disabled by setting this option to 0. This is automatically enabled when the Hider options are set to "string integrationmode" "path" and "int incremental" 1.
  • "string integrationmode" ["distribution" | "path"] tells the raytrace hider whether to use distribution ray tracing (the default) or path tracing. This parameter will override the Hider option, but does not provide full support for the optional parameters, so the Hider option is preferred at this time. It will also force "screenorder" to "bucket".
  • "float[4] cropwindow" crops the initial display using the provided coordinates, specified as fractions of the window (values between 0 and 1).

RiEditWorldEnd closes the editing session.

Additionally, the re-renderer supports an RiOption "rerender" "int[2] lodrange" for the specification of which initial pass (or level of detail) to use.


EditWorldBegin name ...parameterlist...
EditWorldEnd -


RiEditWorldBegin ("bake", RI_NULL);
RiEditWorldEnd ();


RiWorldBegin, RiHider

Edit Blocks

Editing is performed by issuing a series of RiEditBegin \ RiEditEnd blocks. The Ri calls in an edit block are applied to the scene database and the scene is re-rendered during RiEditEnd. The range of edits that can be applied to a scene are renderer-dependent.

RiEditBegin ( RtToken editcategory, ... parameterlist ... )
RiEditEnd ()

Edits to a scene are specified using one of three types of edit blocks. The scene is re-rendered at the end of each edit block, before RiEditEnd returns.

The editcategory parameter of RiEditBegin may be one of the following:

"option" Changes to the option state are made during an option edit block. Not all options may be changed during edit, and not all re-renderers support the same set of editable options. For instance, the camera may be changed when re-rendering with the raytrace re-renderer, but not when using the REYES re-renderer.

"attribute" Changes to attribute state include: binding of shaders to lights and gprims, the active light list of a gprim, coordinate systems, and user-defined attributes. By default, the global attribute state is the one active during an edit. To restrict attribute changes to a particular gprim, the optional parameter "string scopename" ["regexp"] directs the renderer to search the attribute database, and all scopes whose attribute identifier:name match the given regular expression will be edited.

"instance" The renderer supports editing the parameter list of groups of similar shaders without the need to rebind the shaders. To enable this, a shader is issued with the optional parameter "string __instanceid" ["name"]. Every shader issued with the same instance id must have identical parameter lists. Supplying an instance id is a directive to the renderer that a group of shaders are sharing a single parameter state.

The optional parameters include:

"string editlights" [lighthandle1:lighthandle2] The REYES re-renderer recomputes the portion of the lighting in a scene due to the set of lights being edited. This parameter is currently ignored by the raytrace re-renderer.

"int displayonlyeditlights" [0] If enabled, the REYES re-renderer will display the scene as illuminated only by the lights being edited. This parameter is currently ignored by the raytrace re-renderer.

"string scopename" ["regular expression"] When passed to an attribute edit block, the attribute database is searched and all scopes whose attribute identifier:name match the regular expression will be edited. All subsequent Ri calls, until a matching RiEditEnd(), will modify these attribute states. The default value for scopename, the empty string, directs the renderer to edit the global scope.

RiEditEnd does not normally return until the rendering program has completed drawing the image. If the image is to be saved in a file, this is done automatically by RiEditEnd.


EditBegin - category ...parameterlist...
EditEnd -


RiEditBegin ("attribute", "string editlights", &lights, RI_NULL);
RiEditEnd ();



The edits that can be applied to a scene have been classified into three categories: options, attributes, and instances.

Editing Options

Options include the configuration of the display, hider, camera, crop window, and renderer run-time controls. The REYES re-renderer supports a very limited set of option edits: changing crop windows and "rerender" run-time controls. The raytrace re-renderer supports arbitrary changes to the camera, but the display and hider may not be changed.

Setting a Crop Window

Crop window changes during editing restrict the region of the image updated during an edit. Unlike an off-line render, setting a crop window during re-rendering will not change the size of the image as presented to a display driver. Instead, a new call has been added to the display driver interface that tells the driver what the active region is. For details see: DspyImageActiveRegion

Crop windows can be used both when baking and during editing. The crop set during editing is relative to the original size of an image, not to a crop set during baking (if any).

RiEditBegin( "option", RI_NULL );
  RiCropWindow( ... );
Moving the Camera

The raytrace re-renderer supports arbitrary changes to the camera. Edits should be applied to the camera named world. The changes to the camera may be specified inline in the RiCamera() call, or by using individual calls to change camera settings followed by a call to RiCamera().

RiEditBegin( "option", RI_NULL );
  RiTranslate( ... );
  RiDepthOfField( ... );
  RiCamera( "world", ... );

Editing Attributes

The attribute state includes all flags and values in the graphics state that are bound to gprims. This includes the shader set (displacement, surface, atmopshere, etc.), the light list, the co-shader list, user-defined attributes, and scoped coordinate systems. The attribute state also includes global information such as: the binding of light shaders to light handles and named coordinate systems. When editing attribute state, the name of the attribute scope to edit must be supplied. By default the global scope is edited.

When using an attribute edit block, edits to shaders are implemented as a rebinding edit. The previous shader is completely replaced. As a result, the edit must completely respecify the shader, including the shader space and all co-shaders referenced in the parameter list of the shader.

In contrast, instance edits, described below, allow changes to the parameter list of a shader without regenerating the shader space

Editing a Light

Lights, referred to by their globally unique handles, are changed by issuing an RiLightSource call with the same handle. All parameters to the light must be reissued, including its transformation.

RiEditBegin("attribute", "string editlights", "light1", RI_NULL);
  // specify the coordinate system for light1
  RiTransform( ... );
  RiLightsource( "spotlight", RI_HANDLEID, "light1", "color lightcolor", (RtPointer)&color );
Adding a Light

Adding a light is a two-step process. First it is declared, which creates a globally unique handle, then the attribute state of every gprim that should receive the light is modified. In Ri, a light is turned on by default in the current and enclosed scopes. At edit time, we no longer know the nesting relationship of scopes because the attribute hierarchy has been flattened. So we adopt the convention that lights created during relighting are off by default and illuminate no objects. The light list of every gprim to be illuminated by the new light must then be updated. The scope parameter is matched against the attribute identifier:name.

When adding a light, one may not specify a list of lights to edit. Adding and editing must be done in separate edit blocks.

RiEditBegin("attribute", RI_NULL);
  // create coordinate system for light2
  RiTransform( ... );
  // save this transform for future use
  RiCoordinateSystem( "light2_xform" );
  RiLightsource( "pointlight", RI_HANDLEID, "light2", "color lightcolor", (RtPointer)&color );
  // shine the light on the gprim named "left_hand"

char* sn = "left_hand";
RiEditBegin("attribute", "string scopename", &sn, RI_NULL);
  RiIlluminate( "light2", 1 );
Deleting a Light

To delete a light, simply set its shader to null. The renderer will automatically remove the light from every light list in every gprim.

When deleting a light, one may not specify a list of lights to edit. Deleting and editing must be done in separate edit blocks.

RiEditBegin("attribute", RI_NULL);
  RiLightSource( RI_NULL, RI_HANDLEID, "light1" );
Muting a Light

Override illumination during live rendering.

A new type of edit overrideilluminate allows lighting applications to turn on/off lights non-destructively (light linking is preserved).

Multiple overrides can be provided in a single edit. For instance, to "solo" a light (turn all but this light off):

RiEditBegin("overrideilluminate", RI_NULL);
  RiIlluminate("*", 0, RI_NULL);
  RiIlluminate("lightBlue", 1, RI_NULL);

Where "*" matches all lights. To clear an overrider, send -1. For instance, to clear all overrides:

RiEditBegin("overrideilluminate", RI_NULL);
  RiIlluminate("*", -1, RI_NULL);

Which will revert to the pre-existing light linking.

Changing a Surface

The raytrace re-renderer renders a scene from scratch on every edit, so arbitrary changes to surface shaders will be properly incorporated into the rendered image. The REYES re-renderer fixes visibility at the time the scene is baked for re-rendering. So, while surface shaders may be changed during editing, visibility may not. A change in a surface shader that changes opacity will not result in an accurate image.

To change a surface:

char* sn = "left_hand";
RiEditBegin("attribute", "string scopename", &sn, RI_NULL);
  RiSurface( "new_surface", ... );
Editing an Area Light Source

As with a surface edit, the raytrace re-renderer will incorporate changes from edits to transformations or changes to shader shader parameters. The REYES re-renderer does not support edits to area light sources.

To edit an area light source:

char* sn = "myAreaLightSource";
RiEditBegin("attribute", "string scopename", &sn, RI_NULL);
  RiTranslate( 1.0, 0.0, 0.0 );

This will find all area light sources in the attribute id scope called: "myAreaLightSource" and re-issue the translation in X by 1 to the transform on that light source. Keep in mind that, like other attribute edits, these are replacements edits, not relative edits. All transform calls must be reissued to get back to the original transformation on the area light before the edit.

Editing Shader Instances

An instance is defined as a unique invocation of a shader. Every use of a particular shader instance must have identical parameter lists. To declare an instance, include the parameter __instanceid in the shader call in the same way __handleid is used to identify light handles.

In RIB, a surface shader instance is shared by two gprims by:

    Translate -1 0 0
    Attribute "identifier" "name" ["patch1"]
    Surface "matte" "__instanceid" "myinst" "float Kd" [.6]
    Patch "bilinear" "P" [0 1 0  1 1 0  0 0 0  1 0 0]

    Translate -1 0 0
    Attribute "identifier" "name" ["patch2"]
    Surface "matte" "__instanceid" "myinst" "float Kd" [.6]
    Patch "bilinear" "P" [0 1 0  1 1 0  0 0 0  1 0 0]

To edit the parameter list of the surfaces on both gprims simultaneously (in RIB):

EditBegin "instance"
  Surface "matte" "__instanceid" "myinst" "float Kd" [.8]

Lights and co-shaders may also be edited using instances. For details of light instance editing, see the example in the RenderMan Pro Server distribution.

More Re-rendering Examples

The RenderMan Pro Server distribution has several Python-based examples in the directory: $RMANTREE/lib/examples/rerender.

Deprecated Edit blocks

RiEditAttributeBegin ( RtToken scopename, ... parameterlist ... )
RiEditAttributeEnd ()
Previously, edits to attribute state were accomplished using an RiEditAttributeBegin \ RiEditAttributeEnd block. These calls have been deprecated in favor of the "attribute" editcategory. These calls remain in version 16 of RenderMan Pro Server, but will be removed in the next version.