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 and are described in the subsections sections below. 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.
|
5.2.1 Primitives Identification
Attribute "identifier" "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" [""]- 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" [""]- 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" [""]- 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 group name. Primitives that are in the same subsurface group are considered as forming one closed object. A special group name 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 "shade" "viewdependent" [0]- When using multi-camera rendering (see section Multi-Camera Rendering) this will make the renderer shade each grid one per camera.
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.
Attribute "trace" "int maxdiffusedepth" [1]Attribute "trace" "int maxspeculardepth" [2]- Specifies the maximum depth for reflections and diffuse bounces.
Attribute "trace" "float importancethreshold" [0.001]- 3Delight will attempt not to trace rays with lower importance than this value. The process adds some noise which is usually not noticeable. A larger value here will improve performance while a smaller one will lower that specific source of noise.
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(17). "illuminance"- This is the "physically correct" area light sampling that will run illuminance based shadeops (18) 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).
"trace"- This strategy will allow the area light to be sampled by the trace shadeop. The area light will not be seen by illuminance loops or shadeops such as
specular(). This provides the highest quality but requires support from the surface shaders.
illumianceconstructs. Attribute "light" "integer normalize" [0]- If set to 1, area light intensity will be scaled by the inverse of the total area of the arealight. Meaning that changing area light size won't affect overall lighting intensity. This only works with the `trace' sampling strategy.
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. Attribute "subsurface" "string type" "pointlcoud | raytrace"- Specifies the algorithm to use for subsurface scattering. Additionally, object "grouping" is not supported by ray tracing the algorithm. This attribute can be overridden by the
subsurface()shadeop (see subsurface shadeop). Attribute "subsurface" "integer samples" [n]- For the ray tracing algorithm, specify how many rays to trace. This value can be overridden by the
subsurface()shadeop (see subsurface shadeop).
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 "trace" "float displacementshadingrate" [1]- Controls at which frequency the displacement shader is run on the geometry before intersecting it with rays. Larger values will be faster and use less memory while smaller values will yield more accurate results.
Attribute "trace" "float inflategrids" [0]- This setting allows the grids used to trace displacements to be slightly inflated to hide cracks which may occur between them. Values between 0 and 1 will usually hide most problems. Turning this on can have a significant effect on performance so use it only when needed.
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. Attribute "displacement" "int level" [100]- 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. A value of 0 will displace only the mesh vertices, with the shader being run again to provide bump mapping of fine detail. It is only supported for polygon meshes and subdivision surfaces.
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.
As an optimization, the shader may also have an extra parameter which tells the render if it is actually doing any displacement, based on its specific parameter values. This allows 3Delight to render more efficiently when a displacement shader is used but set to do no real displacement. Here is an example with a simple shader object:
class bumpy_surface(
float Km = 1, amplitude = 1;
string texturename = "";
float Ka = 0.2, Kd = 0.8 )
{
public constant float __displacementbound_sphere;
public constant string __displacementbound_coordinatesystem = "current";
public constant float __displacement_enabled;
public void construct()
{
__displacementbound_sphere = Km * amplitude;
if( __displacementbound_sphere > 0 && texturename != "" )
{
__displacement_enabled = 1;
}
else
{
__displacement_enabled = 0;
}
}
public void displacement( output point P; output normal N )
{
if( texturename != "" )
{
float amp = Km * amplitude * float texture( texturename );
P += amp * normalize(N);
N = calculatenormal( P );
}
}
public void surface( output color Ci; output color Oi )
{
float diffuse = I.N;
diffuse = (diffuse*diffuse) / (I.I * N.N);
Ci = Cs * ( Ka + Kd*diffuse );
Oi = Os;
Ci *= Oi;
}
}
Note that public members are being used here instead of parameters.
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" "lodreferencecamera" ""- Specifies a camera (or a list of cameras, separated by commas) to use in selecting the detail level to render. The cameras should be declared using
RiCamera. If this is not specified, the dice reference cameras are used instead. If those are not specified, the main camera is used. Attribute "dice" "referencecamera" ""- Selects a camera (or a list of cameras, separated by commas) 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. Attribute "procedural" "integer reentrant" 1- When run with multiple threads, 3Delight may choose to call the same procedural function with different data from more than one thread at once. If some procedural is not thread safe, this attribute can be set to 0 to disable that behavior(19). The default should be used for better performance.
Attribute "shade" "string frequency" "motionsegment"- This controls how often primitives with multi-segment motion blur are shaded. The default value of "motionsegment" shades at the start of every segment. A value of "frame" specifies shading only once per frame, at the first segment. This is less accurate but will usually be faster and use less memory. Note that some primitives only support "motionsegment", in which case the attribute is silently ignored.
Attribute "shade" "volumeintersectionstrategy" ["exclusive"]- Dictates what to do with intersecting interior volumes. By default, only one of the interior volume is run. If set to "additive", all volumes in an intersecting region will be evaluated.
Attribute "shade" "integer smoothnormals" 0- Setting this attribute to 1 tells 3Delight to render polygon meshes with smooth normals instead of geometric normals. It will have no effect if the N primitive variable was already supplied with the mesh.
Attribute "shade" "shadingrate" [1]- This is exactly equivalent to the
ShadingRatecommand. Attribute "shade" "relativeshadingrate" [1]Attribute "shade" "resetrelativeshadingrate" [1]- "relativeshadingrate" sets the value of the relative shading rate. This will be multiplied by all the relative shading rates found "upward" in the attribute stack.
"resetrelativeshadingrate" will reset the current value of the relative shading rate to the provide value (meaning that relative shading rates won't be considered from that point upwards). Final shading rate of the surface is computed by multiplying the shading rate by the cumulated relative shading rates. The following example illustrates how this feature works.
ShadingRate 2.0 AttributeBegin Attribute "shade" "relativeshadingrate" 10.0 # shading rate is now 20 AttributeBegin Attribute "shader" "relativeshadingrate" 0.2 # shading rate is is now 4 AttributeBegin Attribute "shader" "resetrelativeshadingrate" 0.1 # shading rate is now 0.2 since 0.1 x 2 = 0.2 AttributeEnd AttributeEnd AttributeEnd Attribute "shutter" "offset" [0.0]- This is added to the shutter offset option and serves exactly the same purpose but is more flexible because it is an attribute. For example, it can be applied to only a single archive in a scene. See also the shutter offset option.
3Delight 10.0. Copyright 2000-2011 The 3Delight Team. All Rights Reserved.