SDL_OpenCamera(3)

💖 SDL_OpenCamera(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS page for SDL_OpenCamera — yes, we're opening a video recording device (a "camera") 📸✨

---

✨ NAME ✨

SDL_OpenCamera — open a video recording device (a "camera"). no cap, that's the whole job 🎀

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_camera.h>

SDL_Camera * SDL_OpenCamera(SDL_CameraID instance_id, const SDL_CameraSpec *spec);

---

🌸 DESCRIPTION 🌸

so here's the tea ☕ — you can open the device with any reasonable spec, and if the hardware can't directly support it, it will convert data seamlessly to the requested format. lowkey slay, but heads up: this might incur overhead, including scaling of image data. it's giving "we did it but we worked for it" 💅

if you would rather just accept whatever format the device offers, you can pass a NULL spec here and it will choose one for you (and you can use SDL_Surface's conversion/scaling functions directly if necessary). main character energy: let the device decide 🫶

you can call SDL_GetCameraFormat() to get the actual data format if passing a NULL spec here. and if you wanna see the exact specs a device can support without conversion, that's SDL_GetCameraSupportedFormats() ✨

SDL will not attempt to emulate framerate. it will try to set the hardware to the rate closest to the requested speed, but it won't attempt to limit or duplicate frames artificially. so call SDL_GetCameraFormat() to see the actual framerate of the opened the device, and check your timestamps if this is crucial to your app! ⏱️ not me warning you twice, but like, do it 😭

🚨 IMPORTANT BESTIE 🚨 note that the camera is not usable until the user approves its use! on some platforms, the operating system will prompt the user to permit access to the camera, and they can choose Yes or No at that point. until they do, the camera will not be usable. the app should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_GetCameraPermissionState() occasionally until it returns non-zero. on platforms that don't require explicit user approval (and perhaps in places where the user previously permitted access), the approval event might come immediately, but it might come seconds, minutes, or hours later! 💀 like, hours. fr fr.

---

🎀 FUNCTION PARAMETERS 🎀

• instance_id — the camera device instance ID. 👑
• spec — the desired format for data the device will provide. Can be NULL. 🙈

---

⭐ RETURN VALUE ⭐

returns an SDL_Camera object, or NULL on failure 🥲 — call SDL_GetError() for more information. (iykyk, always check the error.)

---

🧚 THREAD SAFETY 🧚

it is safe to call this function from any thread. go off, multithreaded queen 👑

---

🌈 AVAILABILITY 🌈

this function is available since SDL 3.2.0 ✨

---

💜 SEE ALSO 💜

• SDL_GetCameras(3)
• SDL_GetCameraFormat(3)

---

and that's the whole page, bestie!! 🫶 this lil' beauty comes to you from Simple Directmedia Layer, version SDL 3.4.18 — mwah, obsessed, periodt 💅🎀🦋