RdlInstancerGeometry
Overview
RdlInstancerGeometry instances other geometry based on its parameters.
Geometry to instance is referenced with the references attribute. Which geometry to use per-instance is defined with the ref_indices attribute. Note that the reference object itself will not be rendered – only its instances.
The transforms of the instances can be defined by either the xforms_list which uses a list matrices or the positions, orientations, and scales vector list attributes. The attribute use_reference_xforms determines whether the instances should first be transformed by the reference object’s node_xform. Primitive attributes can be defined per-instance but only at a constant rate.
boxGeom = BoxGeometry("boxGeom") {
}
sphereGeom = SphereGeometry("sphereGeom") {
}
colorData = UserData("colorData") {
["color_key"] = "Cd",
["color_values_0"] = {
Rgb(1.0, 0.0, 0.0),
Rgb(0.0, 1.0, 0.0),
Rgb(0.0, 0.0, 1.0),
Rgb(1.0, 0.0, 1.0),
Rgb(0.0, 1.0, 1.0),
},
}
instancer0 = RdlInstancerGeometry("instancer0") {
["references"] = { boxGeom, sphereGeom },
["ref_indices"] = {0, 1, 0, 1, 0 },
["positions"] = {
Vec3(-0.1, 0.1, 0.0),
Vec3(0.1, 0.2, 0.0),
Vec3(-0.1, 0.3, 0.0),
Vec3(0.1, 0.4, 0.0),
Vec3(-0.1, 0.5, 0.0),
},
["orientations"] = {
Vec4(0.0, 0.0, -0.487175, -0.873305),
Vec4(0.0, 0.0, 0.0, 0.0),
Vec4(0.0, -0.487175, 0.0, -0.873305),
Vec4(0.0, 0.0, 0.0, 0.0),
Vec4(0.0, 0.0, 0.0, 0.0),
},
["scales"] = {
Vec3(0.15, 0.05, 0.05),
Vec3(0.05, 0.05, 0.05),
Vec3(0.1, 0.05, 0.2),
Vec3(0.05, 0.1, 0.05),
Vec3(0.1, 0.1, 0.1),
},
["primitive_attributes"] = {
colorData,
},
}
colorData2 = UserData("colorData2") {
["color_key"] = "Cd",
["color_values_0"] = {
Rgb(1.0, 0.0, 0.0),
Rgb(0.0, 1.0, 0.0),
Rgb(0.0, 0.0, 1.0),
},
}
Referenced geometry must also be declared in the GeometrySet and materials must also be assigned to the referenced geometry. Any material assigned to the RdlInstancerGeometry itself is ignored.
GeometrySet("/Scene/geometry/all") {
grid,
boxGeom,
sphereGeom,
instancer0,
instancer1,
}
geomMtl = DwaSolidDielectricMaterial("geomMtl") {
["show_diffuse"] = true,
["show_specular"] = true,
["albedo"] = bind(attrMapCd, Rgb(0.1, 0.1, 0.1)),
["roughness"] = 0.2,
}
Layer("/Scene/rendering/all") {
{boxGeom, "", geomMtl},
{sphereGeom, "", geomMtl},
{instancer0, ""}
}
Instancer geometry may itself also be instanced up to four levels deep. The example below instances the previously defined instancer. It also uses its own set of Cd color data which overrides the data on the referenced instancer.
colorData2 = UserData("colorData2") {
["color_key"] = "Cd",
["color_values_0"] = {
Rgb(1.0, 0.0, 0.0),
Rgb(0.0, 1.0, 0.0),
Rgb(0.0, 0.0, 1.0),
},
}
instancer1 = RdlInstancerGeometry("instancer1") {
["references"] = { instancer0 },
["positions"] = {
Vec3(-0.2, 0.0, 0.0),
Vec3(-0.0, 0.1, -0.2),
Vec3(0.3, 0.0, 0.0),
},
["primitive_attributes"] = {
colorData2,
},
}
GeometrySet("/Scene/geometry/all") {
boxGeom,
sphereGeom,
instancer0,
instancer1,
}
Layer("/Scene/rendering/all") {
{boxGeom, "", geomMtl},
{sphereGeom, "", geomMtl},
{instancer0, "" },
{instancer1, "" },
}
Attribute Reference
Geometry attributes
reverse_normals
Bool
default: False
enable to reverse the normals in the geometry
side_type
Int enum
0 = “force two-sided” (default)
1 = “force single-sided”
2 = “use mesh sidedness”
set single sidedness of the mesh, will affect the visibility of the mesh based on normal direction
Instancing attributes
disable_indices
IntVector
default: {}
A list of index values to hide / disable. For example, with 4 instances you can supply a list of 0, 2 to disable those instances. If an index in this list is out of range, it is ignored.
instance_level
Int enum
0 = “instance level 0” (default)
1 = “instance level 1”
2 = “instance level 2”
3 = “instance level 3”
4 = “instance level 4”
Sets the level/depth of this instance. This adds a Mat4f primitive attribute to the geometry which can be referenced during shading to use the local space of each instance. The name of the primitive attribute corresponds the the instance level that is set (i.e. "instance_level_0", "instance_level_1", etc)
method
Int enum
0 = “xform attributes” (default)
2 = “xform list”
Specifies the source of the transform data for instancing. If set to "xform attributes", data is used from the "positions", "orientations", "scales" attributes.If set to "xform list", data is used from the "xform list"attribute.
orientations
Vec4fVector
default: {}
A list of Vec4 quaternions that represent the per-instance orientation. The length of the list should be either 0 or consistent with "positions".
positions
Vec3fVector
default: {}
A list of Vec3 values that represent the per-instance position.
ref_indices
IntVector
default: {}
A list of index values to specify which reference geometry to instance at each position. The list corresponds to entries in the "references" attribute. The length of the list should be either 0 or consistent with "positions"|"xform_list". The index entry falls back to 0 when this attribute is empty or the value of entry is out of index range
scales
Vec3fVector
default: {}
A list of Vec3 values that represet the per-instance velocity(motion blur). The length of the list should be either 0 or consistent with "positions".
use_reference_attributes
Bool
default: True
Use the geometry attributes of the reference (prototype) instead of the ones on the InstanceGeometry. Currently only works for shadow_ray_epsilon
use_reference_xforms
Bool
default: False
Transform the reference (prototype) geometry by it's node_xform parameter before applying the instance transform
xform_list
Mat4dVector
default: {}
A list of Mat4 transforms that represent the per-instance xform.
Labels attributes
label
String
default:
label used in material aov expresssions
shadow_receiver_label
String
default:
Label used to associate Geometry objects into ShadowReceiverSets. Using this in combination with the ["shadow_exclusion_mappings"] attribute, shadows from specified geometries or their parts can be suppressed from casting shadows onto one or more specified sets.
Motion Blur attributes
velocities
Vec3fVector
default: {}
No documentation available
Ray Tracing attributes
ray_epsilon
Float
default: 0.0
When a secondary ray is fired, anything within this distance of the intersection point will be ignored. Instead, it is considered part of the current intersection's geometry. If zero, an automatically calculated epsilon will be used.
shadow_ray_epsilon
Float
default: 0.0
When a shadow ray is fired, anything within this distance of the intersection point will be ignored. If this value is less than "ray_epsilon", then it has no additional effect.
Time attributes
evaluation_frame
Float
default: 0.0
Evaluate geometry at specified frame (relative) instead of SceneVariables frame.
User Data attributes
primitive_attributes
UserData Vector
default: {}
A list of UserData to specify arbitrary primitive attributes(For example, color or roughness multiplier) per-instance
Visibility attributes
visible_diffuse_reflection
Bool
default: True
whether the geometry is visible in diffuse reflection
visible_diffuse_transmission
Bool
default: True
whether the geometry is visible in diffuse transmission
visible_glossy_reflection
Bool
default: True
whether the geometry is visible in glossy reflection.
visible_glossy_transmission
Bool
default: True
whether the geometry is visible in glossy transmission (refraction).
visible_in_camera
Bool
default: True
whether the geometry is visible to camera rays
visible_mirror_reflection
Bool
default: True
whether the geometry is visible in miror reflection.
visible_mirror_transmission
Bool
default: True
whether the geometry is visible in miror transmission (refraction).
visible_shadow
Bool
default: True
whether the geometry casts shadows
visible_volume
Bool
default: True
whether the geometry is visible in indirect volume rays
General attributes
contains_camera
Bool
default: False
Specifies whether the geometry contains the camera and should be used for IOR tracking. This should not be changed by the user -- they should instead attach the relevant geometry to the camera, which will then flag this geometry.
dicing_camera
SceneObject
default: None
Alternate camera that is used for adaptive tessellation. This is useful if you want adaptive tessellation to behave consistently in a sequence, regardless of what the main camera is doing
node_xform
Mat4d blurrable
default: [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]
The 4x4 matrix describing the transformation from local space to world space.
references
Geometry Vector
default: {}
list of geometries that geometry procedural can reference during procedural generate/update stages. For example, an instancer geometry procedural can instance primitives generated by the reference geometry procedural.
shadow_exclusion_mappings
String
default:
A space-separated list of mappings of the form A:B where:
A is a comma-separated list of names of parts of this Geometry, or an asterisk to specify the whole geometry;
B is a comma-separated list of shadow receiver set labels established using the ["shadow_receiver_label"] attribute, or an asterisk to specify to all such sets in the scene.
For each of the listed mappings, shadows from the parts specified in A will be suppressed from casting onto any geometries in the ShadowReceiverSets specified in B.
**Note: no part name should appear more than once in the string, otherwise the behavior is undefined.**
static
Bool
default: True
disable if the geometry will be updated between frames
use_explicit_shading_attributes
Bool
default: False
Enable the use of explicit shading attributes (N, dPds, dPdt) if they are present
use_local_camera_motion_blur
Bool
default: False
Enables experimental feature that also attempts to remove the camera blur in the local regions
use_local_motion_blur
Bool
default: False
Enables the local motion blur feature, which makes the geometry procedural responsible for handling all of the geometry's motion and allows for custom effects