Introduction

This documentation is intended to instruct developers in the authoring of custom projections. Developers should also consult the RixProjection.h header file for complete details. The source code for the PxrOrthographic and PxrPerspective projection plugins may be found in the plugins/projection/simple subdirectory of the PixarRenderMan-Examples package.

A projection plugin is used to model camera and lens behavior. These plugins are responsible for taking stratified random samples as input from the renderer and turning these into primary camera rays.

RixProjectionFactory

RixProjectionFactory is a subclass of RixShadingPlugin, and therefore shares the same initialization, synchronization, and parameter table logic as other shading plugins. Projections do not support lightweight instances, and therefore CreateInstanceData() should not be overridden as any created instance data will not be returned to the factory.

The renderer uses the RixProjectionFactory object by invoking RixBxdfFactory::CreateProjection()  to obtain a  RixProjection. A description of various options associated with the current render are provided to the factory via the RixProjectionEnvironment &env. This class includes information about the current format (the width and height of the image in pixels and the pixel aspect ratio), the screen window, the shutter time values, the near and far clipping planes, and the world to camera transform. Developers are expected to use this information, along with the arguments supplied to the plugin via the RixParameterList pList, to create an instance of RixProjection that encapsulates the information necessary to model the desired camera and lens behavior.

RixProjectionEnvironment contains one field that can be altered: the deepMetric field. This is used to indicate to the renderer the depth metric used for computing Z values when rendering deep output. The default value of k_cameraZ indicates the renderer should use the distance strictly in the Z axis and can assume that all camera rays go forward in the +Z direction, while k_rayLength indicates that the distance should be measured along the ray direction, as the rays may be go in either the -Z or +Z direction. All other fields on RixProjectionEnvironment should be considered read only.  For example, a plugin that implements the standard perspective projection should return k_cameraZ, while a plugin that implements a cylindrical panoramic projection should use k_rayLength.

RixProjection

Once a RixProjection object is obtained, the renderer will invoke the following methods: