This topic describes the operation of the XGen RenderMan DSO as well as all of its arguments. It describes the procedural so that you can implement your own method of getting XGen to render itself.
There are two forms of the XGen RenderMan procedural: patch and face. The rib generator is responsible for putting the patch level procedural calls into the rib. XGen expands those into face procedurals when, and if, the patch procedural is cracked open. It is only when the face procedural is cracked that primitives are generated and therefore any real rendering begins. It is the patch procedural that takes all of the flags given below. A bounding box must be given for the patch procedural. It must bind all of the faces and all of the primitives that are to be rendered. If it is too small, clipping occurs. If it is too large, the procedural cracks open too soon and memory is wasted. The bounding box should bind all motion samples for that patch.
When a patch procedural is cracked, it parses the parameters. If it determines that this is the first time that the given palette has been hit, it loads in the palette file, reads the appropriate geometry for the motion samples, and caches it. It then emits face procedurals for all of the faces on the named patch. If the palette has already been cached, then the file is not read, but instead the process skips ahead and begins emitting the face procedurals for the named patch.
The palettes are cached based on their name, which includes the name of the nameSpace. This allows the same .xgen file to be used multiple times in order to populate a forest or a crowd. However, you must give each instance a unique name so that they do not end up sharing geometry inadvertently.
The geometry files are cached separately from the palette files, allowing for greater sharing. For example, the same geometry is often used multiple times, even within the same palette. You may have a forest of trees where a few are the same. Memory can be saved by allowing sharing. The XGen palettes would not be shared, but the underlying geometry would.
The procedural takes a number of arguments as flags. Each is listed below with a brief description and an indication as to whether or not it is optional.
| -debug | Sets the level for debug messages (optional). |
| -stats | Sets the level for statistics messages (optional). |
| -warning | Sets the level for warning messages (optional). |
| -quitOnError | Tells XGen to quit if any error occurs (optional). |
| -nameSpace | If a nameSpace exists for the palette, then use this flag to pass it. Do not append the nameSpace onto the palette name. |
| -palette | The name of the palette to be rendered. This name must agree with the name in the .xgen file passed using the -file flag. |
| -description | The name of the description within the named palette that is to be rendered. |
| -patch | The name of the patch (geometry) belonging to the description and palette that is to be rendered. |
| -frame | Sets the frame the palette should use as the base palette's frame. This will be adjusted by the -motionSamplesLookup values, if given. |
| -motionSamplesLookup | A list of motion sample offset values for loading geometry. These values are added to the value passed via -frame to give the frame value for each motion sample. This is not the value put into the motion block, however. That is specified via the -motionSamplesPlacement flag. Having these two decoupled allows control over the motion blur effects. |
| -motionSamplesPlacement | A list of motion block values. These are used directly as values in the RenderMan motion block calls. Usually, this value aligns with the spacing specified via -motionSamplesLookup, but it is not mandatory if a motion blur effect is desired (such as strobing). |
| -file | The palette .xgen file for this particular palette/description/patch. This is read once and cached for a specific element (nameSpace). |
| -delta | A space-separated list of delta files that should be applied to the given palette file. They are applied to the palette in the order in which they are found. |
| -geom | The geometry cache file for the palette. This can have more geometry than the palette needs, and can hold other data as well. XGen ignores what it does not use. What is required is data for the sample frames, static topology, and Pref for all geometry to which XGen is bound. For best performance, the geometry should be in object space. |
| -fps | Sets the frame rate for the palette. |
| -world | Sets the world transform matrix applied to the palette. |
| -interpolation | Sets the interpolation method for geometry cache data. Use this if the requested frame is not in the cache file. Supported interpolation methods are:
|
A collection of settings are required within the rib file. These are settings that are not suited for the xgen file, as it would make the file specific to a frame, camera, or render phase (color versus shadow). It is often useful to bake out a rib that contains elements such as wind cycles, and then instance that rib throughout a scene. These RenderMan settings allow this to be done while each element still renders as if it were rendered in that position (that is, face camera, culling, level of detail all still work).
# directory for writing temp files Option "user" "string irCacheDir" ["/disk1/tmp/renderPipeTemp12766"] # the current render phase Option "user" "uniform string phase" ["Shadow"] Option "user" "uniform string generator" ["key_dir"] # the 'current camera/generator' (once in rib) Attribute "user" "string irCurrentCam" ["true, -0.633307, -0.591462, -0.499094"] Attribute "user" "string irCurrentCamFOV" ["90, 90"] Attribute "user" "string irCurrentCamXform" ["0.773158, 0.0338928, 0.633307, 0, -0.511791, 0.623091, 0.591462, 0, -0.374562, -0.781414, 0.499094, 0, 0, 0, 0, 1"] Attribute "user" "string irCurrentCamRatio" ["1"] # tell xgen the 'render camera' (once in rib) Attribute "user" "string irRenderCam" ["false, 5.33365, 7.04902, 14.19"] Attribute "user" "string irRenderCamFOV" ["54.4321, 54.4321"] Attribute "user" "string irRenderCamXform" ["0.93606, -0.148352, 0.319037, 0, 0, 0.906762, 0.421643, 0, -0.351842, -0.394683, 0.848783, 0, 0, 0, -16.718, 1"] Attribute "user" "string irRenderCamRatio" ["1.94445"]
The irCacheDir is used for writing out dra files when using the DRA render method. There is an assumption that when rendering the shadow passes, the directory is one level deeper than when rendering the color passes. The phase indicates the type of render: Color or Shadow. The assumption is that all shadow renders occur before the color render. If the phase is Shadow, then the name of the shadow generator is given with the generator option.
The next two sets of values represent the cameras being used. The first is the irCurrentCam, and represents the current camera or shadow generator. The example shown is a shadow render, and so the current camera is a shadow generator (that is, a light). The first value is a bool indicating if the camera is orthographic, and the next three values are the position (if the camera is perspective); or, the direction (if orthographic). The irCurrenCamFOV is the field of view for the camera (values for orthographic are 90,90; as shown). irCurrentCamXform is the inverse camera transform. Finally, irCurrentCamRatio is the ratio for the camera at 2k and is used for stochastic level of detail. This final attribute is computed as 2.0*focalLength/25.4044/horizontalFilmAperture.
The next set of values is irRenderCam, and they represent the camera for the color pass. If possible, both sets of values should be provided for all renders. If you are unable to produce both sets, and can only provide the values for the current camera, then pass those values into both sets of attributes.
There are a few config variables available for controlling the renderer as well. Some of these are specific to the DSO, and some are general, but since they all affect the process, they are included here as reference. When these variables are set, they override any flag value given above.
This flips the parametrization of the Spline primitive so that it is 1 at the base and 0 at the top.