Attributes

RiColor ( RtColor color )

Set the current color to color. Normally there are three components in the color (red, green, and blue), but this may be changed with the colorsamples request.

RIB BINDING

Color c0 c1... cn
Color [c0 c1... cn]

EXAMPLE

RtColor blue = { .2, .3, .9};
RiColor(blue);

Color [.2 .3 .9]

SEE ALSO

RiOpacity, RiColorSamples

RiOpacity ( RtColor color )

Set the current opacity to color. The color component values must be in the range [0,1]. Normally there are three components in the color (red, green, and blue), but this may be changed with RiColorSamples. If the opacity is 1, the object is completely opaque; if the opacity is 0, the object is completely transparent.

RIB BINDING

Opacity c0 c1... cn
Opacity [c0 c1... cn]

EXAMPLE

Opacity .5 1 1

SEE ALSO

RiColorSamples, RiColor

RiTextureCoordinates (RtFloat s1, tFloat t1, tFloat s2, tFloat t2,
                        tFloat s3, tFloat t3, tFloat s4, tFloat t4 )

Set the current set of texture coordinates to the values passed as arguments according to the above table.

RIB BINDING

TextureCoordinates s1 t1 s2 t2 s3 t3 s4 t4
TextureCoordinates [s1 t1 s2 t2 s3 t3 s4 t4]

EXAMPLE

RiTextureCoordinates (0.0,0.0,  2.0,-0.5, -0.5,1.75,  3.0,3.0);

SEE ALSO

texture() and bump() in the Shading Language

RtLightHandle RiLightSource (RtToken shadername, ...parameterlist... )

shadername is the name of a light source shader. This procedure creates a non-area light, turns it on, and adds it to the current light source list. An RtLightHandle value is returned that can be used to turn the light off or on again.

RIB BINDING

LightSource name handle ...parameterlist...

The handle is a unique light identification number or string that is provided by the RIB client to the RIB server. Both client and server maintain independent mappings between the handle and their corresponding RtLightHandles. When specified as a number it must be in the range 0 to 65535.

EXAMPLE

LightSource "spotlight" 2 "coneangle" [5]
LightSource "ambientlight" 3 "lightcolor" [.5 0 0] "intensity" [.6]
LightSource "blacklight" "a-unique-string-handle" "lightcolor" [.5 0 0] "intensity" [.6]

In order to override the string handle selected, RiLightSource recognizes the special string __handleid parameter, which may be passed in via the parameter list. The value of this parameter will be used to override the handleid that appears in the RIB binding, e.g.:

RtString id = "mylight";
RiLightSource("spotlight", "__handleid", &id);

Integer sequence numbers are supported and are equivalent to their string representations. Thus, the following RIB statements are equivalent:

LightSource 57 "spotlight"
LightSource "57" "spotlight"

SEE ALSO

RiAreaLightSource, RiIlluminate, RiFrameEnd, RiWorldEnd

RtLightHandle RiAreaLightSource ( RtToken shadername, ...parameterlist... )

shadername is the name of a light source shader. This procedure creates an area light and makes it the current area light source. Each subsequent geometric primitive is added to the list of surfaces that define the area light. RiAttributeEnd ends the assembly of the area light source.

The light is also turned on and added to the current light source list. An RtLightHandle value is returned which can be used to turn the light off or on again.

If the Area Light Source capability is not supported by a particular implementation, this subroutine is equivalent to RiLightSource.

RIB BINDING

AreaLightSource name handle parameterlist

The handle is a unique light identification number or string that is provided by the RIB client to the RIB server. Both client and server maintain independent mappings between the handle and their corresponding RtLightHandles. When specified as a number it must be in the range 0 to 65535.

EXAMPLE

RtFloat decay = .5, intensity = .6;
RtColor color = {.5,0,0};

RiAreaLightSource ( "finite", "decayexponent", (RtPointer)&decay, RI_NULL);
RiAreaLightSource ("ambientlight", "lightcolor", (RtPointer) color, "intensity",
                    (RtPointer)&intensity, RI_NULL);

SEE ALSO

RiFrameEnd, RiLightSource, RiIlluminate, RiWorldEnd

RiIlluminate ( RtLightHandle light, RtBoolean onoff )

If onoff is RI_TRUE and the light source referred to by the RtLightHandle is not currently in the current light source list, add it to the list. If onoff is RI_FALSE and the light source referred to by the RtLightHandle is currently in the current light source list, remove it from the list. Note that popping the graphics state restores the onoff value of all lights to their previous values.

RIB BINDING

Illuminate handle onoff

The handle is the integer or string light handle defined in a LightSource or AreaLightSource request.

EXAMPLE

LightSource "main" 3
Illuminate 3 0

SEE ALSO

RiAttributeEnd, RiAreaLightSource, RiLightSource

RiSurface ( RtToken shadername, ...parameterlist... )

shadername is the name of a surface shader. This procedure sets the current surface shader to be shadername. If the surface shader shadername is not defined, some implementation-dependent default surface shader (but not "null") is used.

RIB BINDING

Surface shadername parameterlist

EXAMPLE

RtFloat rough = 0.3, kd = 1.0;

RiSurface ("wood", "roughness",(RtPointer)&rough, "Kd", (RtPointer)&kd,
     RI_NULL);

SEE ALSO

RiAtmosphere, RiDisplacement

RiDisplacement ( RtToken shadername, ...parameterlist... )

Set the current displacement shader to the named shader. shadername is the name of a displacement shader.

If a particular implementation does not support the Displacements capability, displacement shaders can only change the normal vectors to generate bump mapping, and the surface geometry itself is not modified (see Displacement Shaders).

RIB BINDING

Displacement shadername ...parameterlist...

EXAMPLE

RiDisplacement ("displaceit", RI NULL);

SEE ALSO

RiSurface

RtString c[1] = "world";
RtFloat d = 3.5;
RiAttribute("displacementbound", "coordinatesystem", (RtPointer)c,
               "sphere", (RtPointer)&d, RI_NULL);

Attribute "displacementbound"
        "sphere" [2]
        "coordinatesystem" ["world"]

dispmag = sphereradius * ntransform("world", Nf);

Attribute "displacementbound"
        "sphere" [2]
        "transform" [...mx...]

dispmag = sphereradius * ntransform(mx, Nf);

RiShader ( RtToken shadername, RtToken handlename, ...parameterlist... )

shadername is the name of a shader definition. The handlename is used as a key when calling this co-shader from another shader.

RIB BINDING

Shader shadername handlename parameterlist

EXAMPLE

RtFloat Ks = 0.0;

RiShader ("rust", "rustlayer", "Ks", (RtPointer)&Ks, RI_NULL);

SEE ALSO

RiSurface, RiLightSource

RiAtmosphere ( RtToken shadername, ...parameterlist... )

This procedure sets the current atmosphere shader. shadername is the name of an atmosphere shader. If shadername is RI_NULL, no atmosphere shader is used.

RIB BINDING

Atmosphere shadername parameterlist

EXAMPLE

Atmosphere "fog"

SEE ALSO

RiDisplacement, RiSurface

RiInterior ( RtToken shadername, ...parameterlist... );

This procedure sets the current interior volume shader. shadername is the name of a volume or atmosphere shader. If shadername is RI_NULL, the surface will not have an interior shader.

RIB BINDING

Interior shadername parameterlist

EXAMPLE

Interior "water"

SEE ALSO

RiExterior, RiAtmosphere

RiExterior ( RtToken shadername, ...parameterlist... );

This procedure sets the current exterior volume shader. shadername is the name of a volume or atmosphere shader. If shadername is RI_NULL, the surface will not have an exterior shader.

RIB BINDING

Exterior shadername parameterlist

EXAMPLE

RiExterior ( "fog," RI_NULL );

SEE ALSO

RiInterior, RiAtmosphere

RiVPSurface ( RtToken shadername, ...parameterlist... )

This procedure sets the current visible point surface shader. shadername is the name of a surface shader. If shadername is RI_NULL, no visible point surface shader is used.

RIB BINDING

VPSurface shadername parameterlist

EXAMPLE

VPSurface "constant"

SEE ALSO

RiVPInterior, RiVPAtmosphere

RiVPInterior ( RtToken shadername, ...parameterlist... );

This procedure sets the current visible point interior shader. shadername is the name of a volume or atmosphere shader. If shadername is RI_NULL, no visible point interior shader will be used.

Visible point interior shaders operate directly on the depth samples of the objects to which they are bound and the depth samples of other objects within their interior. This allows the computation of volumetric effects without the need for 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.

Visible point interior shaders allow effects such as 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.

RIB BINDING

VPInterior shadername parameterlist

EXAMPLE

VPInterior "water"

SEE ALSO

RiVPSurface, RiVPAtmosphere

RiVPAtmosphere ( RtToken shadername, ...parameterlist... );

This procedure sets the current exterior volume shader. shadername is the name of a volume or atmosphere shader. If shadername is RI_NULL, the surface will not have an exterior shader.

RIB BINDING

VPAtmosphere shadername parameterlist

EXAMPLE

VPAtmosphere "fog"

SEE ALSO

RiVPSurface, RiVPInterior

RiShadingRate ( RtFloat size )

Set the current shading rate to size. The current shading rate is specified as an area in pixels. A shading rate of RI_INFINITY specifies that shading need only be done once per polygon. A shading rate of 1 specifies that shading is done at least once per pixel. This second case is often referred to as Phong shading.

RIB BINDING

ShadingRate size

EXAMPLE

RiShadingRate (1.0);

SEE ALSO

RiGeometricApproximation

Attribute "shade" "shadingrate" [float]

The shading rate can also be set via an attribute. Attribute "shade" "shadingrate" can take either one float or two. The single float variant sets both the standard and the volume (depth) shading rate at once. The float[2] variant sets them independently. The default is 0.25.

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

RiShadingInterpolation ( RtToken type )

This function controls how values are interpolated between shading samples (usually across a polygon). If type is "constant" the color and opacity of all the pixels inside the polygon are the same. This is often referred to as flat or facetted shading. If type is "smooth" the color and opacity of all the pixels between shaded values are interpolated from the calculated values. This is often referred to as Gouraud shading.

RIB BINDING

ShadingInterpolation "constant"
ShadingInterpolation "smooth"

EXAMPLE

ShadingInterpolation "smooth"

RiMatte ( RtBoolean onoff )

Indicates whether subsequent primitives are matte objects.

RIB BINDING

Matte onoff

EXAMPLE

RiMatte (RI_TRUE);

SEE ALSO

RiSurface, RiDisplayChannel

Attribute "derivatives" "centered"    [1]
Attribute "derivatives" "extrapolate"    [1]

Derivatives and normals are calculated using a technique that eliminates or reduces several shading artifacts.

• Derivatives are symmetric with respect to the (u,v) parameterization. This eliminates the shading artifacts that would sometimes occur when adjacent patches in a subdivision surface had different orientations.
• Derivatives are more robust near degeneracies (such as sphere poles).
• Second derivatives are more accurate, which should reduce or eliminate grid artifacts when using reflection maps.

Attribute "derivatives" "centered"    [0]
Attribute "derivatives" "extrapolate"    [0]

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 when different objects have different values of these attributes, we pass the current max down the ray tree and calculate maxdiffusedepth = MIN(parent.maxdiffusedepth, parent.diffusedepth + object.maxdiffusedepth) - and similar for maxspeculardepth.

Attribute "trace" "int displacements" [0]

controls whether true displacements appear in ray-traced results. When 0 (off), 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. When 1, the surface will be displaced before ray-primitive intersection tests. New for PRMan 16.0: When 2, the surface will only be displaced when near the ray origin or when the ray differential is narrow.

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" "float importancethreshold" [0.001]

rays with importance below this value aren't traced.

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.

Attribute "trace" "int decimationrate" [1]

similar to the decimationrate option, the attribute specifies the tessellation decimation for ray tracing. With values 2 or higher, the surface tessellation used for ray tracing will be coarser than the surface tessellation ("dicing") used for Reyes rendering of directly visible surfaces. This means faster ray-surface hit tests. The number of grids in the fine geometry cache will decrease with higher values of decimationrate (since each grid is smaller), leading to better cache performance in complex scenes. The most useful values are 1, 2, 4, and 16. The default value of the attribute is the corresponding option value, which defaults to 1 (i.e. no decimation). If both the option and attribute are set, the attribute value is used. The attribute value must be at least as high as the option value. (When the decimationrate option is set, we change the relative sizes of the three tessellation caches; with the decimationrate attribute this isn't possible.)

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.

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" [""]

specifies a simplified shading model to employ when tracing photons. Valid strings are glass, water, chrome, matte, transparent, refractive:ior=... (wherein the index of refraction can be set to any number greater than or equal to 1), dielectric, pointcloud:..., brickmap:..., or absorbing. "" means matte (the default).

Attribute "photon" "int maxdiffusedepth" [-1] "int maxspeculardepth" [-1]

these attributes limit the number of bounces (diffuse or specular) for photons - similar to the corresponding "trace" attributes. Their default values are -1, which means use the corresponding "trace" values (which have default values of 2 and 1, respectively).

Attribute "photon" "int minstoredepth" [0]

this attribute gives the possibility of e.g. not storing photons directly from the light source - necessary if we want to compute direct illumination by other means (usually ray tracing) and not double-count direct illumination.

Attribute "shade" "string strategy" ["grids"]

Using the long-standing, default, "grids" strategy, all shaders attached to an object are executed as soon as it becomes shadeable. The "vpvolumes" strategy requests that atmosphere and interior shaders be run as visible point volume shaders. This has been deprecated in favor of the RiVPInterior and RiVPAtmosphere procedures, which designate a visible point shader without the need to set any additional attribute state.

Attribute "shade" "string volumeintersectionstrategy" ["exclusive"]

The volumeintersectionstrategy attribute allows regions with overlapping Interior or VPInterior shaders to combine their effects. It can be set to "exclusive", meaning that only one Interior or VPInterior will run on the region of overlap, or "additive", which composites the results of multiple Interior or VPInterior shaders on the region.

Attribute "shade" "float volumeintersectionpriority" [0.0]

The volumeintersectionpriority controls the order in which overlapping interiors are compbined, and also whether the "exclusive" or "additive" volumeintersectionstrategy applies when both are present in the same region. When using volumeintersectionstrategy "additive", the vpvolumeintersections option sets the maximum number of overlapping interiors.

Attribute "shade" "string diffusehitmode" ["primitive"]
                  "string diffusehitcache" [""]
                  "string diffusehitcolorchannel" [""]
                  "string diffusehitopacitychannel" [""]
                  "string specularhitmode" ["shader"]
                  "string transmissionhitmode" ["shader"]
                  "string transmissionhitcache" [""]
                  "string camerahitmode" ["shader"]

Possible values: "primitive", "cache" 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()
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 Cs and Os vertex variables (or Color and Opacity attributes) associated with the hit object will be used as the color and opacity of the hit point, without further shading computation. When the mode is "cache", the color and opacity will be found by lookup in a point cloud or brick map. (The point cloud or brick map file name is specified with Attribute "shade" "string diffusehitcache" "file:..." and similar for the other hitmodes, and the channels in the file are specified with Attribute "shade" "string diffusehitcolorchannel" "..." and Attribute "shade" "string diffusehitopacitychannel" "...".) These optimizations 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.

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. RiGeometricApproximation specifies an attribute and as such, motionfactor should be scoped within the current RiAttributeBegin-RiAttributeEnd block.

RiGeometricApproximation ( "focusfactor", ( RtFloat ) 1.0);

If focusfactor is not set (the default value is -1), then the motionfactor value, if set, continues to affect the adjustment of dicing rate for both motion blur and depth blur. If focusfactor is set (to a value greater than or equal to 0), then the motionfactor value only affects the motion blur adjustment, and focusfactor only affects the depth blur adjustment. A value of 0.0 will cause the renderer to use the default shading rate; values greater than 1.0 will cause objects to have their effective shading increased.

Attribute "shade" "string frequency" ["motionsegment"]

Attribute "shade" "frequency" sets the frequency of shading execution for multi-segment motion blurred geometry. The default frequency is "motionsegment": the shader is executed at the beginning of every motion segment. In this mode, the primitive variables bound to the shader are sourced directly from each segment.

When the frequency is set to "frame", the shader is executed only once for the frame. In this mode, the primvars bound to the shader are sourced only from the first motion segment; all other primvars are ignored. Note that the dPdtime variable in the shading language remains a scalar vector, not an array. Hence, the renderer will compute a dPdtime that takes into account only the first and last motion samples. If a displacement shader chooses to output dPdtime, it will not have an affect on the interior motion samples, and they will be linearly interpolated to match the specified motion.

"Frame" frequency can lead to more efficient rendering due to reduced shading and reduced memory overhead, but may be inappropriate for situations where primitive variables are themselves motion blurred, or shading scenarios which demand a higher frequency of shading for accuracy. Also, in some cases of extreme motion blur, objects with "frame" frequency may be less efficient to bound, leading to higher hiding costs.

Attribute "shadegroups" "string attributecombining" ["strict|permissive"]

When a shader uses the attribute() shadeop, Attribute "shadegroups" "attributecombining" allows the user to relax the rule governing whether or not two grids can be combined and shaded together. For instance, if the grids have different values for an attribute that is queried in a shader and assigned to a uniform value, the grids cannot be combined and shaded in a single group because the attribute() shadeop would not be able to return a single valuethat is correct for all points being shaded.

A subset of the available attributes are considered critical and must be the same if queried to avoid rendering artifacts. If one of these is queried the renderer checks the attribute's value agrees in all grids grouped together. Any grid that differs is excluded from a shading group. (See the Tuning Scenes for Combined Shading application note). For all other attributes, the renderer assumes the attributes differ and prevents combining. This is the default strict behavior.

There are cases where the user knows attribute queries are harmless, for instance, if an attribute in the un-verified set is known to be the same for all the grass gprims in a scene. In this case, the renderer can be told to be permissive when analyzing attribute queries for the purposes of combining.

Attribute "shadegroups" "string objectspacecombining" ["true|false"]

When a shader uses the RxTransform() or RxTransformPoints() call from an RslPlugin, Attribute "shadegroups" "objectspacecombining" allows the user to prevent objects using these calls from combining. The is required because RxTransform() expects a single value for the matrix return result. If grids from different objects are combined with different object spaces then the return result from RxTransform() will be underspecified; it will just contain the transform for the first grid, but the others will be ignored. By setting this attribute to "false", those objects won't be combined and there will only be a single consistent object space for all combined grids.

RiBound ( RtBound bound )

This procedure sets the current bound to bound. The bounding box bound is specified in the current object coordinate system. Subsequent output primitives should all lie within this bounding box. This allows the efficient specification of a bounding box for a collection of output primitives.

RIB BINDING

Bound xmin xmax ymin ymax zmin zmax
Bound [xmin xmax ymin ymax zmin zmax]

EXAMPLE

Bound [0 0.5 0 0.5 0.9 1]

SEE ALSO

RiDetail

RiDetail( bound );
RiDetailRange( 0., 0., 10., 20. );
    RiObjectInstance( foo1 );
RiDetailRange( 10., 20., RI_INFINITY, RI_INFINITY );
    RiObjectInstance( foo2 );

RiDetail ( RtBound bound )

Set the current bound to bound. The bounding box bound is specified in the current coordinate system. The current detail is set to the area of this bounding box as projected into the raster coordinate system, times the relative detail. Before computing the raster area, the bounding box is clipped to the near clipping plane but not to the edges of the display or the far clipping plane. The raster area outside the field of view is computed so that if the camera zooms in on an object the detail will increase smoothly. Detail is expressed in raster coordinates so that increasing the resolution of the output image will increase the detail.

RIB BINDING

Detail minx maxx miny maxy minz maxz
Detail [minx maxx miny maxy minz maxz]

EXAMPLE

RtBound box = { 10.0, 20.0, 42.0, 69.0, 0.0, 1.0 };

RiDetail (box);

SEE ALSO

RiBound, RiDetailRange, RiRelativeDetail

RiDetailRange ( RtFloat minvisible, RtFloat lowertransition,
                RtFloat uppertransition, RtFloat maxvisible )

Set the current detail range. Primitives are never drawn if the current detail is less than minvisible or greater than maxvisible. Primitives are always drawn if the* current detail* is between lowertransition and uppertransition. All these numbers should be non-negative and satisfy the following ordering:

minvisible <=; lowertransition <=; uppertransition <=; maxvisible.

If the Detail capability is not supported by a particular implementation, all object representations which include RI_INFINITY in their detail ranges are rendered.

RIB BINDING

DetailRange minvisible lowertransition uppertransition maxvisible
DetailRange [minvisible lowertransition uppertransition maxvisible]

EXAMPLE

DetailRange [0 0 10 20]

SEE ALSO

RiDetail, RiRelativeDetail

RiGeometricApproximation ( RtToken type, RtFloat value )

The predefined geometric approximation is "flatness." Flatness is expressed as a distance from the true surface to the approximated surface in pixels. Flatness is sometimes called chordal deviation.

RIB BINDING

GeometricApproximation "flatness" value
GeometricApproximation type value

EXAMPLE

GeometricApproximation "flatness" 2.5

SEE ALSO

RiShadingRate

RiOrientation ( RtToken orientation )

This procedure sets the current orientation to be either "outside" (to match the current coordinate system), "inside" (to be the inverse of the current coordinate system), "lh" (for explicit left-handed orientation) or "rh" (for explicit right-handed orientation).

RIB BINDING

Orientation orientation

EXAMPLE

Orientation "lh"

SEE ALSO

RiReverseOrientation

RiReverseOrientation ()

Causes the current orientation to be toggled. If the orientation was right-handed it is now left-handed, and vice versa.

RIB BINDING

ReverseOrientation -

EXAMPLE

RiReverseOrientation ();

SEE ALSO

RiOrientation

RiSides ( RtInt sides )

If sides is 2, subsequent surfaces are considered two-sided and both the inside and the outside of the surface will be visible. If sides is 1, subsequent surfaces are considered one-sided and only the outside of the surface will be visible.

RIB BINDING

Sides sides

EXAMPLE

Sides 1

SEE ALSO

RiOrientation

Attribute "sides" "backfacetolerance" [0]

The renderer 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. Backface culling is guaranteed to occur and to be exact; no transparency artifacts as described above will occur; the threshhold for backface culling of one-sided primitives prior to shading can be adjusted with the sides:backfacetolerance attribute. The backface culling tolerance angle is a floating-point number, measured in degrees, that 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.

Attribute "sides" "int doubleshaded" [0]

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.

Attribute "identifier" "string name" [s]

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>.

Attribute "trimcurve" "string sense" [s]

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

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" [1]

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 that 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".

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:

• "name"
• list,of,names" or "list of names"
• +additional,names"
• -without,names"

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.

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

PRMan supports two 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.

Attribute "stitch" "int enable" [1]

prevents cracks within single primitives, even when large displacements are used. This feature has been implemented for all surface types except polygons and implicits.

Attribute "stitch" "int traceenable" [1]

applies crack elimination to ray-traced primitives. Because there is a certain amount of memory cost associated with this feature, it is controlled by this separate attribute, which is not turned on by default.

SEE ALSO

Binary Dicing

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 "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.

Attribute "stochastic" "int sigma" [0]

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.

Attribute "stochastic" "int pointfalloff" [0]

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 "pointfalloffpower" option to the "stochastic" hider.

Attribute "procedural" "string 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 ray tracing, 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" ] [ ]

Translate 0 0 5
Procedural "DelayedReadArchive" ["archive.rib"] [0 1 0 1 0 1]

Resource "mystate" "attributes" "string operation" "save"
Translate 0 0 5
Attribute "procedural" "string attributes" "mystate"
Procedural "DelayedReadArchive" ["archive.rib"] [0 1 0 1 5 6]

Attribute "procedural" "int reentrant" [1]

Prior to PRMan 15, all procedural primitive geometry was run serially and could not be run simultaneously in multiple threads. Attribute "procedural" "int reentrant" [1] will cause any subsequent procedural to not lock the global mutex. Note that this requires that the procedural be thread safe. The default value of this attribute is 0, i.e. all procedurals remain locked. The default value can be overridden by a rendermn.ini flag: /prman/procedural/reentrant can be set to true or false, and this value will dictate the default value of Attribute "procedural" "reentrant" if not otherwise set.

Note that multiple invocations of the same RunProgram will still spawn only a single RunProgram. As RunPrograms are generally written to respond to ordered input, this means that simultaneous execution of the same RunProgram by multiple threads will still incur a lock: a thread will lock before writing to the pipe, and will release the lock after reading from the pipe.

Attribute "procedural" "int unloadable" [1]

The "procedural" "int unloadable" attribute is used by any subsequent procedural primitive in conjunction with the procedural memory limit option. By default, the renderer assumes that all procedurals can be unloaded from memory. If a procedural must remain persistent, setting the value of the unloadable attribute to 0 will prevent the renderer from unloading the procedural even if the procedural memory limit has been reached.