---
name: "RTC_GEOMETRY_TYPE_INSTANCE"
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"
---

# RTC\_GEOMETRY\_TYPE\_INSTANCE(3)

### NAME

-

  ```
  RTC_GEOMETRY_TYPE_INSTANCE - instance geometry type
  ```

### SYNOPSIS

-

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

### 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.

Embree supports 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.

Instances are created by passing `RTC_GEOMETRY_TYPE_INSTANCE` to the `rtcNewGeometry` function call. The instanced scene can be set using the `rtcSetGeometryInstancedScene` call, and the affine transformation can be set using the `rtcSetGeometryTransform` function.

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

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, and the `instID` member of the hit is set to the geometry ID of the instance in the top-level scene.

The instancing scheme can also be implemented using user geometries. To achieve this, the user geometry code should set the `instID` member of the ray query context to the geometry ID of the instance, then trace the transformed ray, and finally set the `instID` field of the ray query context again to -1. The `instID` field is copied automatically by each primitive intersector into the `instID` field of the hit structure when the primitive is hit. See the \[User Geometry\] tutorial for an example.

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 `rtcSetGeometryTransform` function.

See tutorials \[Instanced Geometry\] and \[Multi Level Instancing\] for examples of how to use instances.

### EXIT STATUS

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

### SEE ALSO

\[rtcNewGeometry\], \[rtcSetGeometryInstancedScene\], \[rtcSetGeometryTransform\]