RTC_GEOME..._INSTANCE(3)

💖 NAME 💖

RTC_GEOMETRY_TYPE_INSTANCE — the instance geometry type, bestie. Yes, from the Embree Ray Tracing Kernels 4 manual, section 3. Buckle up, this one's a bop. 🦋

---

✨ SYNOPSIS ✨

#include <embree4/rtcore.h>

RTCGeometry geometry =
   rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE);

---

🌸 DESCRIPTION 🌸

Okay so picture this: Embree lets you instance whole scenes using affine transformations — that's a 3×3 matrix plus a translation, the whole glow-up package. And the iconic part? The instanced scene gets stored only a single time, even if you plop it down in a million different locations. So you can build absolutely unhinged, complex scenes with a tiny little memory footprint. It's giving efficiency. It's giving main character energy. 👑

Embree serves both single-level instancing and multi-level instancing, no gatekeeping. The max instance nesting depth is RTC_MAX_INSTANCE_LEVEL_COUNT, and you can configure that at compile-time using the constant EMBREE_MAX_INSTANCE_LEVEL_COUNT. So like — adapt that constant to your needs, fr fr, because instances nested any deeper are silently ignored in release mode and cause assertions in debug mode. 💀 Not a vibe, just a fact.

Instances get created by passing RTC_GEOMETRY_TYPE_INSTANCE to the rtcNewGeometry function call. Then:

• the instanced scene can be set with the rtcSetGeometryInstancedScene call 🎀
• the affine transformation can be set with the rtcSetGeometryTransform function ✨

Bestie, listen closely: rtcCommitScene on the instanced scene should be called first, then rtcCommitGeometry on the instance, then rtcCommitScene for the top-level scene containing the instance. In that order. Periodt. The order is the whole personality here.

So when a ray hits the instance, the geomID and primID members of the hit get set to the geometry ID and primitive ID of the hit primitive in the instanced scene, and the instID member of the hit gets set to the geometry ID of the instance in the top-level scene. Clean. Tidy. Obsessed. 💅

You can also pull off the instancing scheme with user geometries, if that's more your thing. Here's the recipe:

1. the user geometry code sets the instID member of the ray query context to the geometry ID of the instance
2. then it traces the transformed ray
3. and finally sets the instID field of the ray query context back to -1 🫶

And here's the cute little detail: 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, iykyk. 🌈

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. One per step, no skipping. ⭐

Also, go look at the tutorials [Instanced Geometry] and [Multi Level Instancing] for examples of how to use instances — they ate, honestly. 🔥

---

💀 EXIT STATUS 💀

On failure, NULL is returned and an error code is set that can be queried using rtcGetDeviceError. So check it. Don't just sit there wondering why your geometry is giving nothing. 🙈

---

🎀 SEE ALSO 🎀

• [rtcNewGeometry]
• [rtcSetGeometryInstancedScene]
• [rtcSetGeometryTransform]

---

Okay that's the whole page, bestie — straight from the Embree Ray Tracing Kernels 4 manual, RTC_GEOME..._INSTANCE(3), section 3 of the manual set. Go instance something iconic. 💖✨🧚