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( ... );
RiEditEnd();

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", ... );
RiEditEnd();

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 );
RiEditEnd();

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"
RiEditEnd();

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

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" );
RiEditEnd();

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);
RiEditEnd();

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

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

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", ... );
RiEditEnd();

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 );
RiEditEnd();

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.