1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategoryCamera
24 *
25 * Video capture for the SDL library.
26 *
27 * This API lets apps read input from video sources, like webcams. Camera
28 * devices can be enumerated, queried, and opened. Once opened, it will
29 * provide SDL_Surface objects as new frames of video come in. These surfaces
30 * can be uploaded to an SDL_Texture or processed as pixels in memory.
31 *
32 * Several platforms will alert the user if an app tries to access a camera,
33 * and some will present a UI asking the user if your application should be
34 * allowed to obtain images at all, which they can deny. A successfully opened
35 * camera will not provide images until permission is granted. Applications,
36 * after opening a camera device, can see if they were granted access by
37 * either polling with the SDL_GetCameraPermissionState() function, or waiting
38 * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED
39 * event. Platforms that don't have any user approval process will report
40 * approval immediately.
41 *
42 * Note that SDL cameras only provide video as individual frames; they will
43 * not provide full-motion video encoded in a movie file format, although an
44 * app is free to encode the acquired frames into any format it likes. It also
45 * does not provide audio from the camera hardware through this API; not only
46 * do many webcams not have microphones at all, many people--from streamers to
47 * people on Zoom calls--will want to use a separate microphone regardless of
48 * the camera. In any case, recorded audio will be available through SDL's
49 * audio API no matter what hardware provides the microphone.
50 *
51 * ## Camera gotchas
52 *
53 * Consumer-level camera hardware tends to take a little while to warm up,
54 * once the device has been opened. Generally most camera apps have some sort
55 * of UI to take a picture (a button to snap a pic while a preview is showing,
56 * some sort of multi-second countdown for the user to pose, like a photo
57 * booth), which puts control in the users' hands, or they are intended to
58 * stay on for long times (Pokemon Go, etc).
59 *
60 * It's not uncommon that a newly-opened camera will provide a couple of
61 * completely black frames, maybe followed by some under-exposed images. If
62 * taking a single frame automatically, or recording video from a camera's
63 * input without the user initiating it from a preview, it could be wise to
64 * drop the first several frames (if not the first several _seconds_ worth of
65 * frames!) before using images from a camera.
66 */
67
68#ifndef SDL_camera_h_
69#define SDL_camera_h_
70
71#include <SDL3/SDL_stdinc.h>
72#include <SDL3/SDL_error.h>
73#include <SDL3/SDL_pixels.h>
74#include <SDL3/SDL_properties.h>
75#include <SDL3/SDL_surface.h>
76
77#include <SDL3/SDL_begin_code.h>
78/* Set up for C function definitions, even when using C++ */
79#ifdef __cplusplus
80extern "C" {
81#endif
82
83/**
84 * This is a unique ID for a camera device for the time it is connected to the
85 * system, and is never reused for the lifetime of the application.
86 *
87 * If the device is disconnected and reconnected, it will get a new ID.
88 *
89 * The value 0 is an invalid ID.
90 *
91 * \since This datatype is available since SDL 3.2.0.
92 *
93 * \sa SDL_GetCameras
94 */
95typedef Uint32 SDL_CameraID;
96
97/**
98 * The opaque structure used to identify an opened SDL camera.
99 *
100 * \since This struct is available since SDL 3.2.0.
101 */
102typedef struct SDL_Camera SDL_Camera;
103
104/**
105 * The details of an output format for a camera device.
106 *
107 * Cameras often support multiple formats; each one will be encapsulated in
108 * this struct.
109 *
110 * \since This struct is available since SDL 3.2.0.
111 *
112 * \sa SDL_GetCameraSupportedFormats
113 * \sa SDL_GetCameraFormat
114 */
115typedef struct SDL_CameraSpec
116{
117 SDL_PixelFormat format; /**< Frame format */
118 SDL_Colorspace colorspace; /**< Frame colorspace */
119 int width; /**< Frame width */
120 int height; /**< Frame height */
121 int framerate_numerator; /**< Frame rate numerator ((num / denom) == FPS, (denom / num) == duration in seconds) */
122 int framerate_denominator; /**< Frame rate demoninator ((num / denom) == FPS, (denom / num) == duration in seconds) */
123} SDL_CameraSpec;
124
125/**
126 * The position of camera in relation to system device.
127 *
128 * \since This enum is available since SDL 3.2.0.
129 *
130 * \sa SDL_GetCameraPosition
131 */
132typedef enum SDL_CameraPosition
133{
134 SDL_CAMERA_POSITION_UNKNOWN,
135 SDL_CAMERA_POSITION_FRONT_FACING,
136 SDL_CAMERA_POSITION_BACK_FACING
137} SDL_CameraPosition;
138
139
140/**
141 * Use this function to get the number of built-in camera drivers.
142 *
143 * This function returns a hardcoded number. This never returns a negative
144 * value; if there are no drivers compiled into this build of SDL, this
145 * function returns zero. The presence of a driver in this list does not mean
146 * it will function, it just means SDL is capable of interacting with that
147 * interface. For example, a build of SDL might have v4l2 support, but if
148 * there's no kernel support available, SDL's v4l2 driver would fail if used.
149 *
150 * By default, SDL tries all drivers, in its preferred order, until one is
151 * found to be usable.
152 *
153 * \returns the number of built-in camera drivers.
154 *
155 * \threadsafety It is safe to call this function from any thread.
156 *
157 * \since This function is available since SDL 3.2.0.
158 *
159 * \sa SDL_GetCameraDriver
160 */
161extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
162
163/**
164 * Use this function to get the name of a built in camera driver.
165 *
166 * The list of camera drivers is given in the order that they are normally
167 * initialized by default; the drivers that seem more reasonable to choose
168 * first (as far as the SDL developers believe) are earlier in the list.
169 *
170 * The names of drivers are all simple, low-ASCII identifiers, like "v4l2",
171 * "coremedia" or "android". These never have Unicode characters, and are not
172 * meant to be proper names.
173 *
174 * \param index the index of the camera driver; the value ranges from 0 to
175 * SDL_GetNumCameraDrivers() - 1.
176 * \returns the name of the camera driver at the requested index, or NULL if
177 * an invalid index was specified.
178 *
179 * \threadsafety It is safe to call this function from any thread.
180 *
181 * \since This function is available since SDL 3.2.0.
182 *
183 * \sa SDL_GetNumCameraDrivers
184 */
185extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index);
186
187/**
188 * Get the name of the current camera driver.
189 *
190 * The names of drivers are all simple, low-ASCII identifiers, like "v4l2",
191 * "coremedia" or "android". These never have Unicode characters, and are not
192 * meant to be proper names.
193 *
194 * \returns the name of the current camera driver or NULL if no driver has
195 * been initialized.
196 *
197 * \threadsafety It is safe to call this function from any thread.
198 *
199 * \since This function is available since SDL 3.2.0.
200 */
201extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
202
203/**
204 * Get a list of currently connected camera devices.
205 *
206 * \param count a pointer filled in with the number of cameras returned, may
207 * be NULL.
208 * \returns a 0 terminated array of camera instance IDs or NULL on failure;
209 * call SDL_GetError() for more information. This should be freed
210 * with SDL_free() when it is no longer needed.
211 *
212 * \threadsafety It is safe to call this function from any thread.
213 *
214 * \since This function is available since SDL 3.2.0.
215 *
216 * \sa SDL_OpenCamera
217 */
218extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
219
220/**
221 * Get the list of native formats/sizes a camera supports.
222 *
223 * This returns a list of all formats and frame sizes that a specific camera
224 * can offer. This is useful if your app can accept a variety of image formats
225 * and sizes and so want to find the optimal spec that doesn't require
226 * conversion.
227 *
228 * This function isn't strictly required; if you call SDL_OpenCamera with a
229 * NULL spec, SDL will choose a native format for you, and if you instead
230 * specify a desired format, it will transparently convert to the requested
231 * format on your behalf.
232 *
233 * If `count` is not NULL, it will be filled with the number of elements in
234 * the returned array.
235 *
236 * Note that it's legal for a camera to supply an empty list. This is what
237 * will happen on Emscripten builds, since that platform won't tell _anything_
238 * about available cameras until you've opened one, and won't even tell if
239 * there _is_ a camera until the user has given you permission to check
240 * through a scary warning popup.
241 *
242 * \param instance_id the camera device instance ID.
243 * \param count a pointer filled in with the number of elements in the list,
244 * may be NULL.
245 * \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on
246 * failure; call SDL_GetError() for more information. This is a
247 * single allocation that should be freed with SDL_free() when it is
248 * no longer needed.
249 *
250 * \threadsafety It is safe to call this function from any thread.
251 *
252 * \since This function is available since SDL 3.2.0.
253 *
254 * \sa SDL_GetCameras
255 * \sa SDL_OpenCamera
256 */
257extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID instance_id, int *count);
258
259/**
260 * Get the human-readable device name for a camera.
261 *
262 * \param instance_id the camera device instance ID.
263 * \returns a human-readable device name or NULL on failure; call
264 * SDL_GetError() for more information.
265 *
266 * \threadsafety It is safe to call this function from any thread.
267 *
268 * \since This function is available since SDL 3.2.0.
269 *
270 * \sa SDL_GetCameras
271 */
272extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance_id);
273
274/**
275 * Get the position of the camera in relation to the system.
276 *
277 * Most platforms will report UNKNOWN, but mobile devices, like phones, can
278 * often make a distinction between cameras on the front of the device (that
279 * points towards the user, for taking "selfies") and cameras on the back (for
280 * filming in the direction the user is facing).
281 *
282 * \param instance_id the camera device instance ID.
283 * \returns the position of the camera on the system hardware.
284 *
285 * \threadsafety It is safe to call this function from any thread.
286 *
287 * \since This function is available since SDL 3.2.0.
288 *
289 * \sa SDL_GetCameras
290 */
291extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraID instance_id);
292
293/**
294 * Open a video recording device (a "camera").
295 *
296 * You can open the device with any reasonable spec, and if the hardware can't
297 * directly support it, it will convert data seamlessly to the requested
298 * format. This might incur overhead, including scaling of image data.
299 *
300 * If you would rather accept whatever format the device offers, you can pass
301 * a NULL spec here and it will choose one for you (and you can use
302 * SDL_Surface's conversion/scaling functions directly if necessary).
303 *
304 * You can call SDL_GetCameraFormat() to get the actual data format if passing
305 * a NULL spec here. You can see the exact specs a device can support without
306 * conversion with SDL_GetCameraSupportedFormats().
307 *
308 * SDL will not attempt to emulate framerate; it will try to set the hardware
309 * to the rate closest to the requested speed, but it won't attempt to limit
310 * or duplicate frames artificially; call SDL_GetCameraFormat() to see the
311 * actual framerate of the opened the device, and check your timestamps if
312 * this is crucial to your app!
313 *
314 * Note that the camera is not usable until the user approves its use! On some
315 * platforms, the operating system will prompt the user to permit access to
316 * the camera, and they can choose Yes or No at that point. Until they do, the
317 * camera will not be usable. The app should either wait for an
318 * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event,
319 * or poll SDL_GetCameraPermissionState() occasionally until it returns
320 * non-zero. On platforms that don't require explicit user approval (and
321 * perhaps in places where the user previously permitted access), the approval
322 * event might come immediately, but it might come seconds, minutes, or hours
323 * later!
324 *
325 * \param instance_id the camera device instance ID.
326 * \param spec the desired format for data the device will provide. Can be
327 * NULL.
328 * \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for
329 * more information.
330 *
331 * \threadsafety It is safe to call this function from any thread.
332 *
333 * \since This function is available since SDL 3.2.0.
334 *
335 * \sa SDL_GetCameras
336 * \sa SDL_GetCameraFormat
337 */
338extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id, const SDL_CameraSpec *spec);
339
340/**
341 * Query if camera access has been approved by the user.
342 *
343 * Cameras will not function between when the device is opened by the app and
344 * when the user permits access to the hardware. On some platforms, this
345 * presents as a popup dialog where the user has to explicitly approve access;
346 * on others the approval might be implicit and not alert the user at all.
347 *
348 * This function can be used to check the status of that approval. It will
349 * return 0 if still waiting for user response, 1 if the camera is approved
350 * for use, and -1 if the user denied access.
351 *
352 * Instead of polling with this function, you can wait for a
353 * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event
354 * in the standard SDL event loop, which is guaranteed to be sent once when
355 * permission to use the camera is decided.
356 *
357 * If a camera is declined, there's nothing to be done but call
358 * SDL_CloseCamera() to dispose of it.
359 *
360 * \param camera the opened camera device to query.
361 * \returns -1 if user denied access to the camera, 1 if user approved access,
362 * 0 if no decision has been made yet.
363 *
364 * \threadsafety It is safe to call this function from any thread.
365 *
366 * \since This function is available since SDL 3.2.0.
367 *
368 * \sa SDL_OpenCamera
369 * \sa SDL_CloseCamera
370 */
371extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera);
372
373/**
374 * Get the instance ID of an opened camera.
375 *
376 * \param camera an SDL_Camera to query.
377 * \returns the instance ID of the specified camera on success or 0 on
378 * failure; call SDL_GetError() for more information.
379 *
380 * \threadsafety It is safe to call this function from any thread.
381 *
382 * \since This function is available since SDL 3.2.0.
383 *
384 * \sa SDL_OpenCamera
385 */
386extern SDL_DECLSPEC SDL_CameraID SDLCALL SDL_GetCameraID(SDL_Camera *camera);
387
388/**
389 * Get the properties associated with an opened camera.
390 *
391 * \param camera the SDL_Camera obtained from SDL_OpenCamera().
392 * \returns a valid property ID on success or 0 on failure; call
393 * SDL_GetError() for more information.
394 *
395 * \threadsafety It is safe to call this function from any thread.
396 *
397 * \since This function is available since SDL 3.2.0.
398 */
399extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera);
400
401/**
402 * Get the spec that a camera is using when generating images.
403 *
404 * Note that this might not be the native format of the hardware, as SDL might
405 * be converting to this format behind the scenes.
406 *
407 * If the system is waiting for the user to approve access to the camera, as
408 * some platforms require, this will return false, but this isn't necessarily
409 * a fatal error; you should either wait for an
410 * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event,
411 * or poll SDL_GetCameraPermissionState() occasionally until it returns
412 * non-zero.
413 *
414 * \param camera opened camera device.
415 * \param spec the SDL_CameraSpec to be initialized by this function.
416 * \returns true on success or false on failure; call SDL_GetError() for more
417 * information.
418 *
419 * \threadsafety It is safe to call this function from any thread.
420 *
421 * \since This function is available since SDL 3.2.0.
422 *
423 * \sa SDL_OpenCamera
424 */
425extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec);
426
427/**
428 * Acquire a frame.
429 *
430 * The frame is a memory pointer to the image data, whose size and format are
431 * given by the spec requested when opening the device.
432 *
433 * This is a non blocking API. If there is a frame available, a non-NULL
434 * surface is returned, and timestampNS will be filled with a non-zero value.
435 *
436 * Note that an error case can also return NULL, but a NULL by itself is
437 * normal and just signifies that a new frame is not yet available. Note that
438 * even if a camera device fails outright (a USB camera is unplugged while in
439 * use, etc), SDL will send an event separately to notify the app, but
440 * continue to provide blank frames at ongoing intervals until
441 * SDL_CloseCamera() is called, so real failure here is almost always an out
442 * of memory condition.
443 *
444 * After use, the frame should be released with SDL_ReleaseCameraFrame(). If
445 * you don't do this, the system may stop providing more video!
446 *
447 * Do not call SDL_DestroySurface() on the returned surface! It must be given
448 * back to the camera subsystem with SDL_ReleaseCameraFrame!
449 *
450 * If the system is waiting for the user to approve access to the camera, as
451 * some platforms require, this will return NULL (no frames available); you
452 * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or
453 * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll
454 * SDL_GetCameraPermissionState() occasionally until it returns non-zero.
455 *
456 * \param camera opened camera device.
457 * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
458 * error. Can be NULL.
459 * \returns a new frame of video on success, NULL if none is currently
460 * available.
461 *
462 * \threadsafety It is safe to call this function from any thread.
463 *
464 * \since This function is available since SDL 3.2.0.
465 *
466 * \sa SDL_ReleaseCameraFrame
467 */
468extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS);
469
470/**
471 * Release a frame of video acquired from a camera.
472 *
473 * Let the back-end re-use the internal buffer for camera.
474 *
475 * This function _must_ be called only on surface objects returned by
476 * SDL_AcquireCameraFrame(). This function should be called as quickly as
477 * possible after acquisition, as SDL keeps a small FIFO queue of surfaces for
478 * video frames; if surfaces aren't released in a timely manner, SDL may drop
479 * upcoming video frames from the camera.
480 *
481 * If the app needs to keep the surface for a significant time, they should
482 * make a copy of it and release the original.
483 *
484 * The app should not use the surface again after calling this function;
485 * assume the surface is freed and the pointer is invalid.
486 *
487 * \param camera opened camera device.
488 * \param frame the video frame surface to release.
489 *
490 * \threadsafety It is safe to call this function from any thread.
491 *
492 * \since This function is available since SDL 3.2.0.
493 *
494 * \sa SDL_AcquireCameraFrame
495 */
496extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame);
497
498/**
499 * Use this function to shut down camera processing and close the camera
500 * device.
501 *
502 * \param camera opened camera device.
503 *
504 * \threadsafety It is safe to call this function from any thread, but no
505 * thread may reference `device` once this function is called.
506 *
507 * \since This function is available since SDL 3.2.0.
508 *
509 * \sa SDL_OpenCamera
510 */
511extern SDL_DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera);
512
513/* Ends C function definitions when using C++ */
514#ifdef __cplusplus
515}
516#endif
517#include <SDL3/SDL_close_code.h>
518
519#endif /* SDL_camera_h_ */
520