rtcNewSharedBuffer(3)

💖 rtcNewSharedBuffer — bestie edition 💖

okay so this is a page from the Embree Ray Tracing Kernels 3 manual, and today we're talking about rtcNewSharedBuffer, which lowkey is the moment you tell Embree "hey, I already have my own buffer, just use mine, don't allocate anything new." it's giving teamwork. it's giving trust. 🫶

✨ NAME ✨

rtcNewSharedBuffer — creates a new shared data buffer 🌸

🎀 SYNOPSIS 🎀

#include <embree3/rtcore.h>

RTCBuffer rtcNewSharedBuffer(
  RTCDevice device,
  void* ptr,
  size_t byteSize
);

🦋 DESCRIPTION 🦋

so rtcNewSharedBuffer creates a brand new shared data buffer object, and it's bound to the device you pass in (the device argument). 💫

the buffer object is reference counted, and it starts its life with an initial reference count of 1. when you're done with it, you release it with the rtcReleaseBuffer function. bye bestie 👋

at construction time, you hand over the pointer to the user-managed buffer data (the ptr argument) plus its size in bytes (the byteSize argument), and that's what creates the buffer. and here's the iconic part: at buffer construction time no buffer data is allocated at all — Embree just uses the buffer data your application already provided. main character energy, honestly. 👑

⚠️ but listen: the buffer data must remain valid for as long as the buffer may be used, and you (yes, you, the user) are responsible for freeing the buffer data when it's no longer required. Embree is not your cleanup crew, bestie. 😭

the data pointer (the ptr argument) must be aligned to 4 bytes. if it's not? the rtcNewSharedBuffer function will fail. no cap, no wiggle room, it just fails. 💀

🌈 EXIT STATUS 🌈

on failure, NULL is returned and an error code is set that you can query using rtcGetDeviceError. so like, if you get NULL, go check that error code, that's where the tea is. 🍓

👑 SEE ALSO 👑

• [rtcRetainBuffer]
• [rtcReleaseBuffer]

and that's the whole page, fr fr 💅 that was rtcNewSharedBuffer from the Embree Ray Tracing Kernels 3 manual, page dated like the rtcNewSharedBuffer(3) footer says — go forth and align your pointers to 4 bytes, bestie, I believe in you 🧚✨💜