1RTC_GEOMETRY_TYPE_INSTANCEE(m3b)ree Ray Tracing KernelRsTC3_GEOMETRY_TYPE_INSTANCE(3)
2
3
4
5   NAME
6              RTC_GEOMETRY_TYPE_INSTANCE - instance geometry type
7
8   SYNOPSIS
9              #include <embree3/rtcore.h>
10
11              RTCGeometry geometry =
12                 rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE);
13
14   DESCRIPTION
15       Embree  supports instancing of scenes using affine transformations (3×3
16       matrix plus translation).  As the instanced scene is stored only a sin‐
17       gle  time, even if instanced to multiple locations, this feature can be
18       used to create very complex scenes with small memory footprint.
19
20       Embree supports both single-level instancing and  multi-level  instanc‐
21       ing.   The  maximum  instance  nesting  depth  is RTC_MAX_INSTANCE_LEV‐
22       EL_COUNT; it can be configured at compile-time using the  constant  EM‐
23       BREE_MAX_INSTANCE_LEVEL_COUNT.   Users  should  adapt  this constant to
24       their needs: instances nested any deeper are silently  ignored  in  re‐
25       lease mode, and cause assertions in debug mode.
26
27       Instances are created by passing RTC_GEOMETRY_TYPE_INSTANCE to the rtc‐
28       NewGeometry function call.  The instanced scene can be  set  using  the
29       rtcSetGeometryInstancedScene call, and the affine transformation can be
30       set using the rtcSetGeometryTransform function.
31
32       Please note that rtcCommitScene on the instanced scene should be called
33       first,  followed by rtcCommitGeometry on the instance, followed by rtc‐
34       CommitScene for the top-level scene containing the instance.
35
36       If a ray hits the instance, the geomID and primID members  of  the  hit
37       are set to the geometry ID and primitive ID of the hit primitive in the
38       instanced scene, and the instID member of the hit is set to the  geome‐
39       try ID of the instance in the top-level scene.
40
41       The  instancing  scheme  can also be implemented using user geometries.
42       To achieve this, the user geometry code should set the instID member of
43       the intersection context to the geometry ID of the instance, then trace
44       the transformed ray, and finally set the instID field of the  intersec‐
45       tion  context again to -1.  The instID field is copied automatically by
46       each primitive intersector into the instID field of the  hit  structure
47       when the primitive is hit.  See the [User Geometry] tutorial for an ex‐
48       ample.
49
50       For multi-segment motion blur, the number of time steps must  be  first
51       specified  using  the  rtcSetGeometryTimeStepCount  function.   Then  a
52       transformation for each time step can be specified using the  rtcSetGe‐
53       ometryTransform function.
54
55       See tutorials [Instanced Geometry] and [Multi Level Instancing] for ex‐
56       amples of how to use instances.
57
58   EXIT STATUS
59       On failure NULL is returned and an  error  code  is  set  that  can  be
60       queried using rtcGetDeviceError.
61
62   SEE ALSO
63       [rtcNewGeometry], [rtcSetGeometryInstancedScene], [rtcSetGeometryTrans‐
64       form]
65
66
67
68                                                 RTC_GEOMETRY_TYPE_INSTANCE(3)