5.2 Attributes
Attributes are components of the graphic state that are associated with elements of the scene, such as geometric primitives and light sources. As with options, there are two kinds of attributes: the standard and the implementation specific. Standard attributes, along with their default values, are listed in Table 5.4. Implementation specific attributes are passed through the RiAttribute command. All attributes are saved at RiAttributeBegin and restored at RiAttributeEnd. Attributes are also implicitely saved at each RiFrameBegin and RiWorldBegin and restored at the enclosing RiWorldEnd and RiFrameEnd.
|
3Delight has a set of implementation specific attributes which are summarized in Table 5.5 and further explained in the sections that follow.
|
5.2.1 Primitives Identification
Attribute "identifier" "name" ["primitive_name"]- Subsequent objects are named as specified by this attribute. This is useful when 3Delight reports warnings or errors about a primitive.
Attribute "grouping" "string membership" ["group_name"]- Specifies group membership of subsequent primitives. Beginning the group_name with "+" or "-" adds or removes subsequent primitives from the specified group_name. Specifying "" as the group_name resets any group memberships. More about grouping in Trace Group Membership and Display Subsets.
Attribute "grouping" "string tracesubset" ["subset_name"]- Sets the default group subset for primitives that are shooting a ray. This attribute sets the default value if ray tracing functions do not provide any value. More about grouping in Trace Group Membership.
5.2.2 Primitives Visibility and Ray Tracing
Attribute "visibility" "integer camera" [1]- Specifies if an object is visible to primary camera rays.
Attribute "visibility" "integer trace" [0]- Specifies if an object is visible to secondary rays traced in the scene. It affects rays traced by
environment(),trace(),gather()andindirectdiffuse(). This attribute is obsolete; "visibility" "diffuse" and "visibility" "specular" should be used instead. Attribute "visibility" "integer diffuse" [0]Attribute "visibility" "integer specular" [0]- Specifies if an object is visible to diffuse or specular rays. Diffuse rays are traced by
gather(),indirectdiffuse()andocclusion(). Specular rays are traced bygather(),trace()andenvironment(). Note that these attributes must be specified with inline declarations and take precedence over "visibility" "trace". The way objects are shaded when hit by a specular or diffuse ray is specified using "hitmode" attributes described in hitmode.IMPORTANT
gather(),indirectdiffuse()andocclusion()functions can trace both specular and diffuse rays depending on the specular threshold as explained in specularthreshold. Attribute "visibility" "string transmission" ["transparent"]- Specifies how an object appears to transmission-like rays. In particular, controls how a specific surface casts shadows on other surfaces. Possible values for this attribute are:
"transparent"- The object does not cast shadows on any other object since it is completely transparent.
"opaque"- The object casts a shadow as a completely opaque object.
"Os"- The object casts a shadow according to the opacity value given by
RiOpacityor by the Os variable attached to the geometry, if provided. "shader"- The object casts shadows according to the opacity value computed by the surface shader.
shadow(),transmission()andocclusion(). This attribute is obsolete; "visibility" "integer transmission" should be used instead. Attribute "visibility" "integer transmission" [0]- Specifies if an object is visible to transmission rays. See also hitmode. Transmission rays are those traced by
shadow()andtransmission(). Note that this attribute must be specified with an inline declaration and takes precedence over "visibility" "string transmission". Attribute "visibility" "integer photon" [0]- Specifies if an object is visible to photons.
Attribute "visibility" "string subsurface" ["groupname"]- Specifies that geometry is visible to "subsurface" rays. This means that affected primitives are included in subsurface scattering computations and that they belong to the specified subsurface groupname. Primitives that are in the same subsurface group are considered as forming one closed object. A special groupname of "*" must be specified for procedural geometry if its contents is visible to several different subsurface groups. More on subsurface scattering in Subsurface Scattering.
Attribute "shade" "string diffusehitmode" ["primitive"]Attribute "shade" "string specularhitmode" ["shader"]Attribute "shade" "string transmissionhitmode" ["shader"]- These attributes determine if the object's shader is run when it is hit by various types of rays. A value of `shader' runs the shader to compute Ci and Oi while `primitive' uses the object's Cs and Os attributes directly. The later is of course much faster.
Attribute "shade" "string photonhitmode" ["shader"]- Specifies the action to take when a photon hits a surface. The default action is to run the shader and use the resulting color and opacity in combination with the photon shading model as specifyed in photon shading model. Using `primitive' instead of `shader' will use object's Cs and Os quantities without any shading.
Attribute "shade" "string camerahitmode" ["shader"]- If this is set to `primitive' instead of `shader' the object is assumed to be opaque by the camera. This allows the renderer to compute visibility faster without running the surface shader.
Attribute "cull" "integer hidden" [1]- Specifies if primitives hidden by other primitives are culled or not. Specifying `0' to this attribute is only meaningful when "baking" a shader and could have a significant impact on performance if not used properly.
Attribute "cull" "integer backfacing" [1]- Specifies if primitives backfacing the camera are shaded or not if
RiSidesis set to `1'. Only meaningful when "baking" a shader. By default, cull primitives that are backfacing the camera. Attribute "hider" "integer composite" [1]- Enables or disables compositing of transparent surfaces together. Any object which has this attribute set to 0 will cause compositing to act is if all the objects behind it did not exist. This allows the object to be semi-transparent without other objects showing through, giving direct control over the alpha channel of the final image.
Attribute "trace" "float bias" [.01]- This bias affects all traced rays. The bias specifies an offset added to ray's starting point (in ray's direction) so as to avoid intersecting with the emitting surface.
Attribute "trace" "int samplemotion" [0]- By default rays are all launched at the object's shading time. However, rays traced from an object which has this attribute set, are spread over the object's visibility time span so they can see motion blur. This should not be turned on for objects which are moving because the ray's source position is unreliable, and may result in self-intersection with the launching surface.
Attribute "light" "string shadows" ["off"]- Turns automatic shadow calculation ["on"] or ["off"] for
RiLightSources specified after this directive. Attribute "light" "integer samples" [1]- Controls the oversampling of automatic shadows. Larger values improve shadow accuracy but slow down rendering.
Attribute "light" "string samplingstrategy" ["lightsource"]- Controls how 3Delight samples area lights. Two values are accepted:
"lightsource"- When this sampling strategy is selected (it is the default), 3Delight will run each area light as many times as there are area light samples and will average the result. Surface shaders will be provided with
L,ClandOlthat are the result of the averaging. This method will generally produce correct soft shadows (since in most cases light sources are responsable of shadow computation) but incorrect lighting(20). "illuminance"- This is the "physically correct" area light sampling that will run illuminance based shadeops (21) in all surface shaders as many times as there are area light samples so to ensure a proper BRDF sampling. This mode is recommended if:
- Accurate specular highlights are important.
- Shadows are generated from inside surface shaders (and not light shaders).
illumianceconstructs.
5.2.3 Global Illumination Attributes
Attribute "irradiance" "nsamples" [64]- Specifies the default number of samples to use when calling
occlusion()orindirectdiffuse()shadeops. This default value can be modified by passing a parameter to those shadeops. See section Oversampling and Derivatives. Attribute "irradiance" "shadingrate" [4]- 3Delight can use a different shading rate for irradiance computations to speed up
occlusion()andindirectdiffuse()computations. Using higher shading rates enables irradiance interpolation across shaded grids, and therefore speeds up rendering. Attribute "irradiance" "maxerror" [0.1]- Controls a maximum tolerable error when using interpolation (for an irradiance shading rate higher than 1). Parameter range is [0..1].
Attribute "photon" "color reflectance" [1 1 1]- This is a multiplier over the reflectance given by the surface shader (or the primitive color as specified by the shading model below). This can be used to exaggerate or to attenuate the color bleeding effect produced by a particular object.
Attribute "photon" "string shadingmodel" ["matte"]- Sets the shading model of the surface when interacting with a photon. Accepter shading models are `matte', `chrome', `water', `glass' and `transparent'.
Attribute "photon" "causticmap" [""]Attribute "photon" "globalmap" [""]- Specifies a caustic or a global photon map for the current surface. This value be retrieved from inside a shader using the
attribute()shadeop. See attribute shadeop. Attribute "photon" "int estimator" [50]- Specifies the total number of photons to use when estimating radiance or irradiance. This will be the default value when calling the
photonmap()shadeop. See photonmap shadeop.
5.2.4 Subsurface Light Transport
Attribute "subsurface" "color absorption" [absorption]Attribute "subsurface" "color scattering" [scattering]- Specifies reduced absorption and reduced scattering coefficients for the subsurface simulation. These two parameters should always be specified in pairs:
# marble reduced scattering + absorption parameters Attribute "subsurface" "color scattering" [2.19 2.62 3.00] "absorption" [0.0021 0.0041 0.0071]
Attribute "subsurface" "color meanfreepath"Attribute "subsurface" "color reflectance"- Another way to specify subsurface parameters, using translucency and reflectance (mean free path and diffuse reflectance). These two parameters should be specified in pair. If "reflectance" is not specified it is set to the
RiColorof the surface.# marble reduced meanfreepath + diffuse reflectance Attribute "subsurface" "meanfreepath" [8.50 5.566 3.951] "reflectance" [ 0.83 0.79 0.75]
Attribute "subsurface" "refractionindex"- This attribute specifies the third parameter of the subsurface simulation. It is a single float indicating the relative index of refraction of the simulated material (commonly referred to as n).
Attribute "subsurface" "scale" [1]- The values for subsurface scattering use a millimeter scale. Since most scenes are modeled on a different scale, this attribute compensates for that instead of adjusting the parameters themselves. It is a single float which defaults to 1.0.
Attribute "subsurface" "shadingrate" [1]- This attribute controls how many irradiance samples should be taken during the precomputation phase. It is a single float which defaults to 1.0 and has a meaning similar to
RiShadingRate. Attribute "subsurface" "referencecamera" ["cameraname"]- Specifies a dicing camera to use when evaluating the subsurface light transport. The camera must be declared with
RiCamerafirst as explained in Dicing Cameras.
More on subsurface scattering in Subsurface Scattering.
5.2.5 Displacement
Whenever a displacement shader is applied to a primitive, one must specify a displacement bound to inform the renderer about maximum displacement amplitude. This is done using one of the attributes described below.
Attribute "displacementbound" "float sphere" [radius] "string coordinatesystem" "ss-name"- This tells the renderer that a displaced point does not move outside a sphere of a given radius in the given coordinate system. The following coordinate systems are supported:
-
"surface"which is the surface shader's coordinate system. -
"displacement"which is the displacement shader's coordinate system. -
"shader"which means"displacement"if a displacement shader is attached to the object and"surface"if not. -
"current"which is the shading language "current" space. -
"null"which specifies the coordinate system active when the attribute call is made. - Any other named coordinate system which will be accessible to the object's shaders.
"object"space is used. Do not forget to specify a displacement bound when using displacement shaders. -
Attribute "displacementbound" "float sphere" [radius] "matrix transform" [matrix]- This is very similar to the previous attribute except that the coordinate system is specified using a matrix.
Attribute "bound" "float displacement" [radius]- This is provided for backward compatibility and specifies a sphere of a given radius living in the object's coordinate system.
Attribute "trace" "int displacements" [0]- If true (
[1]), objects are displaced prior to ray-primitive intersection tests. See Raytracing Displacements. Attribute "displacement" "int concatenate" [0]- When this is set to 1 and a displacement shader is instantiated, its effect will be concatenated to that of existing displacement shader(s) in the current attribute state. Any number of shaders can be linked together in this fashion. When the object is displaced, the innermost shaders (ie. the ones declared last) are run first.
Attribute "displacement" "string detail" ["default"]- This attribute controls how displacement shaders are run on geometric primitives. The default value causes them to be run at the finest possible detail level for smooth, accurate displacement. It is also possible to specify "vertex" which will cause the displacement shaders to be run on the primitive's vertices for less accurate but faster displacement. Note that in that case, the
calculatenormalshadeop will not work so the normals need to be displaced explicitely.
3Delight also allows the displacement bound to be specified as parameters of the displacement shader. This is especially useful when using stacked displacement shaders. The "sphere" and "coordinatesystem" parameters of the "displacementbound" attribute are simply replaced by two parameters.
EXAMPLE
displacement bumpy(
float Km = 1, amplitude = 1;
string texturename = "";
float __displacementbound_sphere = Km * amplitude;
string __displacementbound_coordinatesystem = "current" )
{
if( texturename != "" )
{
float amp = Km * amplitude * float texture( texturename, s, t );
P += amp * normalize(N);
N = calculatenormal( P );
}
}
Note that the parameters can be either computed by the shader (as in the example) or set when the shader is instantiated. The displacement bound specified with this method and the one specified with the attribute are added together.
5.2.6 User Attributes
Attribute "user" "uniform type variable" value- Specifies a user defined attribute. User attributes can be read in the shading language using the
attribute()shadeop. See attribute shadeop.
EXAMPLEAttribute "user" "float self_illuminated" [1]
Note that it is also possible to declare user defined options, as described in User Options.
5.2.7 Other Attributes
Attribute "sides" "float backfacetolerance" [90]- This value is the angle, in degrees, which specifies how much a surface must be backfacing so it can be discarded before displacement shading occurs. This is to account for the fact that the displacement shader may change the orientation of the surface. A value of 90 causes no backface culling to take place before displacement (the safe choice and the default). A value of 0 causes all backfacing surfaces to be discarded before displacement.
Attribute "sides" "integer doubleshaded" [0]- When this is set to 1, each surface is shaded twice: once as usual and once with the normals reversed. This allows thickness to be given to a surface with displacement or to avoid shading artifacts where a transparent surface changes orientation.
Attribute "trimcurve" "string sense" ["inside"]- Specifies whether the `interior' or the `exterior' of a trim curve should be trimmed (cut) on a NURBS surface. The default value is "inside". Specifying "outside" reverses the behavior.
Attribute "dice" "rasterorient" [1]- When raster oriented dicing is off (
[0]), surfaces are diced as if they will always face the camera. This is most useful when rendering surfaces that lose displacement details when turned sideways to the camera since micropolygons become big in camera space while they stay small in raster space. This feature increases the number of diced and shaded micropolygons, which leads to longer render times. Attribute "dice" "hair" [0]- This attribute allows direct control over the tesselation in the u parametric direction of curves. When set to 0, the width of the curve determines tesselation like other primitives. When set to a greater value, it is taken as the number of micropolygons to create in the u direction. A value of 1 is typically used to render hair.
Attribute "dice" "hairumin" [0]- This attribute is an alternate form of control over the tesselation in the u parametric direction of curves. It specifies the minimum number of micropolygons to create in the u direction. Unlike "dice" "hair", the actual tesselation can be greater than the specified value. It is useful for shaders which require more than one micropolygon to produce the correct look. Note that if both this attribute and "dice" "hair" are specified, the actual number of micropolygons will be the largest of both.
Attribute "dice" "referencecamera" ""- Selects a camera to use for dicing. The camera should be declared using
RiCameraas explained in Dicing Cameras. Attribute "derivatives" "integer centered" [1]- Centered derivatives help remove artifacts due to abutting patches having a different parametric orientation. They are automatically turned on with smooth shading interpolation and should never be turned off.
Attribute "derivatives" "integer forcesecond" [1]- By default, 3Delight attempts to provide shaders with values which allow second derivatives to be computed, even for very fine geometry. This means, for example, that the derivative of the surface normal will usually not be null. It also improves shading of curved surfaces. When the geometry is really too detailed, this may be unnecessary and have a significant impact on rendering times. Setting this attribute to 0 can then improve performance without a visible degradation of the image.
Attribute "derivatives" "integer smooth" [1]- Smooth derivatives help reduce shading artifacts at grid boundaries by providing a smooth variation of
duanddvacross the grid. They do so by computing ideal values as if theShadingRateattribute had been exactly met. This can also improve performance when micropolygons are much smaller than they need to be due to excessive geometric detail in the scene. However, the very same situation can cause issues with texture filtering if the overpaint zone is not large enough.
3Delight 8.5. Copyright 2000-2009 The 3Delight Team. All Rights Reserved.