.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "RTC_GEOMETRY_TYPE_INSTANCE" "3" "" "" "Embree Ray Tracing Kernels 4"
.hy
.SS NAME
.IP
.nf
\f[C]
RTC_GEOMETRY_TYPE_INSTANCE - instance geometry type
\f[R]
.fi
.SS SYNOPSIS
.IP
.nf
\f[C]
#include <embree4/rtcore.h>

RTCGeometry geometry =
   rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE);
\f[R]
.fi
.SS DESCRIPTION
.PP
Embree supports instancing of scenes using affine transformations
(3\[tmu]3 matrix plus translation).
As the instanced scene is stored only a single time, even if instanced
to multiple locations, this feature can be used to create very complex
scenes with small memory footprint.
.PP
Embree supports both single-level instancing and multi-level instancing.
The maximum instance nesting depth is
\f[C]RTC_MAX_INSTANCE_LEVEL_COUNT\f[R]; it can be configured at
compile-time using the constant
\f[C]EMBREE_MAX_INSTANCE_LEVEL_COUNT\f[R].
Users should adapt this constant to their needs: instances nested any
deeper are silently ignored in release mode, and cause assertions in
debug mode.
.PP
Instances are created by passing \f[C]RTC_GEOMETRY_TYPE_INSTANCE\f[R] to
the \f[C]rtcNewGeometry\f[R] function call.
The instanced scene can be set using the
\f[C]rtcSetGeometryInstancedScene\f[R] call, and the affine
transformation can be set using the \f[C]rtcSetGeometryTransform\f[R]
function.
.PP
Please note that \f[C]rtcCommitScene\f[R] on the instanced scene should
be called first, followed by \f[C]rtcCommitGeometry\f[R] on the
instance, followed by \f[C]rtcCommitScene\f[R] for the top-level scene
containing the instance.
.PP
If a ray hits the instance, the \f[C]geomID\f[R] and \f[C]primID\f[R]
members of the hit are set to the geometry ID and primitive ID of the
hit primitive in the instanced scene, and the \f[C]instID\f[R] member of
the hit is set to the geometry ID of the instance in the top-level
scene.
.PP
The instancing scheme can also be implemented using user geometries.
To achieve this, the user geometry code should set the \f[C]instID\f[R]
member of the ray query context to the geometry ID of the instance, then
trace the transformed ray, and finally set the \f[C]instID\f[R] field of
the ray query context again to -1.
The \f[C]instID\f[R] field is copied automatically by each primitive
intersector into the \f[C]instID\f[R] field of the hit structure when
the primitive is hit.
See the [User Geometry] tutorial for an example.
.PP
For multi-segment motion blur, the number of time steps must be first
specified using the \f[C]rtcSetGeometryTimeStepCount\f[R] function.
Then a transformation for each time step can be specified using the
\f[C]rtcSetGeometryTransform\f[R] function.
.PP
See tutorials [Instanced Geometry] and [Multi Level Instancing] for
examples of how to use instances.
.SS EXIT STATUS
.PP
On failure \f[C]NULL\f[R] is returned and an error code is set that can
be queried using \f[C]rtcGetDeviceError\f[R].
.SS SEE ALSO
.PP
[rtcNewGeometry], [rtcSetGeometryInstancedScene],
[rtcSetGeometryTransform]