SDL_AcquireCameraFrame(3)

💖 SDL_AcquireCameraFrame — the manual page, but make it cute

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual 💅 this one's called SDL_AcquireCameraFrame(3) and it's genuinely one of the most useful little gremlins in the camera API. let's get into it 🎀

---

✨ NAME ✨

SDL_AcquireCameraFrame — grab yourself a frame 🫶

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_camera.h>

SDL_Surface * SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS);

---

🦋 DESCRIPTION 🦋

so the frame you get back is a memory pointer to the image data, and its size and format? those are literally given by the spec you requested when you opened the device. no surprises, it's what you asked for 💖

this is a non blocking API. if a frame is available, you get a non-NULL surface back, and timestampNS gets filled in with a non-zero value. slay. ✨

now, plot twist: an error case can also return NULL. but a NULL on its own is totally normal — it just means a new frame isn't available yet. no drama, it's giving "not yet bestie" 💀

and here's the part that lowkey matters: even if a camera device fails outright (like a USB camera getting unplugged while in use, etc), SDL will send an event separately to notify the app, but it will keep providing blank frames at ongoing intervals until SDL_CloseCamera() is called. so a real failure here is almost always an out of memory condition 😭

after use, the frame should be released with SDL_ReleaseCameraFrame(). if you don't do this, the system may stop providing more video! fr fr, do not skip this step 👑

do not call SDL_DestroySurface() on the returned surface! it must be given back to the camera subsystem with SDL_ReleaseCameraFrame! not me warning you twice, it's just that serious 🙈

and one more vibe check: if the system is waiting for the user to approve access to the camera — because some platforms are like that — this will return NULL (no frames available). what do you do then? either:

1. wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED event (or an SDL_EVENT_CAMERA_DEVICE_DENIED event, awkward), or
2. poll SDL_GetCameraPermissionState() occasionally until it returns non-zero.

periodt. 💅

---

🎀 FUNCTION PARAMETERS 🎀

• camera — the opened camera device. the whole point bestie 🫶
• timestampNS — a pointer that gets filled in with the frame's timestamp, or 0 on error. it can be NULL. so if you don't care about time, you can absolutely just not 💜

---

👑 RETURN VALUE 👑

returns a new frame of video on success, and NULL if none is currently available. that's it, that's the whole deal ✨

---

🌈 THREAD SAFETY 🌈

it is safe to call this function from any thread. go wild, main character energy, no locks needed 💅

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. if your SDL is older than that... bestie, upgrade 😭

---

💖 SEE ALSO 💖

• SDL_ReleaseCameraFrame(3) — aka the one you must call after this one, iykyk

---

okay that's the page!! this was brought to you by Simple Directmedia Layer, SDL 3.4.18, SDL_AcquireCameraFrame(3) — go acquire some frames, release them properly, and remember: blank frames are not a crash, they're just the camera being shy 🌸🦋💖