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

RTCGeometry geometry =
   rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE_ARRAY);
\f[R]
.fi
.SS DESCRIPTION
.PP
Embree supports instance arrays, which is a more memory efficient way to
represent large amounts of instances of the same or a small set of
(sub)scenes.
The main difference to regular Embree instances is that Embree instance
arrays have a buffer of transformations (either affine transformations
or quaternion decompositions [RTCQuaternionDecomposition]) that can be
allocated by Embree or a shared buffer, similar to vertex buffers for
triangle meshes.
Optionally, instead of instancing only one scene, an instance array can
instance multiple scenes by passing an array of scenes and a
corresponding index buffer that specifies which instance of the instance
array instances which of the scenes in the scenes array.
.PP
Instance arrays are created by passing
\f[C]RTC_GEOMETRY_TYPE_INSTANCE_ARRAY\f[R] to the
\f[C]rtcNewGeometry\f[R] function call.
The instanced scene can be either be set using the
\f[C]rtcSetGeometryInstancedScene\f[R] call, or if multiple scenes
should be instanced by passing an array of scenes using
\f[C]rtcSetGeometryInstancedScenes\f[R].
The latter also requires to specify an index buffer using
\f[C]rtcSetNewGeometryBuffer\f[R] or
\f[C]rtcSetSharedGeometryBuffer\f[R] with
\f[C]RTC_BUFFER_TYPE_INDEX\f[R] as the buffer type.
.PP
Because the transformation information can become large for a large
amount of instances, the instance array allows to share the
transformation buffer between the user application and Embree.
It can be either stored in a buffer created by Embree with
\f[C]rtcSetNewGeometryBuffer\f[R] or an already existing buffer can be
shared using \f[C]rtcSetSharedGeometryBuffer\f[R].
In either case, the buffer type has to be
\f[C]RTC_BUFFER_TYPE_TRANSFORM\f[R] and the allowed formats are
\f[C]RTC_FORMAT_FLOAT4X4_COLUMN_MAJOR\f[R],
\f[C]RTC_FORMAT_FLOAT3X4_COLUMN_MAJOR\f[R],
\f[C]RTC_FORMAT_FLOAT3X4_ROW_MAJOR\f[R], and
\f[C]RTC_FORMAT_QUATERNION_DECOMPOSITION\f[R].
Embree will not modify the data in the transformation buffer.
.PP
Embree instance arrays support 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
Please note that \f[C]rtcCommitScene\f[R] on the instanced scene(s)
should be called first, followed by \f[C]rtcCommitGeometry\f[R] on the
instance array, followed by \f[C]rtcCommitScene\f[R] for the top-level
scene containing the instance array.
.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.
The \f[C]instID\f[R] member of the hit is set to the geometry ID of the
instance array in the top-level scene and the \f[C]instPrimID\f[R]
member is set to the index of the hit instance of the instance array.
.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]rtcSetNewGeometryBuffer\f[R] or
\f[C]rtcSetSharedGeometryBuffer\f[R] function and passing the time step
as the \f[C]slot\f[R] parameter of these calls.
.PP
See the [Instance Array Geometry] tutorial for an example of how to use
instance arrays.
.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],
[rtcSetGeometryInstancedScenes], [rtcSetNewGeometryBuffer],
[rtcSetSharedGeometryBuffer], [rtcGetGeometryTransformEx]