Attributes

Binary Dicing

Displacement Bounds

Named Primitives

Trim Curve Sense

Motion Factor

One-sided Primitives

Centered Derivatives and Normals

Internal Crack Elimination

Nonraster Oriented Dicing

User Specified Attributes

Extrapolated Derivatives
Visibility
Grouping

Trace

Irradiance

Photon

Accelerated Curves for Hair

Subdivision Stitch Groups

Double-sided Shading

Shading Hit-Mode

Shading Strategy

Shading Rate

Dicing Strategy

Sigma Hiding

Point Falloff

Procedural Attributes


Attributes are flags and values that are part of the graphics state, and are therefore associated with individual primitives. The values of these attributes are pushed and popped with the graphics state.

The PRMan Quick Reference includes a table that summarizes the attributes available in PhotoRealistic RenderMan. Note that some of the defaults listed can be overridden by configuration files (see Section 2.8).

Binary Dicing

This is a flag that indicates whether the lowest level patches must be diced into a grid of micropolygons with power-of-two dimensions. This attribute is typically used to prevent patch cracking on high-curvature patches.

	RtInt flag = 1;
	RiAttribute("dice", "binary", (RtPointer)&flag, RI_NULL);

Displacement Bounds

This is a control that increases the sizes of calculated bounding boxes on primitives in order to account for the effects of displacement mapping. The size is specified by identifying a single floating-point value which is the radius of a sphere which is guaranteed to contain the maximum possible displacement, and the name of the coordinate system in which this sphere resides. This value should be as tight as possible. It is extremely inefficient, both in terms of memory usage and calculation time, to specify a bounding sphere which is larger than the actual displacement. Therefore, this sphere should be as small as possible without permitting points on the object to displace farther than the sphere's radius.

The coordinate system identified can be:

The default coordinate system is "object" space.
	RtString c[1] = "world";
	RtFloat d = 3.5;
	RiAttribute("displacementbound", "coordinatesystem", (RtPointer)c,
                                 "sphere", (RtPointer)&d, RI_NULL);

In version 3.8, the coordinate system may be specified by supplying a transformation matrix. The parameterlist name for this version of the call is "transform", and the value is a single transformation matrix. The semantics of this transformation matrix is parallel to passing a transformation matrix to a shader and transforming a point through it. In other words,

	Attribute "displacementbound"
		"sphere" [2]
		"coordinatesystem" ["world"]
is to
	dispmag = sphereradius * ntransform("world", Nf);
as
	Attribute "displacementbound"
		"sphere" [2]
		"transform" [...mx...]
is to
	dispmag = sphereradius * ntransform(mx, Nf);

Named Primitives

It is occasionally useful to give names to individual primitives. For example, when a primitive has incorrect motion blur parameters it can be desirable to know which primitive is causing the problem. This can be done using the attribute identifier with the parameter name, as in:

	RtString name[1] = { "Gigi" };
	RiAttribute("identifier", "name", (RtPointer)name, RI_NULL);
	

All defined primitives will have this name until the graphics stack is popped (with RiAttributeEnd) or another such RiAttribute call is made. The error message would then contain a reference to a specific primitive name instead of the mysterious <unnamed>.

Trim Curve Sense

The sense of Trim Curves can now be reversed using an attribute. The sense can be set to either inside or outside. The default is inside. When the sense is set to outside, all portions of the surface inside the Trim Curve, those drawn in the default case, will not be drawn, and those portions outside the Trim Curve, those not drawn in the default case, will be drawn. Since Trim Curves are attributes themselves, this allows one to use a single Trim Curve to define areas of different shading on the same NURBS surface by repeating the patch with a different sense of the same Trim Curve. The following example shows how to set the Trim Curve sense in a C program.

	RtString sense[1] = "outside";
	RiAttribute("trimcurve", "sense", (RtPointer) sense, RI_NULL);
The Pixar Looks example program in the /usr/local/prman/examples directory uses this technique.

Motion Factor

A special geometric approximation type, motionfactor, is available with RiGeometricApproximation to provide a processing/quality tradeoff for motion blurred objects whose motion can be large in screen space. The following call:

       RiGeometricApproximation("motionfactor", (RtFloat) 1.0);
    
will cause the renderer to check the length of the motion blur on the screen for all motion blurred objects and if the distance is large, raise the effective shading rate value of the blurred objects. Since the objects will be blurred across the screen, fine shading detail would be lost anyway. This can save large amounts of processing if many objects in the scene have large blurs. A motionfactor factor value of 0.0 will turn this feature off. Values greater than 1.0 will cause motion blurred objects to have their effective shading rate raised even higher. According to the RenderMan Interface Version 3.2 Specification RiGeometricApproximation specifies an attribute and as such, motionfactor should be scoped within the current RiAttributeBegin-RiAttributeEnd block.

One-sided Primitives

Normally the renderer currently culls one-sided primitives that are backfacing. A primitive is considered backfacing if the primitive's surface normals all point more than 90 degrees away from the viewing vector. In PRMan version 3.7 and earlier, this culling was not guaranteed to occur. Primitives might not be culled even though they were truly backfacing, and no primitive was ever cut cleanly along the terminator. Thus, transparent one-sided objects may have shown inconsistent or ragged-edged results as parts, but not all, of the backfacing sections were culled. Moreover, there was a culling phase prior to shading that could have had the unexpected effect of culling backfacing geometry that a displacement shader would have subsequently moved into a front-facing orientation.

PRMan (subsequent to version 3.8) modifies these behaviors. First, backface culling is guaranteed to occur and to be exact; no transparency artifacts as described above will occur.

Second, the threshhold for backface culling of one-sided primitives prior to shading can be adjusted with the new sides:backfacetolerance attribute. The backface culling tolerance angle is a floating-point number, measured in degrees, which specifies the angle that the primitive must exceed, beyond the “silhouette normal”, before it may be culled prior to shading. The default value is 0 degrees. For example:

    Attribute "sides" "backfacetolerance" [20]
    
will cause the renderer to not cull backfacing objects until their surface normals point more than 110 degrees away from the viewing vector. Note that this does not affect the fact that by the end of the rendering pipeline, backface culling is exact and occurs at 90 degrees.

Centered Derivatives and Normals

Starting in PRMan 3.9, derivatives and normals are calculated using a new technique which will eliminate or reduce several shading artifacts.

The new technique will change surface normals slightly, and may give bumpy surfaces a softer appearance.

Note: These changes only take effect when smooth shading is enabled (via ShadingInterpolation "smooth"). When constant shading is used (the default setting), derivatives and normals are unchanged from previous releases. Smooth shading and centered derivatives are highly recommended in order to minimize rendering artifacts.

If desired, centered derivatives can be turned off as follows:

        Attribute "derivatives" "centered"    [0]
    

Internal Crack Elimination

Starting in PRMan 3.9, the renderer automatically prevents cracks within single primitives, even when large displacements are used. This feature has been implemented for all surface types except polygons and implicits. It is controlled by the following attribute (turned on by default):

        Attribute "stitch" "int enable" [1]    

Starting in PRMan 13.0, the renderer will also apply crack elimination to raytraced primitives. Because there is a certain amount of memory cost associated with this feature, it is controlled by a separate attribute, which is not turned on by default:

        Attribute "stitch" "int traceenable" [1]    

Cracks may still occur between separate primitives (for example, between two adjacent bicubic patches). As in previous releases, such cracks may be reduced by turning on binary dicing:

	Attribute "dice" "int binary" [1]    

Nonraster Oriented Dicing

PRMan supports a mode of dicing that computes micropolygon sizes using an unoriented raster space metric rather than the standard screen aligned raster metric. This is useful in situations where it is important that the dicing rate on an object doesn't change due to camera orientation. For example, it can help in situations where objects which are viewed edge on result in large micropolygons (but small in screen space), which are then displaced leading to micropolygons which are large in screen space.

The default dicing criteria is the screen-oriented raster space. This can be turned off to use the new unoriented metric as follows:

      Attribute "dice" "rasterorient" [0]
    

User Specified Attributes

PRMan (subsequent to version 10.0) supports the use of arbitrarily defined token/value pairs for the user attribute. These token/value pairs may be arbitrarily defined and set, and then queried with the attribute shadeop or via the RxAttribute mechanism. Like other attributes, all token/value pairs associated with this attribute will be pushed and popped on the graphics stack with each RiAttributeBegin and RiAttributeEnd call.

        RtString myattribute = "foo";
        RiAttribute("user", "uniform string myattribute", (RtPointer)&myattribute, RI_NULL);

In RIB form:

        Attribute "user" "uniform string myattribute" [ "foo" ]
      

Extrapolated Derivatives

PRMan 3.9 introduced a new method for computing derivatives and normals at grid boundaries. Instead of replicating the values (and thus leading to second derivatives with value zero along the grid boundaries), the new scheme uses quadratic extrapolation to estimate new values. This is most useful on smooth surfaces, where it can virtually eliminate grid artifacts due to derivatives. On rough or bumpy surfaces, however, there is a chance that enabling this attribute may cause the grid artifacts to be worse.

Since PRMan 10.0, the quadratic extrapolation scheme is enabled by default. It may be disabled by specifying:

        Attribute "derivatives" "extrapolate"    [0]

Visibility

Attribute "visibility" "int camera" [1]
controls the visibility of subsequent primitives to the camera. By default all primitives are visible.
 
Attribute "visibility" "int diffuse" [0]
controls the visibility of the current primitive to diffuse rays. These are rays cast by gather, occlusion, and indirectdiffuse.
 
Attribute "visibility" "int specular" [0]
controls the visibility of the current primitive to specular rays. These are rays cast by gather, trace, and environment.
 
Attribute "visibility" "int transmission" [0]
controls the visibility of primitives to transmission (shadow) rays. 
 
Attribute "visibility" "int photon" [0]
controls the visibility of the current primitive to photons. Since photon map generation is a separate rendering pass, this attribute is usually superfluous.  We support it to facilitate the use of the same RIB archive in both photon generation and final rendering passes.
 
Attribute "visibility" "int midpoint" [0]
controls the visibility of the current primitive to the midpoint depth filter. Options which have midpoint visibility but no camera visibility are considered visible when the midpoint depthfilter is active, and take part in the two surface hider computation, but only as the second surface. Such objects can be considered "shadow receivers", but will not be "shadow casters".
Note that a separate shading hit-mode attribute controls whether full shading is done when rendering objects in different visibility contexts.

Grouping

Attribute "grouping" "string membership" ["name_spec"]
controls the group membership of subsequent primitives.  A single primitive can be a member of several groups. Membership is used to precisely control trace relationships between objects.  Ray-tracing shaders on one object can limit their ray intersections to members of specific groups by using the optional "subset" parameter of the tracing operators.  The name_spec supports relative and absolute specification: In addition, starting with PRMan 13.5, the special value "*" may be specified for name_spec. Primitives with this membership will be hit-testable by any ray, no matter what the subset of that ray, or even if the ray doesn't specify a subset.

Trace

Attribute "trace" "int maxdiffusedepth" [1] "int maxspeculardepth" [2]
these attributes limit the number of bounces (diffuse or specular) for indirect illuminance relative to the associated primitive.  To resolve the interaction between per-primitive values, we pass the current max down the ray tree and apply MIN(ray.depthMax, primitive.depthMax + ray.depth). The maxdiffusedepth option is used to limit the number of diffuse and specular bounces of photons in the photon tracing pass, while maxspeculardepth controls the number of reflection and refraction bounces.
 
Attribute "trace" "int displacements" [0]
controls whether true displacements appear in ray traced results.  When false, the displacement will be disregarded for the purposes of ray-primitive intersection tests, but shading will take the displacements into account effectively resulting in a bump mapped appearance.
 
Attribute "trace" "bias" [.01]
this bias value affects transmission/shadow rays as well as trace/environment rays. It is an offset applied to the ray origin, moving it slightly away from the surface launch point in the ray direction. This offset can prevent blotchy artifacts resulting from the ray immediately finding an intersection with the surface it just left.
 
Attribute "trace" "int samplemotion" [0]
controls whether motion blurred objects appear in ray traced results.  When 0, the motion blur of other objects hit by rays launched from the object with this attribute will be ignored.  When non-zero, motion blur will be taken into account by rays launched from an object with this attribute.
 

Irradiance

Attribute "irradiance" "float maxerror" [0.5]
an error metric to control quality/speed tradeoff for irradiance calculations. If set to zero, the irradiance will be computed at every shading point; no attempt at interpolation will be done. The larger 'maxerror' is, the more time can be saved by interpolating nearby irradiance values.
 
Attribute "irradiance" "float maxpixeldist" [30]
an alternative backup metric to control quality/speed tradeoff for irradiance. If there are visible discontinuities in occlusion or irradiance, typically on curved objects far from other objects, it is often helpful to reduce 'maxpixeldist' to smaller values -- for example 10 or 15. This ensures that interpolation is only done over shorter distances.

Photon

Attribute "photon" "int estimator" [50]
controls the number of photons to consider when estimating caustic effects.
 
Attribute "photon" "causticmap" [""]
specifies the caustic photonmap to store photons in during photon tracing; this attribute allows you to deposit photons into a per-primitive map. Also specifies which caustic photon map to use when a shader calls the caustic shade-op.
 
Attribute "photon" "globalmap" [""]
specifies the global photonmap to store photons in during photon tracing; this attribute allows you to deposit photons into a per-primitive map.
 
Attribute "photon" "string shadingmodel" ["matte"] (glass,water,chrome,matte,transparent,"")
specifies a simplified shading model to employ when tracing photons.  If empty, the shader will be analyzed to determine photon scattering.

Accelerated Curves for Hair

Attribute "dice" "hair" [1]

This Attribute specifically used for RiCurves geometry makes thin hair-like curves much cheaper to shade, and more memory efficient when dealing with long hair which spans multiple buckets. When it is enabled by setting to 1 (it is disabled by default), Du() of any quantity is 0, with the trivial exception of Du(u) = 1. In other words, derivatives across the width of the curve are ill defined. Because of this, this attribute should only be used for curves which are truly hair-like (very thin in screen space).

Subdivision Stitch Groups

Attribute "stitch" "newgroup" [1]

This Attribute is used in conjunction with subdivision mesh stitching, and is used to avoid stitch curve ID conflicts. When this Attribute appears in the RIB stream as above, it marks the beginning of a new stitch group, which lasts until the end of the enclosing attribute block, or the next "newgroup" attribute, whichever comes first. Tags defined within a given stitch group will not match tags defined anywhere else in the input stream, including those in nested stitch groups.

Double-sided Shading

When this Attribute is enabled, two-sided primitives will be shaded twice, once on each side. The surface normals will face in the standard direction on one pass, and in the inverted, or reversed-orientation, direction on the other pass (roughly speaking, towards the viewer once and away from the viewer once). This permits, for example, two-sided objects which are laminar sheets or ribbons to have different colors on each side, or to be displaced in both directions in order to give it a shader-generated thickness.

Culling

Attribute "cull" "backfacing"    [1]
Attribute "cull" "hidden"    [1]

As of version 11.5, PRMan supports two new attributes for culling. When the "cull" "backfacing" Attribute is turned off, surfaces are shaded even if they have Sides 1 and their back side is facing the camera. When the "cull" "hidden" Attribute is turned off, surfaces are shaded even if they are behind other surfaces. These attributes are convenient to force shading to happen, for example for baking ambient occlusion or indirect illumination. For regular rendering, these attributes should be left at their default value (1) so that surfaces that do not contribute to an image are culled before wasting time shading them.

Shading Strategy

Attribute "shade" "string strategy" ["grids"]
    "string volumeintersectionstrategy" ["exclusive"]
    "float volumeintersectionpriority" [0.0]

Using the long-standing, default, "grids" strategy, all shaders attached to an object are executed as soon as it becomes shadeable. Starting with PRMan 12.0, when Attribute "shade" "strategy" ["vpvolumes"] is attached to a primitive, its associated Atmosphere and Interior shaders are instead executed only after all of the final depth samples ("visible points") for that object, and others, have been determined. This "post-visibility computation" volume shading of camera samples allows Interior shaders to execute on these depth samples directly, without requiring ray-tracing or analytic techniques to determine the "back side" of an object. However, ray-traced Interior volumes are still valuable for combining volumetric and refractive effects.  In some cases, the "vpvolumes" strategy can also be used to compensate for motion blur and depth of field "dragging" of volume samples seen by the camera.

Using the "vpvolumes" strategy usually increases the number of points at which volumes are executed (it is a function of PixelSamples, rather than ShadingRate). However, there are some cases where it may actually reduce the number of volume shading points, such as when a very complex object is very small on screen. It will also not run Atmosphere shaders on parts of objects which are completely hidden.

Interior shaders allow effects such as the smoke inside a closed object to be described by a volume shader which is independent of the object's surface shader. The surface must be partially transparent for the interior to be exposed.

An additional new Attribute, "string shade" "volumeintersectionstrategy" ["additive" | "exclusive"], allows regions with overlapping Interior shaders to combine their effects. There is also a "float volumeintersectionpriority" which controls the combining order, and also which of "exclusive" or "additive" apply when both are present in the same region.

Shading Hit-Mode

Attribute "shade" "string diffusehitmode" ["primitive"]
    "string specularhitmode" ["shader"]
    "string transmissionhitmode" ["shader"]
    "string camerahitmode" ["shader"]

Possible values: "primitive" or "shader", the defaults are shown above.

The hitmode attributes provide limited control over whether or not shaders will actually execute at the attached object's shading points ("hits"). The renderer generates shading points for objects seen directly by the camera, and also at the points where rays from ray-tracing functions intersect objects. These attributes are typically used to control shading expense at ray hit points. Full shading is typically desirable in very coherent (specular) secondary reflections; if the same objects are also sampled by very diffuse rays, then expensive full shading may not be necessary in those contexts.

Currently, these attributes only affect rays shot due to these shading functions: occlusion, indirectdiffuse, transmission, and shadow. These functions also accept an explicit "hitmode" parameter which can override the hit object's attribute setting. Rays originating from trace and environment currently always cause shading to occur. The behavior of gather rays depends on modifiers supplied in the shader for each gathered variable.

When the mode is "primitive", then the Color and Opacity attributes associated with the hit object will be used as the the color and opacity of the hit point, without further shading computation. This optimization can reduce render time since potentially expensive shaders are not being run on the hit object. If the mode is "shader", then the shader attached to the hit primitive will be run to compute the color and opacity.

The "primitive" mode for "camerahitmode" is unique in that it does not actually disable shader execution on objects visible to the camera. Instead, shaders are always run on camera-visible objects, but the "primitive" setting causes them to always be considered opaque. So both the Opacity attribute attached to these objects, and their shader's output Oi, are ignored, and opacity is forced to be opaque, color(1,1,1). This simplification can reduce render time by causing shading to be skipped on all objects that fall behind the marked objects, since they are guaranteed to be completely hidden.

Note that a separate visibility attribute controls whether objects are actually visible to different sorts of rays, or the camera, at all.

Shading Rate

Attribute "shade" "relativeshadingrate" [float]
    "resetrelativeshadingrate" [float]

Attribute "shade" "relativeshadingrate" sets the value of the relative shading rate equal to the relativeshadingrate value times any other relativeshadingrate values in the Attribute stack.

Attribute "shade" "resetrelativeshadingrate" resets the relativeshadingrate to the given value.

The final ShadingRate used on an object will be the accumulated relativeshadingrate multiplied by the actual shadingrate.

Dicing Strategy and Dicing Camera

Attribute "dice" "string strategy" ["planarprojection"]
    "string referencecamera" ["worldcamera"]

PRMan 12.0 added support for specifying the camera and strategy to use during dicing. These are chosen via the "strategy" and "referencecamera" parameters of Attribute "dice". There are two types of strategies: "planarprojection" and "sphericalprojection". The "planarprojection" strategy has been used in all previous releases of PRMan: dicing rate is determined using the screen space coordinates of a primitive projected onto a plane. The "sphericalprojection" strategy uses the coordinates of a primitive projected onto a sphere. The parameters of the sphere are taken from the state of the standard camera. The radius is set to the distance to the near clipping plane, and the size of a pixel is set to match the current projection. Both strategies can utilize nonraster oriented dicing metrics.

Two reference cameras can be specified for dicing — the camera state at FrameBegin, "framecamera", and the state of the camera at WorldBegin, "worldcamera" or "camera". In order to guarantee that the frame and world cameras have unique world to eye transformations, Identity must be called after FrameBegin. To setup the frame camera as your dicing camera:

  Define dicing camera
  FrameBegin
  Identity
  Define viewing camera
  WorldBegin
  WorldEnd
  FrameEnd

There are some restrictions on the frame camera. Transformation motion blur is not supported, and the frame camera does not have its own dicing rate. There is one global dicing rate. To change the dicing rate on the frame camera, change its resolution.

Lastly, the choice of world vs frame camera is independent of the choice of projection vs spherical projection strategy.

Sigma Hiding

The "stochastic" "sigma" attribute has no effect unless the "sigma" option to RiHider has been enabled. If that is the case, setting this attribute to a value of 1 indicates that the geometry to follow should undergo sigma hiding. Please refer to the documentation for the Hider "sigma" option for more details.

Point Falloff

The "stochastic" "int pointfalloff" attribute, when set to 1, turns on a cosine based falloff for color and transparency on RiPoints (only valid with the "stochastic" hider). The points are fully opaque in the center and fall away to zero at the edge of the disks. The falloff can be shaped with the "stochastic" "pointfalloffpower" option to the "stochastic" hider.

Procedural Attributes

The "procedural" "string attributes" attribute is used by any subsequent procedural primitive. The value of the attribute is used as a look up for a saved resource, of type "attributes". If found, the saved attribute state will override the graphics state for the procedural primitive, without affecting the inherited graphics state of the contents of the procedural primitive. One use of this attribute is to control the visibility of a procedural, without interfering with the visibility of the procedural's contents, which normally would inherit the graphics state previously defined.

For example, suppose it is required for the contents of an archived RIB file to inherit no raytrace visibility (the contents of said RIB file may of course turn on raytracing visibility where it sees fits). One could simply do this:

Attribute "visibility" "int diffuse" [0] "int specular" [0] "int camera" [1]
ReadArchive "archive.rib"

This breaks when it comes to a Procedural DelayedReadArchive:

Attribute "visibility" "int diffuse" [0] "int specular" [0] "int camera" [1]
Procedural "DelayedReadArchive" [ "archive.rib" ] [ ]

In this situation, the procedural never gets cracked by raytracing, even if its contents actually have diffuse/specular 1. Here, we clearly have a disconnect between the desire to specify the visibility of a procedural, and the inherited default visibility of its contents. By using Attribute "procedural" "string attributes", the desired situation can be expressed as follows:

Attribute "visibility" "int diffuse" [1] "int specular" [1] "int camera" [1]
Resource "supervisibility" "attributes" "string operation" "save"
Attribute "procedural" "string attributes" "supervisibility"
Attribute "visibility" "int diffuse" [0] "int specular" [0] "int camera" [1]
Procedural "DelayedReadArchive" [ "archive.rib" ] [ ]


 

Pixar Animation Studios
(510) 752-3000 (voice)   (510) 752-3151 (fax)
Copyright © 1996- Pixar. All rights reserved.
RenderMan® is a registered trademark of Pixar.