RTC_GEOME..._INSTANCE(3)

💖 RTC_GEOMETRY_TYPE_INSTANCE — instance geometry type 💖

okay bestie, welcome to the Embree Ray Tracing Kernels 3 manual, section 3 — this one is literally the blueprint for RTC_GEOMETRY_TYPE_INSTANCE, and it's a whole vibe, no cap. 🦋

✨ SYNOPSIS ✨

#include <embree3/rtcore.h>

RTCGeometry geometry =
   rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE);

🌸 DESCRIPTION 🌸

So Embree does instancing of scenes using affine transformations — that's a 3×3 matrix plus translation, periodt. And the way the instanced scene is stored only a single time, even when you drop it into a bunch of different locations? It's giving main character energy fr — you can build ridiculously complex scenes with a small memory footprint. Obsessed. 💅

Embree serves both single-level instancing and multi-level instancing, because of course it does. The maximum instance nesting depth is RTC_MAX_INSTANCE_LEVEL_COUNT, and you can configure it at compile-time with the constant EMBREE_MAX_INSTANCE_LEVEL_COUNT. Bestie, adapt that constant to your needs, okay? Because instances nested any deeper are silently ignored in release mode, and they cause assertions in debug mode. Not dramatic, just true. 😭

Instances get created by passing RTC_GEOMETRY_TYPE_INSTANCE to the rtcNewGeometry function call. The instanced scene itself? Set that with rtcSetGeometryInstancedScene. And the affine transformation? That's rtcSetGeometryTransform. Slay. ✨

🫶 Order matters here, bestie — 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. That's the sequence. No skipping steps, iykyk.

If 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. The way it just knows where everything came from 😌

The instancing scheme can also be implemented using user geometries. To do that, your user geometry code should set the instID member of the intersection context to the geometry ID of the instance, then trace the transformed ray, and finally set the instID field of the intersection context back 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. There's a whole example in the [User Geometry] tutorial if you wanna see it in the wild. 🌈

For multi-segment motion blur, the number of time steps has to be specified first using the rtcSetGeometryTimeStepCount function. Then a transformation for each time step can be specified using the rtcSetGeometryTransform function. Cute, right? 🎀

And if you want actual examples of how to use instances, go look at the [Instanced Geometry] and [Multi Level Instancing] tutorials. They ate. 🔥

💀 EXIT STATUS 💀

On failure NULL is returned and an error code is set that you can query using rtcGetDeviceError. So if something's giving nothing back, check the error code before you spiral, bestie. 🙈

👑 SEE ALSO 👑

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

and that's the whole page, babe 💖 this was RTC_GEOME..._INSTANCE(3) from the Embree Ray Tracing Kernels 3 manual set — go forth and instance responsibly. bye bestie, you got this 🎀✨🦋💜