1RTC_GEOMETRY_TYPE_INSTANCEE_mAbRrReAeY(R3a)y TracingRKTeCr_nGeElOsME4TRY_TYPE_INSTANCE_ARRAY(3)
2 NAME
6 RTC_GEOMETRY_TYPE_INSTANCE_ARRAY - instance array geometry type
7 SYNOPSIS
9 #include <embree4/rtcore.h>
10 RTCGeometry geometry =
12 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE_ARRAY);
13 DESCRIPTION
15 Embree supports instance arrays, which is a more memory efficient way
16 to represent large amounts of instances of the same or a small set of
17 (sub)scenes. The main difference to regular Embree instances is that
18 Embree instance arrays have a buffer of transformations (either affine
19 transformations or quaternion decompositions [RTCQuaternionDecomposi‐
20 tion]) that can be allocated by Embree or a shared buffer, similar to
21 vertex buffers for triangle meshes. Optionally, instead of instancing
22 only one scene, an instance array can instance multiple scenes by pass‐
23 ing an array of scenes and a corresponding index buffer that specifies
24 which instance of the instance array instances which of the scenes in
25 the scenes array.
26 Instance arrays are created by passing RTC_GEOMETRY_TYPE_INSTANCE_ARRAY
28 to the rtcNewGeometry function call. The instanced scene can be either
29 be set using the rtcSetGeometryInstancedScene call, or if multiple
30 scenes should be instanced by passing an array of scenes using rtcSet‐
31 GeometryInstancedScenes. The latter also requires to specify an index
32 buffer using rtcSetNewGeometryBuffer or rtcSetSharedGeometryBuffer with
33 RTC_BUFFER_TYPE_INDEX as the buffer type.
34 Because the transformation information can become large for a large
36 amount of instances, the instance array allows to share the transforma‐
37 tion buffer between the user application and Embree. It can be either
38 stored in a buffer created by Embree with rtcSetNewGeometryBuffer or an
39 already existing buffer can be shared using rtcSetSharedGeometryBuffer.
40 In either case, the buffer type has to be RTC_BUFFER_TYPE_TRANSFORM and
41 the allowed formats are RTC_FORMAT_FLOAT4X4_COLUMN_MAJOR, RTC_FOR‐
42 MAT_FLOAT3X4_COLUMN_MAJOR, RTC_FORMAT_FLOAT3X4_ROW_MAJOR, and RTC_FOR‐
43 MAT_QUATERNION_DECOMPOSITION. Embree will not modify the data in the
44 transformation buffer.
45 Embree instance arrays support both single-level instancing and multi-
47 level instancing. The maximum instance nesting depth is RTC_MAX_IN‐
48 STANCE_LEVEL_COUNT; it can be configured at compile-time using the con‐
49 stant EMBREE_MAX_INSTANCE_LEVEL_COUNT. Users should adapt this con‐
50 stant to their needs: instances nested any deeper are silently ignored
51 in release mode, and cause assertions in debug mode.
52 Please note that rtcCommitScene on the instanced scene(s) should be
54 called first, followed by rtcCommitGeometry on the instance array, fol‐
55 lowed by rtcCommitScene for the top-level scene containing the instance
56 array.
57 If a ray hits the instance, the geomID and primID members of the hit
59 are set to the geometry ID and primitive ID of the hit primitive in the
60 instanced scene. The instID member of the hit is set to the geometry
61 ID of the instance array in the top-level scene and the instPrimID mem‐
62 ber is set to the index of the hit instance of the instance array.
63 For multi-segment motion blur, the number of time steps must be first
65 specified using the rtcSetGeometryTimeStepCount function. Then a
66 transformation for each time step can be specified using the rtcSetNew‐
67 GeometryBuffer or rtcSetSharedGeometryBuffer function and passing the
68 time step as the slot parameter of these calls.
69 See the [Instance Array Geometry] tutorial for an example of how to use
71 instance arrays.
72 EXIT STATUS
74 On failure NULL is returned and an error code is set that can be
75 queried using rtcGetDeviceError.
76 SEE ALSO
78 [rtcNewGeometry], [rtcSetGeometryInstancedScene], [rtcSetGeometryIn‐
79 stancedScenes], [rtcSetNewGeometryBuffer], [rtcSetSharedGeometry‐
80 Buffer], [rtcGetGeometryTransformEx]
81 RTC_GEOMETRY_TYPE_INSTANCE_ARRAY(3)