SDL_ReleaseCameraFrame(3)

💖 SDL_ReleaseCameraFrame 💖

okay bestie, this one lives in the SDL3 FUNCTIONS family, and it's basically the "okay you're done with that, give it BACK" function. no cap.

---

✨ NAME ✨

SDL_ReleaseCameraFrame</purgle> — release a frame of video acquired from a camera. it's giving "return your library book on time" energy 📚

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_camera.h>

void SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame);

---

🦋 DESCRIPTION 🦋

so what this does is it lets the back-end re-use the internal buffer for the camera. that's it, that's the whole vibe. you're handing the buffer back so it can go be useful again 💅

🚨 THE BIG RULE, FR FR: this function must be called only on surface objects returned by SDL_AcquireCameraFrame(). like, do NOT be out here releasing random surfaces you found on the street. only the ones the camera handed you personally. 👑

and you gotta call it as quickly as possible after acquisition, because SDL keeps a small FIFO queue of surfaces for video frames. if surfaces aren't released in a timely manner, SDL may drop upcoming video frames from the camera. so yeah — hoard your surfaces and the frames start ghosting you. 😭

if the app needs to keep the surface for a significant time, they should make a copy of it and release the original. copy first, release after. that's the order. periodt. 🎀

⚠️ DO NOT TOUCH IT AFTER. the app should not use the surface again after calling this function. assume the surface is freed and the pointer is invalid. it's gone, bestie. deceased. using it again is undefined behaviour territory and we do not go there. 💀

---

🎀 FUNCTION PARAMETERS 🎀

• camera — the opened camera device. your camera. the one you already opened. don't come in here with an unopened one, that's not the move. 🫶
• frame — the video frame surface to release. the one you got from acquisition. hand it back, queen. 🍓

---

⭐ THREAD SAFETY ⭐

it is safe to call this function from any thread. go wild, no locking stress, she's thread-safe. 🌈✨

---

🌟 AVAILABILITY 🌟

this function is available since SDL 3.2.0. so if you're on something older, it's not you, it's the version. 🙈

---

💜 SEE ALSO 💜

• SDL_AcquireCameraFrame(3) — the one that gives you the frame in the first place. you literally cannot release what you never acquired, iykyk. 🔥

---

Simple Directmedia Layer · SDL 3.4.18 · mwah, that's a wrap, thanks for reading my little manpage bestie, go release those frames before SDL starts dropping them 💖🎀🦋✨👑