RTC_GEOME...NCE_ARRAY(3)

✨ NAME ✨

RTC_GEOMETRY_TYPE_INSTANCE_ARRAY — the instance array geometry type, and she is that girl 💅

Welcome to the Embree Ray Tracing Kernels 4 page for RTC_GEOME...NCE_ARRAY(3), bestie. Buckle up. 🎀

---

🌸 SYNOPSIS 🌸

#include <embree4/rtcore.h>

RTCGeometry geometry =
   rtcNewGeometry(device, RTC_GEOMETRY_TYPE_INSTANCE_ARRAY);

---

🦋 DESCRIPTION 🦋

okay so. Embree supports instance arrays, which is literally the more memory efficient way to represent large amounts of instances of the same (sub)scene, or of a small set of (sub)scenes. glow-up for your memory budget, no cap ✨

The main difference from regular Embree instances? Regular instances could never. Instance arrays have a buffer of transformations — either affine transformations or quaternion decompositions [RTCQuaternionDecomposition] — and that buffer can be allocated by Embree or be a shared buffer, just like vertex buffers for triangle meshes. 🫶

And optionally — not me adding features — instead of instancing only one scene, an instance array can instance multiple scenes by passing an array of scenes plus a corresponding index buffer. That index buffer specifies which instance of the instance array instances which of the scenes in the scenes array. iykyk 💜

🎀 how you actually make one

You create instance arrays by passing RTC_GEOMETRY_TYPE_INSTANCE_ARRAY to the rtcNewGeometry function call. Then the instanced scene can be:

• set using the rtcSetGeometryInstancedScene call, or
• if multiple scenes should be instanced, set by passing an array of scenes using rtcSetGeometryInstancedScenes.

That second option also requires you to specify an index buffer using rtcSetNewGeometryBuffer or rtcSetSharedGeometryBuffer, with RTC_BUFFER_TYPE_INDEX as the buffer type. periodt. 💅

💖 the transformation buffer situation

Because the transformation information can become large for a large amount of instances, the instance array lets you share the transformation buffer between the user application and Embree. It can be:

• stored in a buffer created by Embree with rtcSetNewGeometryBuffer, or
• an already existing buffer that you share using rtcSetSharedGeometryBuffer.

Either way, 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
• RTC_FORMAT_QUATERNION_DECOMPOSITION

And listen: Embree will not modify the data in the transformation buffer. your buffer, your rules 🧚

🌈 instancing levels, the vibe check

Embree instance arrays support both single-level instancing and multi-level instancing. The maximum instance nesting depth is RTC_MAX_INSTANCE_LEVEL_COUNT, and you can configure it at compile-time using the constant EMBREE_MAX_INSTANCE_LEVEL_COUNT.

Users should adapt this constant to their needs, because:

instances nested any deeper are silently ignored in release mode, and cause assertions in debug mode. 😭 literally not a drill.

⭐ the commit order (do NOT freestyle this)

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. in exactly that order. that's the whole choreography. 👑

🔥 what a hit actually gives you

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.
• the instPrimID member is set to the index of the hit instance of the instance array.

🧚 multi-segment motion blur

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, passing the time step as the slot parameter of these calls. slay. 💅

Also, 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. so check it, bestie, don't just assume it worked 🙈

---

👑 SEE ALSO 👑

• [rtcNewGeometry]
• [rtcSetGeometryInstancedScene]
• [rtcSetGeometryInstancedScenes]
• [rtcSetNewGeometryBuffer]
• [rtcSetSharedGeometryBuffer]
• [rtcGetGeometryTransformEx]

---

and that's the page, babes 💖 this was RTC_GEOME...NCE_ARRAY(3) straight out of Embree Ray Tracing Kernels 4 — go forth and instance responsibly, mwah 🎀✨