.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "RTC_GEOMETRY_TYPE_INSTANCE" "3" "" "" "Embree Ray Tracing Kernels 4"
.SS NAME
.IP
.EX
RTC_GEOMETRY_TYPE_INSTANCE \- instance geometry type
.EE
.SS SYNOPSIS
.IP
.EX
#include <embree4/rtcore.h>

RTCGeometry geometry =
   rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE);
.EE
.SS DESCRIPTION
Embree supports instancing of scenes using affine transformations (3×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[CR]RTC_MAX_INSTANCE_LEVEL_COUNT\f[R]; it can be configured at
compile\-time using the constant
\f[CR]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[CR]RTC_GEOMETRY_TYPE_INSTANCE\f[R]
to the \f[CR]rtcNewGeometry\f[R] function call.
The instanced scene can be set using the
\f[CR]rtcSetGeometryInstancedScene\f[R] call, and the affine
transformation can be set using the \f[CR]rtcSetGeometryTransform\f[R]
function.
.PP
Please note that \f[CR]rtcCommitScene\f[R] on the instanced scene should
be called first, followed by \f[CR]rtcCommitGeometry\f[R] on the
instance, followed by \f[CR]rtcCommitScene\f[R] for the top\-level scene
containing the instance.
.PP
If a ray hits the instance, the \f[CR]geomID\f[R] and \f[CR]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[CR]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[CR]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[CR]instID\f[R] field
of the ray query context again to \-1.
The \f[CR]instID\f[R] field is copied automatically by each primitive
intersector into the \f[CR]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[CR]rtcSetGeometryTimeStepCount\f[R] function.
Then a transformation for each time step can be specified using the
\f[CR]rtcSetGeometryTransform\f[R] function.
.PP
See tutorials [Instanced Geometry] and [Multi Level Instancing] for
examples of how to use instances.
.SS EXIT STATUS
On failure \f[CR]NULL\f[R] is returned and an error code is set that can
be queried using \f[CR]rtcGetDeviceError\f[R].
.SS SEE ALSO
[rtcNewGeometry], [rtcSetGeometryInstancedScene],
[rtcSetGeometryTransform]