|
1
|
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
|
|
|
80 extern "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 */
|
|
|
95 typedef 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 */
|
|
|
102 typedef 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 */
|
|
|
115 typedef 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 denominator ((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 */
|
|
|
132 typedef 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 * The current state of a request for camera access.
|
|
|
141 *
|
|
|
142 * \since This enum is available since SDL 3.4.0.
|
|
|
143 *
|
|
|
144 * \sa SDL_GetCameraPermissionState
|
|
|
145 */
|
|
|
146 typedef enum SDL_CameraPermissionState
|
|
|
147 {
|
|
|
148 SDL_CAMERA_PERMISSION_STATE_DENIED = -1,
|
|
|
149 SDL_CAMERA_PERMISSION_STATE_PENDING,
|
|
|
150 SDL_CAMERA_PERMISSION_STATE_APPROVED,
|
|
|
151 } SDL_CameraPermissionState;
|
|
|
152
|
|
|
153
|
|
|
154 /**
|
|
|
155 * Use this function to get the number of built-in camera drivers.
|
|
|
156 *
|
|
|
157 * This function returns a hardcoded number. This never returns a negative
|
|
|
158 * value; if there are no drivers compiled into this build of SDL, this
|
|
|
159 * function returns zero. The presence of a driver in this list does not mean
|
|
|
160 * it will function, it just means SDL is capable of interacting with that
|
|
|
161 * interface. For example, a build of SDL might have v4l2 support, but if
|
|
|
162 * there's no kernel support available, SDL's v4l2 driver would fail if used.
|
|
|
163 *
|
|
|
164 * By default, SDL tries all drivers, in its preferred order, until one is
|
|
|
165 * found to be usable.
|
|
|
166 *
|
|
|
167 * \returns the number of built-in camera drivers.
|
|
|
168 *
|
|
|
169 * \threadsafety It is safe to call this function from any thread.
|
|
|
170 *
|
|
|
171 * \since This function is available since SDL 3.2.0.
|
|
|
172 *
|
|
|
173 * \sa SDL_GetCameraDriver
|
|
|
174 */
|
|
|
175 extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
|
|
|
176
|
|
|
177 /**
|
|
|
178 * Use this function to get the name of a built in camera driver.
|
|
|
179 *
|
|
|
180 * The list of camera drivers is given in the order that they are normally
|
|
|
181 * initialized by default; the drivers that seem more reasonable to choose
|
|
|
182 * first (as far as the SDL developers believe) are earlier in the list.
|
|
|
183 *
|
|
|
184 * The names of drivers are all simple, low-ASCII identifiers, like "v4l2",
|
|
|
185 * "coremedia" or "android". These never have Unicode characters, and are not
|
|
|
186 * meant to be proper names.
|
|
|
187 *
|
|
|
188 * \param index the index of the camera driver; the value ranges from 0 to
|
|
|
189 * SDL_GetNumCameraDrivers() - 1.
|
|
|
190 * \returns the name of the camera driver at the requested index, or NULL if
|
|
|
191 * an invalid index was specified.
|
|
|
192 *
|
|
|
193 * \threadsafety It is safe to call this function from any thread.
|
|
|
194 *
|
|
|
195 * \since This function is available since SDL 3.2.0.
|
|
|
196 *
|
|
|
197 * \sa SDL_GetNumCameraDrivers
|
|
|
198 */
|
|
|
199 extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index);
|
|
|
200
|
|
|
201 /**
|
|
|
202 * Get the name of the current camera driver.
|
|
|
203 *
|
|
|
204 * The names of drivers are all simple, low-ASCII identifiers, like "v4l2",
|
|
|
205 * "coremedia" or "android". These never have Unicode characters, and are not
|
|
|
206 * meant to be proper names.
|
|
|
207 *
|
|
|
208 * \returns the name of the current camera driver or NULL if no driver has
|
|
|
209 * been initialized.
|
|
|
210 *
|
|
|
211 * \threadsafety It is safe to call this function from any thread.
|
|
|
212 *
|
|
|
213 * \since This function is available since SDL 3.2.0.
|
|
|
214 */
|
|
|
215 extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
|
|
|
216
|
|
|
217 /**
|
|
|
218 * Get a list of currently connected camera devices.
|
|
|
219 *
|
|
|
220 * \param count a pointer filled in with the number of cameras returned, may
|
|
|
221 * be NULL.
|
|
|
222 * \returns a 0 terminated array of camera instance IDs or NULL on failure;
|
|
|
223 * call SDL_GetError() for more information. This should be freed
|
|
|
224 * with SDL_free() when it is no longer needed.
|
|
|
225 *
|
|
|
226 * \threadsafety It is safe to call this function from any thread.
|
|
|
227 *
|
|
|
228 * \since This function is available since SDL 3.2.0.
|
|
|
229 *
|
|
|
230 * \sa SDL_OpenCamera
|
|
|
231 */
|
|
|
232 extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
|
|
|
233
|
|
|
234 /**
|
|
|
235 * Get the list of native formats/sizes a camera supports.
|
|
|
236 *
|
|
|
237 * This returns a list of all formats and frame sizes that a specific camera
|
|
|
238 * can offer. This is useful if your app can accept a variety of image formats
|
|
|
239 * and sizes and so want to find the optimal spec that doesn't require
|
|
|
240 * conversion.
|
|
|
241 *
|
|
|
242 * This function isn't strictly required; if you call SDL_OpenCamera with a
|
|
|
243 * NULL spec, SDL will choose a native format for you, and if you instead
|
|
|
244 * specify a desired format, it will transparently convert to the requested
|
|
|
245 * format on your behalf.
|
|
|
246 *
|
|
|
247 * If `count` is not NULL, it will be filled with the number of elements in
|
|
|
248 * the returned array.
|
|
|
249 *
|
|
|
250 * Note that it's legal for a camera to supply an empty list. This is what
|
|
|
251 * will happen on Emscripten builds, since that platform won't tell _anything_
|
|
|
252 * about available cameras until you've opened one, and won't even tell if
|
|
|
253 * there _is_ a camera until the user has given you permission to check
|
|
|
254 * through a scary warning popup.
|
|
|
255 *
|
|
|
256 * \param instance_id the camera device instance ID.
|
|
|
257 * \param count a pointer filled in with the number of elements in the list,
|
|
|
258 * may be NULL.
|
|
|
259 * \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on
|
|
|
260 * failure; call SDL_GetError() for more information. This is a
|
|
|
261 * single allocation that should be freed with SDL_free() when it is
|
|
|
262 * no longer needed.
|
|
|
263 *
|
|
|
264 * \threadsafety It is safe to call this function from any thread.
|
|
|
265 *
|
|
|
266 * \since This function is available since SDL 3.2.0.
|
|
|
267 *
|
|
|
268 * \sa SDL_GetCameras
|
|
|
269 * \sa SDL_OpenCamera
|
|
|
270 */
|
|
|
271 extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID instance_id, int *count);
|
|
|
272
|
|
|
273 /**
|
|
|
274 * Get the human-readable device name for a camera.
|
|
|
275 *
|
|
|
276 * \param instance_id the camera device instance ID.
|
|
|
277 * \returns a human-readable device name or NULL on failure; call
|
|
|
278 * SDL_GetError() for more information.
|
|
|
279 *
|
|
|
280 * \threadsafety It is safe to call this function from any thread.
|
|
|
281 *
|
|
|
282 * \since This function is available since SDL 3.2.0.
|
|
|
283 *
|
|
|
284 * \sa SDL_GetCameras
|
|
|
285 */
|
|
|
286 extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance_id);
|
|
|
287
|
|
|
288 /**
|
|
|
289 * Get the position of the camera in relation to the system.
|
|
|
290 *
|
|
|
291 * Most platforms will report UNKNOWN, but mobile devices, like phones, can
|
|
|
292 * often make a distinction between cameras on the front of the device (that
|
|
|
293 * points towards the user, for taking "selfies") and cameras on the back (for
|
|
|
294 * filming in the direction the user is facing).
|
|
|
295 *
|
|
|
296 * \param instance_id the camera device instance ID.
|
|
|
297 * \returns the position of the camera on the system hardware.
|
|
|
298 *
|
|
|
299 * \threadsafety It is safe to call this function from any thread.
|
|
|
300 *
|
|
|
301 * \since This function is available since SDL 3.2.0.
|
|
|
302 *
|
|
|
303 * \sa SDL_GetCameras
|
|
|
304 */
|
|
|
305 extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraID instance_id);
|
|
|
306
|
|
|
307 /**
|
|
|
308 * Open a video recording device (a "camera").
|
|
|
309 *
|
|
|
310 * You can open the device with any reasonable spec, and if the hardware can't
|
|
|
311 * directly support it, it will convert data seamlessly to the requested
|
|
|
312 * format. This might incur overhead, including scaling of image data.
|
|
|
313 *
|
|
|
314 * If you would rather accept whatever format the device offers, you can pass
|
|
|
315 * a NULL spec here and it will choose one for you (and you can use
|
|
|
316 * SDL_Surface's conversion/scaling functions directly if necessary).
|
|
|
317 *
|
|
|
318 * You can call SDL_GetCameraFormat() to get the actual data format if passing
|
|
|
319 * a NULL spec here. You can see the exact specs a device can support without
|
|
|
320 * conversion with SDL_GetCameraSupportedFormats().
|
|
|
321 *
|
|
|
322 * SDL will not attempt to emulate framerate; it will try to set the hardware
|
|
|
323 * to the rate closest to the requested speed, but it won't attempt to limit
|
|
|
324 * or duplicate frames artificially; call SDL_GetCameraFormat() to see the
|
|
|
325 * actual framerate of the opened the device, and check your timestamps if
|
|
|
326 * this is crucial to your app!
|
|
|
327 *
|
|
|
328 * Note that the camera is not usable until the user approves its use! On some
|
|
|
329 * platforms, the operating system will prompt the user to permit access to
|
|
|
330 * the camera, and they can choose Yes or No at that point. Until they do, the
|
|
|
331 * camera will not be usable. The app should either wait for an
|
|
|
332 * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event,
|
|
|
333 * or poll SDL_GetCameraPermissionState() occasionally until it returns
|
|
|
334 * non-zero. On platforms that don't require explicit user approval (and
|
|
|
335 * perhaps in places where the user previously permitted access), the approval
|
|
|
336 * event might come immediately, but it might come seconds, minutes, or hours
|
|
|
337 * later!
|
|
|
338 *
|
|
|
339 * \param instance_id the camera device instance ID.
|
|
|
340 * \param spec the desired format for data the device will provide. Can be
|
|
|
341 * NULL.
|
|
|
342 * \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for
|
|
|
343 * more information.
|
|
|
344 *
|
|
|
345 * \threadsafety It is safe to call this function from any thread.
|
|
|
346 *
|
|
|
347 * \since This function is available since SDL 3.2.0.
|
|
|
348 *
|
|
|
349 * \sa SDL_GetCameras
|
|
|
350 * \sa SDL_GetCameraFormat
|
|
|
351 */
|
|
|
352 extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id, const SDL_CameraSpec *spec);
|
|
|
353
|
|
|
354 /**
|
|
|
355 * Query if camera access has been approved by the user.
|
|
|
356 *
|
|
|
357 * Cameras will not function between when the device is opened by the app and
|
|
|
358 * when the user permits access to the hardware. On some platforms, this
|
|
|
359 * presents as a popup dialog where the user has to explicitly approve access;
|
|
|
360 * on others the approval might be implicit and not alert the user at all.
|
|
|
361 *
|
|
|
362 * This function can be used to check the status of that approval. It will
|
|
|
363 * return SDL_CAMERA_PERMISSION_STATE_PENDING if waiting for user response,
|
|
|
364 * SDL_CAMERA_PERMISSION_STATE_APPROVED if the camera is approved for use, and
|
|
|
365 * SDL_CAMERA_PERMISSION_STATE_DENIED if the user denied access.
|
|
|
366 *
|
|
|
367 * Instead of polling with this function, you can wait for a
|
|
|
368 * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event
|
|
|
369 * in the standard SDL event loop, which is guaranteed to be sent once when
|
|
|
370 * permission to use the camera is decided.
|
|
|
371 *
|
|
|
372 * If a camera is declined, there's nothing to be done but call
|
|
|
373 * SDL_CloseCamera() to dispose of it.
|
|
|
374 *
|
|
|
375 * \param camera the opened camera device to query.
|
|
|
376 * \returns an SDL_CameraPermissionState value indicating if access is
|
|
|
377 * granted, or `SDL_CAMERA_PERMISSION_STATE_PENDING` if the decision
|
|
|
378 * is still pending.
|
|
|
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 * \sa SDL_CloseCamera
|
|
|
386 */
|
|
|
387 extern SDL_DECLSPEC SDL_CameraPermissionState SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera);
|
|
|
388
|
|
|
389 /**
|
|
|
390 * Get the instance ID of an opened camera.
|
|
|
391 *
|
|
|
392 * \param camera an SDL_Camera to query.
|
|
|
393 * \returns the instance ID of the specified camera on success or 0 on
|
|
|
394 * failure; call SDL_GetError() for more information.
|
|
|
395 *
|
|
|
396 * \threadsafety It is safe to call this function from any thread.
|
|
|
397 *
|
|
|
398 * \since This function is available since SDL 3.2.0.
|
|
|
399 *
|
|
|
400 * \sa SDL_OpenCamera
|
|
|
401 */
|
|
|
402 extern SDL_DECLSPEC SDL_CameraID SDLCALL SDL_GetCameraID(SDL_Camera *camera);
|
|
|
403
|
|
|
404 /**
|
|
|
405 * Get the properties associated with an opened camera.
|
|
|
406 *
|
|
|
407 * \param camera the SDL_Camera obtained from SDL_OpenCamera().
|
|
|
408 * \returns a valid property ID on success or 0 on failure; call
|
|
|
409 * SDL_GetError() for more information.
|
|
|
410 *
|
|
|
411 * \threadsafety It is safe to call this function from any thread.
|
|
|
412 *
|
|
|
413 * \since This function is available since SDL 3.2.0.
|
|
|
414 */
|
|
|
415 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera);
|
|
|
416
|
|
|
417 /**
|
|
|
418 * Get the spec that a camera is using when generating images.
|
|
|
419 *
|
|
|
420 * Note that this might not be the native format of the hardware, as SDL might
|
|
|
421 * be converting to this format behind the scenes.
|
|
|
422 *
|
|
|
423 * If the system is waiting for the user to approve access to the camera, as
|
|
|
424 * some platforms require, this will return false, but this isn't necessarily
|
|
|
425 * a fatal error; you should either wait for an
|
|
|
426 * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event,
|
|
|
427 * or poll SDL_GetCameraPermissionState() occasionally until it returns
|
|
|
428 * non-zero.
|
|
|
429 *
|
|
|
430 * \param camera opened camera device.
|
|
|
431 * \param spec the SDL_CameraSpec to be initialized by this function.
|
|
|
432 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
433 * information.
|
|
|
434 *
|
|
|
435 * \threadsafety It is safe to call this function from any thread.
|
|
|
436 *
|
|
|
437 * \since This function is available since SDL 3.2.0.
|
|
|
438 *
|
|
|
439 * \sa SDL_OpenCamera
|
|
|
440 */
|
|
|
441 extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec);
|
|
|
442
|
|
|
443 /**
|
|
|
444 * Acquire a frame.
|
|
|
445 *
|
|
|
446 * The frame is a memory pointer to the image data, whose size and format are
|
|
|
447 * given by the spec requested when opening the device.
|
|
|
448 *
|
|
|
449 * This is a non blocking API. If there is a frame available, a non-NULL
|
|
|
450 * surface is returned, and timestampNS will be filled with a non-zero value.
|
|
|
451 *
|
|
|
452 * Note that an error case can also return NULL, but a NULL by itself is
|
|
|
453 * normal and just signifies that a new frame is not yet available. Note that
|
|
|
454 * even if a camera device fails outright (a USB camera is unplugged while in
|
|
|
455 * use, etc), SDL will send an event separately to notify the app, but
|
|
|
456 * continue to provide blank frames at ongoing intervals until
|
|
|
457 * SDL_CloseCamera() is called, so real failure here is almost always an out
|
|
|
458 * of memory condition.
|
|
|
459 *
|
|
|
460 * After use, the frame should be released with SDL_ReleaseCameraFrame(). If
|
|
|
461 * you don't do this, the system may stop providing more video!
|
|
|
462 *
|
|
|
463 * Do not call SDL_DestroySurface() on the returned surface! It must be given
|
|
|
464 * back to the camera subsystem with SDL_ReleaseCameraFrame!
|
|
|
465 *
|
|
|
466 * If the system is waiting for the user to approve access to the camera, as
|
|
|
467 * some platforms require, this will return NULL (no frames available); you
|
|
|
468 * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or
|
|
|
469 * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll
|
|
|
470 * SDL_GetCameraPermissionState() occasionally until it returns non-zero.
|
|
|
471 *
|
|
|
472 * \param camera opened camera device.
|
|
|
473 * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
|
|
|
474 * error. Can be NULL.
|
|
|
475 * \returns a new frame of video on success, NULL if none is currently
|
|
|
476 * available.
|
|
|
477 *
|
|
|
478 * \threadsafety It is safe to call this function from any thread.
|
|
|
479 *
|
|
|
480 * \since This function is available since SDL 3.2.0.
|
|
|
481 *
|
|
|
482 * \sa SDL_ReleaseCameraFrame
|
|
|
483 */
|
|
|
484 extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS);
|
|
|
485
|
|
|
486 /**
|
|
|
487 * Release a frame of video acquired from a camera.
|
|
|
488 *
|
|
|
489 * Let the back-end re-use the internal buffer for camera.
|
|
|
490 *
|
|
|
491 * This function _must_ be called only on surface objects returned by
|
|
|
492 * SDL_AcquireCameraFrame(). This function should be called as quickly as
|
|
|
493 * possible after acquisition, as SDL keeps a small FIFO queue of surfaces for
|
|
|
494 * video frames; if surfaces aren't released in a timely manner, SDL may drop
|
|
|
495 * upcoming video frames from the camera.
|
|
|
496 *
|
|
|
497 * If the app needs to keep the surface for a significant time, they should
|
|
|
498 * make a copy of it and release the original.
|
|
|
499 *
|
|
|
500 * The app should not use the surface again after calling this function;
|
|
|
501 * assume the surface is freed and the pointer is invalid.
|
|
|
502 *
|
|
|
503 * \param camera opened camera device.
|
|
|
504 * \param frame the video frame surface to release.
|
|
|
505 *
|
|
|
506 * \threadsafety It is safe to call this function from any thread.
|
|
|
507 *
|
|
|
508 * \since This function is available since SDL 3.2.0.
|
|
|
509 *
|
|
|
510 * \sa SDL_AcquireCameraFrame
|
|
|
511 */
|
|
|
512 extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame);
|
|
|
513
|
|
|
514 /**
|
|
|
515 * Use this function to shut down camera processing and close the camera
|
|
|
516 * device.
|
|
|
517 *
|
|
|
518 * \param camera opened camera device.
|
|
|
519 *
|
|
|
520 * \threadsafety It is safe to call this function from any thread, but no
|
|
|
521 * thread may reference `device` once this function is called.
|
|
|
522 *
|
|
|
523 * \since This function is available since SDL 3.2.0.
|
|
|
524 *
|
|
|
525 * \sa SDL_OpenCamera
|
|
|
526 */
|
|
|
527 extern SDL_DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera);
|
|
|
528
|
|
|
529 /* Ends C function definitions when using C++ */
|
|
|
530 #ifdef __cplusplus
|
|
|
531 }
|
|
|
532 #endif
|
|
|
533 #include <SDL3/SDL_close_code.h>
|
|
|
534
|
|
|
535 #endif /* SDL_camera_h_ */
|
