SDL 3.0
SDL_camera.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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 * \file SDL_camera.h
24 *
25 * Video Capture for the SDL library.
26 */
27
28#ifndef SDL_camera_h_
29#define SDL_camera_h_
30
31#include <SDL3/SDL_video.h>
32
33#include <SDL3/SDL_begin_code.h>
34/* Set up for C function definitions, even when using C++ */
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/**
40 * This is a unique ID for a camera device for the time it is connected to the system,
41 * and is never reused for the lifetime of the application. If the device is
42 * disconnected and reconnected, it will get a new ID.
43 *
44 * The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
45 *
46 * \sa SDL_GetCameraDevices
47 */
49
50
51/**
52 * The structure used to identify an opened SDL camera
53 */
54struct SDL_Camera;
55typedef struct SDL_Camera SDL_Camera;
56
57/**
58 * SDL_CameraSpec structure
59 *
60 * \sa SDL_GetCameraDeviceSupportedFormats
61 * \sa SDL_GetCameraFormat
62 *
63 */
64typedef struct SDL_CameraSpec
65{
66 SDL_PixelFormatEnum format; /**< Frame format */
67 int width; /**< Frame width */
68 int height; /**< Frame height */
69 int interval_numerator; /**< Frame rate numerator ((dom / num) == fps, (num / dom) == duration) */
70 int interval_denominator; /**< Frame rate demoninator ((dom / num) == fps, (num / dom) == duration) */
72
73/**
74 * The position of camera in relation to system device.
75 *
76 * \sa SDL_GetCameraDevicePosition
77 */
84
85
86/**
87 * Use this function to get the number of built-in camera drivers.
88 *
89 * This function returns a hardcoded number. This never returns a negative
90 * value; if there are no drivers compiled into this build of SDL, this
91 * function returns zero. The presence of a driver in this list does not mean
92 * it will function, it just means SDL is capable of interacting with that
93 * interface. For example, a build of SDL might have v4l2 support, but if
94 * there's no kernel support available, SDL's v4l2 driver would fail if used.
95 *
96 * By default, SDL tries all drivers, in its preferred order, until one is
97 * found to be usable.
98 *
99 * \returns the number of built-in camera drivers.
100 *
101 * \threadsafety It is safe to call this function from any thread.
102 *
103 * \since This function is available since SDL 3.0.0.
104 *
105 * \sa SDL_GetCameraDriver
106 */
107extern DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
108
109/**
110 * Use this function to get the name of a built in camera driver.
111 *
112 * The list of camera drivers is given in the order that they are normally
113 * initialized by default; the drivers that seem more reasonable to choose
114 * first (as far as the SDL developers believe) are earlier in the list.
115 *
116 * The names of drivers are all simple, low-ASCII identifiers, like "v4l2",
117 * "coremedia" or "android". These never have Unicode characters, and are not
118 * meant to be proper names.
119 *
120 * \param index the index of the camera driver; the value ranges from 0 to
121 * SDL_GetNumCameraDrivers() - 1
122 * \returns the name of the camera driver at the requested index, or NULL if
123 * an invalid index was specified.
124 *
125 * \threadsafety It is safe to call this function from any thread.
126 *
127 * \since This function is available since SDL 3.0.0.
128 *
129 * \sa SDL_GetNumCameraDrivers
130 */
131extern DECLSPEC const char *SDLCALL SDL_GetCameraDriver(int index);
132
133/**
134 * Get the name of the current camera driver.
135 *
136 * The returned string points to internal static memory and thus never becomes
137 * invalid, even if you quit the camera subsystem and initialize a new driver
138 * (although such a case would return a different static string from another
139 * call to this function, of course). As such, you should not modify or free
140 * the returned string.
141 *
142 * \returns the name of the current camera driver or NULL if no driver has
143 * been initialized.
144 *
145 * \threadsafety It is safe to call this function from any thread.
146 *
147 * \since This function is available since SDL 3.0.0.
148 */
149extern DECLSPEC const char *SDLCALL SDL_GetCurrentCameraDriver(void);
150
151/**
152 * Get a list of currently connected camera devices.
153 *
154 * \param count a pointer filled in with the number of camera devices. Can be
155 * NULL.
156 * \returns a 0 terminated array of camera instance IDs which should be freed
157 * with SDL_free(), or NULL on error; call SDL_GetError() for more
158 * details.
159 *
160 * \threadsafety It is safe to call this function from any thread.
161 *
162 * \since This function is available since SDL 3.0.0.
163 *
164 * \sa SDL_OpenCamera
165 */
166extern DECLSPEC SDL_CameraDeviceID *SDLCALL SDL_GetCameraDevices(int *count);
167
168/**
169 * Get the list of native formats/sizes a camera supports.
170 *
171 * This returns a list of all formats and frame sizes that a specific camera
172 * can offer. This is useful if your app can accept a variety of image formats
173 * and sizes and so want to find the optimal spec that doesn't require
174 * conversion.
175 *
176 * This function isn't strictly required; if you call SDL_OpenCameraDevice
177 * with a NULL spec, SDL will choose a native format for you, and if you
178 * instead specify a desired format, it will transparently convert to the
179 * requested format on your behalf.
180 *
181 * If `count` is not NULL, it will be filled with the number of elements in
182 * the returned array. Additionally, the last element of the array has all
183 * fields set to zero (this element is not included in `count`).
184 *
185 * The returned list is owned by the caller, and should be released with
186 * SDL_free() when no longer needed.
187 *
188 * Note that it's legal for a camera to supply a list with only the zeroed
189 * final element and `*count` set to zero; this is what will happen on
190 * Emscripten builds, since that platform won't tell _anything_ about
191 * available cameras until you've opened one, and won't even tell if there
192 * _is_ a camera until the user has given you permission to check through a
193 * scary warning popup.
194 *
195 * \param devid the camera device instance ID to query.
196 * \param count a pointer filled in with the number of elements in the list.
197 * Can be NULL.
198 * \returns a 0 terminated array of SDL_CameraSpecs, which should be freed
199 * with SDL_free(), or NULL on error; call SDL_GetError() for more
200 * details.
201 *
202 * \threadsafety It is safe to call this function from any thread.
203 *
204 * \since This function is available since SDL 3.0.0.
205 *
206 * \sa SDL_GetCameraDevices
207 * \sa SDL_OpenCameraDevice
208 */
210
211/**
212 * Get human-readable device name for a camera.
213 *
214 * The returned string is owned by the caller; please release it with
215 * SDL_free() when done with it.
216 *
217 * \param instance_id the camera device instance ID
218 * \returns Human-readable device name, or NULL on error; call SDL_GetError()
219 * for more information.
220 *
221 * \threadsafety It is safe to call this function from any thread.
222 *
223 * \since This function is available since SDL 3.0.0.
224 *
225 * \sa SDL_GetCameraDevices
226 */
227extern DECLSPEC char * SDLCALL SDL_GetCameraDeviceName(SDL_CameraDeviceID instance_id);
228
229/**
230 * Get the position of the camera in relation to the system.
231 *
232 * Most platforms will report UNKNOWN, but mobile devices, like phones, can
233 * often make a distiction between cameras on the front of the device (that
234 * points towards the user, for taking "selfies") and cameras on the back (for
235 * filming in the direction the user is facing).
236 *
237 * \param instance_id the camera device instance ID
238 * \returns The position of the camera on the system hardware.
239 *
240 * \threadsafety It is safe to call this function from any thread.
241 *
242 * \since This function is available since SDL 3.0.0.
243 *
244 * \sa SDL_GetCameraDevices
245 */
247
248/**
249 * Open a video capture device (a "camera").
250 *
251 * You can open the device with any reasonable spec, and if the hardware can't
252 * directly support it, it will convert data seamlessly to the requested
253 * format. This might incur overhead, including scaling of image data.
254 *
255 * If you would rather accept whatever format the device offers, you can pass
256 * a NULL spec here and it will choose one for you (and you can use
257 * SDL_Surface's conversion/scaling functions directly if necessary).
258 *
259 * You can call SDL_GetCameraFormat() to get the actual data format if passing
260 * a NULL spec here. You can see the exact specs a device can support without
261 * conversion with SDL_GetCameraSupportedSpecs().
262 *
263 * SDL will not attempt to emulate framerate; it will try to set the hardware
264 * to the rate closest to the requested speed, but it won't attempt to limit
265 * or duplicate frames artificially; call SDL_GetCameraFormat() to see the
266 * actual framerate of the opened the device, and check your timestamps if
267 * this is crucial to your app!
268 *
269 * Note that the camera is not usable until the user approves its use! On some
270 * platforms, the operating system will prompt the user to permit access to
271 * the camera, and they can choose Yes or No at that point. Until they do, the
272 * camera will not be usable. The app should either wait for an
273 * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event,
274 * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On
275 * platforms that don't require explicit user approval (and perhaps in places
276 * where the user previously permitted access), the approval event might come
277 * immediately, but it might come seconds, minutes, or hours later!
278 *
279 * \param instance_id the camera device instance ID
280 * \param spec The desired format for data the device will provide. Can be
281 * NULL.
282 * \returns device, or NULL on failure; call SDL_GetError() for more
283 * information.
284 *
285 * \threadsafety It is safe to call this function from any thread.
286 *
287 * \since This function is available since SDL 3.0.0.
288 *
289 * \sa SDL_GetCameraDevices
290 * \sa SDL_GetCameraFormat
291 */
292extern DECLSPEC SDL_Camera *SDLCALL SDL_OpenCameraDevice(SDL_CameraDeviceID instance_id, const SDL_CameraSpec *spec);
293
294/**
295 * Query if camera access has been approved by the user.
296 *
297 * Cameras will not function between when the device is opened by the app and
298 * when the user permits access to the hardware. On some platforms, this
299 * presents as a popup dialog where the user has to explicitly approve access;
300 * on others the approval might be implicit and not alert the user at all.
301 *
302 * This function can be used to check the status of that approval. It will
303 * return 0 if still waiting for user response, 1 if the camera is approved
304 * for use, and -1 if the user denied access.
305 *
306 * Instead of polling with this function, you can wait for a
307 * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event
308 * in the standard SDL event loop, which is guaranteed to be sent once when
309 * permission to use the camera is decided.
310 *
311 * If a camera is declined, there's nothing to be done but call
312 * SDL_CloseCamera() to dispose of it.
313 *
314 * \param camera the opened camera device to query
315 * \returns -1 if user denied access to the camera, 1 if user approved access,
316 * 0 if no decision has been made yet.
317 *
318 * \threadsafety It is safe to call this function from any thread.
319 *
320 * \since This function is available since SDL 3.0.0.
321 *
322 * \sa SDL_OpenCameraDevice
323 * \sa SDL_CloseCamera
324 */
325extern DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera);
326
327/**
328 * Get the instance ID of an opened camera.
329 *
330 * \param camera an SDL_Camera to query
331 * \returns the instance ID of the specified camera on success or 0 on
332 * failure; call SDL_GetError() for more information.
333 *
334 * \threadsafety It is safe to call this function from any thread.
335 *
336 * \since This function is available since SDL 3.0.0.
337 *
338 * \sa SDL_OpenCameraDevice
339 */
341
342/**
343 * Get the properties associated with an opened camera.
344 *
345 * \param camera the SDL_Camera obtained from SDL_OpenCameraDevice()
346 * \returns a valid property ID on success or 0 on failure; call
347 * SDL_GetError() for more information.
348 *
349 * \threadsafety It is safe to call this function from any thread.
350 *
351 * \since This function is available since SDL 3.0.0.
352 *
353 * \sa SDL_GetProperty
354 * \sa SDL_SetProperty
355 */
356extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera);
357
358/**
359 * Get the spec that a camera is using when generating images.
360 *
361 * Note that this might not be the native format of the hardware, as SDL might
362 * be converting to this format behind the scenes.
363 *
364 * If the system is waiting for the user to approve access to the camera, as
365 * some platforms require, this will return -1, but this isn't necessarily a
366 * fatal error; you should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED
367 * (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved()
368 * occasionally until it returns non-zero.
369 *
370 * \param camera opened camera device
371 * \param spec The SDL_CameraSpec to be initialized by this function.
372 * \returns 0 on success or a negative error code on failure; call
373 * SDL_GetError() for more information.
374 *
375 * \threadsafety It is safe to call this function from any thread.
376 *
377 * \since This function is available since SDL 3.0.0.
378 *
379 * \sa SDL_OpenCameraDevice
380 */
381extern DECLSPEC int SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec);
382
383/**
384 * Acquire a frame.
385 *
386 * The frame is a memory pointer to the image data, whose size and format are
387 * given by the spec requested when opening the device.
388 *
389 * This is a non blocking API. If there is a frame available, a non-NULL
390 * surface is returned, and timestampNS will be filled with a non-zero value.
391 *
392 * Note that an error case can also return NULL, but a NULL by itself is
393 * normal and just signifies that a new frame is not yet available. Note that
394 * even if a camera device fails outright (a USB camera is unplugged while in
395 * use, etc), SDL will send an event separately to notify the app, but
396 * continue to provide blank frames at ongoing intervals until
397 * SDL_CloseCamera() is called, so real failure here is almost always an out
398 * of memory condition.
399 *
400 * After use, the frame should be released with SDL_ReleaseCameraFrame(). If
401 * you don't do this, the system may stop providing more video!
402 *
403 * Do not call SDL_FreeSurface() on the returned surface! It must be given
404 * back to the camera subsystem with SDL_ReleaseCameraFrame!
405 *
406 * If the system is waiting for the user to approve access to the camera, as
407 * some platforms require, this will return NULL (no frames available); you
408 * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or
409 * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved()
410 * occasionally until it returns non-zero.
411 *
412 * \param camera opened camera device
413 * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
414 * error. Can be NULL.
415 * \returns A new frame of video on success, NULL if none is currently
416 * available.
417 *
418 * \threadsafety It is safe to call this function from any thread.
419 *
420 * \since This function is available since SDL 3.0.0.
421 *
422 * \sa SDL_ReleaseCameraFrame
423 */
424extern DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS);
425
426/**
427 * Release a frame of video acquired from a camera.
428 *
429 * Let the back-end re-use the internal buffer for camera.
430 *
431 * This function _must_ be called only on surface objects returned by
432 * SDL_AcquireCameraFrame(). This function should be called as quickly as
433 * possible after acquisition, as SDL keeps a small FIFO queue of surfaces for
434 * video frames; if surfaces aren't released in a timely manner, SDL may drop
435 * upcoming video frames from the camera.
436 *
437 * If the app needs to keep the surface for a significant time, they should
438 * make a copy of it and release the original.
439 *
440 * The app should not use the surface again after calling this function;
441 * assume the surface is freed and the pointer is invalid.
442 *
443 * \param camera opened camera device
444 * \param frame The video frame surface to release.
445 * \returns 0 on success or a negative error code on failure; call
446 * SDL_GetError() for more information.
447 *
448 * \threadsafety It is safe to call this function from any thread.
449 *
450 * \since This function is available since SDL 3.0.0.
451 *
452 * \sa SDL_AcquireCameraFrame
453 */
454extern DECLSPEC int SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame);
455
456/**
457 * Use this function to shut down camera processing and close the camera
458 * device.
459 *
460 * \param camera opened camera device
461 *
462 * \threadsafety It is safe to call this function from any thread, but no
463 * thread may reference `device` once this function is called.
464 *
465 * \since This function is available since SDL 3.0.0.
466 *
467 * \sa SDL_OpenCameraWithSpec
468 * \sa SDL_OpenCamera
469 */
470extern DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera);
471
472/* Ends C function definitions when using C++ */
473#ifdef __cplusplus
474}
475#endif
476#include <SDL3/SDL_close_code.h>
477
478#endif /* SDL_camera_h_ */
SDL_CameraSpec * SDL_GetCameraDeviceSupportedFormats(SDL_CameraDeviceID devid, int *count)
Uint32 SDL_CameraDeviceID
Definition SDL_camera.h:48
SDL_CameraPosition
Definition SDL_camera.h:79
@ SDL_CAMERA_POSITION_BACK_FACING
Definition SDL_camera.h:82
@ SDL_CAMERA_POSITION_UNKNOWN
Definition SDL_camera.h:80
@ SDL_CAMERA_POSITION_FRONT_FACING
Definition SDL_camera.h:81
SDL_Camera * SDL_OpenCameraDevice(SDL_CameraDeviceID instance_id, const SDL_CameraSpec *spec)
SDL_CameraDeviceID SDL_GetCameraInstanceID(SDL_Camera *camera)
int SDL_GetNumCameraDrivers(void)
void SDL_CloseCamera(SDL_Camera *camera)
SDL_CameraDeviceID * SDL_GetCameraDevices(int *count)
const char * SDL_GetCurrentCameraDriver(void)
SDL_PropertiesID SDL_GetCameraProperties(SDL_Camera *camera)
SDL_CameraPosition SDL_GetCameraDevicePosition(SDL_CameraDeviceID instance_id)
int SDL_GetCameraPermissionState(SDL_Camera *camera)
struct SDL_Camera SDL_Camera
Definition SDL_camera.h:55
char * SDL_GetCameraDeviceName(SDL_CameraDeviceID instance_id)
SDL_Surface * SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS)
int SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec)
const char * SDL_GetCameraDriver(int index)
int SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame)
SDL_PixelFormatEnum
Definition SDL_pixels.h:215
Uint32 SDL_PropertiesID
uint64_t Uint64
Definition SDL_stdinc.h:187
uint32_t Uint32
Definition SDL_stdinc.h:174
SDL_PixelFormatEnum format
Definition SDL_camera.h:66
int interval_denominator
Definition SDL_camera.h:70
int interval_numerator
Definition SDL_camera.h:69