---
name: "RTC_GEOMETRY_TYPE_INSTANCE_ARRAY"
section: "3"
platform: "linux"
package: "libembree-dev"
version: "4.3.3+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/RTC_GEOMETRY_TYPE_INSTANCE_ARRAY"
---

# RTC\_GEOMETRY\_TYPE\_INSTANCE\_ARRAY(3)

### NAME

-

  ```
  RTC_GEOMETRY_TYPE_INSTANCE_ARRAY - instance array geometry type
  ```

### SYNOPSIS

-

  ```
  #include <embree4/rtcore.h>
  RTCGeometry geometry =
     rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE_ARRAY);
  ```

### DESCRIPTION

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.

Instance arrays are created by passing `RTC_GEOMETRY_TYPE_INSTANCE_ARRAY` to the `rtcNewGeometry` function call. The instanced scene can be either be set using the `rtcSetGeometryInstancedScene` call, or if multiple scenes should be instanced by passing an array of scenes using `rtcSetGeometryInstancedScenes`. The latter also requires to specify an index buffer using `rtcSetNewGeometryBuffer` or `rtcSetSharedGeometryBuffer` with `RTC_BUFFER_TYPE_INDEX` as the buffer type.

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 `rtcSetNewGeometryBuffer` or an already existing buffer can be shared using `rtcSetSharedGeometryBuffer`. In either case, the buffer type has to be `RTC_BUFFER_TYPE_TRANSFORM` and the allowed formats are `RTC_FORMAT_FLOAT4X4_COLUMN_MAJOR`, `RTC_FORMAT_FLOAT3X4_COLUMN_MAJOR`, `RTC_FORMAT_FLOAT3X4_ROW_MAJOR`, and `RTC_FORMAT_QUATERNION_DECOMPOSITION`. Embree will not modify the data in the transformation buffer.

Embree instance arrays support both single-level instancing and multi-level instancing. The maximum instance nesting depth is `RTC_MAX_INSTANCE_LEVEL_COUNT`; it can be configured at compile-time using the constant `EMBREE_MAX_INSTANCE_LEVEL_COUNT`. Users should adapt this constant to their needs: instances nested any deeper are silently ignored in release mode, and cause assertions in debug mode.

Please note that `rtcCommitScene` on the instanced scene(s) should be called first, followed by `rtcCommitGeometry` on the instance array, followed by `rtcCommitScene` for the top-level scene containing the instance array.

If a ray hits the instance, the `geomID` and `primID` members of the hit are set to the geometry ID and primitive ID of the hit primitive in the instanced scene. The `instID` member of the hit is set to the geometry ID of the instance array in the top-level scene and the `instPrimID` member is set to the index of the hit instance of the instance array.

For multi-segment motion blur, the number of time steps must be first specified using the `rtcSetGeometryTimeStepCount` function. Then a transformation for each time step can be specified using the `rtcSetNewGeometryBuffer` or `rtcSetSharedGeometryBuffer` function and passing the time step as the `slot` parameter of these calls.

See the \[Instance Array Geometry\] tutorial for an example of how to use instance arrays.

### EXIT STATUS

On failure `NULL` is returned and an error code is set that can be queried using `rtcGetDeviceError`.

### SEE ALSO

\[rtcNewGeometry\], \[rtcSetGeometryInstancedScene\], \[rtcSetGeometryInstancedScenes\], \[rtcSetNewGeometryBuffer\], \[rtcSetSharedGeometryBuffer\], \[rtcGetGeometryTransformEx\]