SDL 3.0
SDL_video_capture.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_video_capture.h
24 *
25 * Video Capture for the SDL library.
26 */
27
28#ifndef SDL_video_capture_h_
29#define SDL_video_capture_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 video capture 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_GetVideoCaptureDevices
47 */
49
50
51/**
52 * The structure used to identify an SDL video capture device
53 */
56
57#define SDL_VIDEO_CAPTURE_ALLOW_ANY_CHANGE 1
58
59/**
60 * SDL_VideoCaptureSpec structure
61 *
62 * Only those field can be 'desired' when configuring the device:
63 * - format
64 * - width
65 * - height
66 *
67 * \sa SDL_GetVideoCaptureFormat
68 * \sa SDL_GetVideoCaptureFrameSize
69 *
70 */
72{
73 Uint32 format; /**< Frame SDL_PixelFormatEnum format */
74 int width; /**< Frame width */
75 int height; /**< Frame height */
77
78/**
79 * SDL Video Capture Status
80 *
81 * Change states but calling the function in this order:
82 *
83 * SDL_OpenVideoCapture()
84 * SDL_SetVideoCaptureSpec() -> Init
85 * SDL_StartVideoCapture() -> Playing
86 * SDL_StopVideoCapture() -> Stopped
87 * SDL_CloseVideoCapture()
88 *
89 */
90typedef enum
91{
92 SDL_VIDEO_CAPTURE_FAIL = -1, /**< Failed */
93 SDL_VIDEO_CAPTURE_INIT = 0, /**< Init, spec hasn't been set */
95 SDL_VIDEO_CAPTURE_PLAYING /**< Playing */
97
98/**
99 * SDL Video Capture Status
100 */
102{
103 Uint64 timestampNS; /**< Frame timestamp in nanoseconds when read from the driver */
104 int num_planes; /**< Number of planes */
105 Uint8 *data[3]; /**< Pointer to data of i-th plane */
106 int pitch[3]; /**< Pitch of i-th plane */
107 void *internal; /**< Private field */
109
110
111/**
112 * Get a list of currently connected video capture devices.
113 *
114 * \param count a pointer filled in with the number of video capture devices
115 * \returns a 0 terminated array of video capture instance IDs which should be
116 * freed with SDL_free(), or NULL on error; call SDL_GetError() for
117 * more details.
118 *
119 * \since This function is available since SDL 3.0.0.
120 *
121 * \sa SDL_OpenVideoCapture
122 */
123extern DECLSPEC SDL_VideoCaptureDeviceID *SDLCALL SDL_GetVideoCaptureDevices(int *count);
124
125/**
126 * Open a Video Capture device
127 *
128 * \param instance_id the video capture device instance ID
129 * \returns device, or NULL on failure; call SDL_GetError() for more
130 * information.
131 *
132 * \since This function is available since SDL 3.0.0.
133 *
134 * \sa SDL_GetVideoCaptureDeviceName
135 * \sa SDL_GetVideoCaptureDevices
136 * \sa SDL_OpenVideoCaptureWithSpec
137 */
139
140/**
141 * Set specification
142 *
143 * \param device opened video capture device
144 * \param desired desired video capture spec
145 * \param obtained obtained video capture spec
146 * \param allowed_changes allow changes or not
147 * \returns 0 on success or a negative error code on failure; call
148 * SDL_GetError() for more information.
149 *
150 * \since This function is available since SDL 3.0.0.
151 *
152 * \sa SDL_OpenVideoCapture
153 * \sa SDL_OpenVideoCaptureWithSpec
154 * \sa SDL_GetVideoCaptureSpec
155 */
156extern DECLSPEC int SDLCALL SDL_SetVideoCaptureSpec(SDL_VideoCaptureDevice *device,
157 const SDL_VideoCaptureSpec *desired,
158 SDL_VideoCaptureSpec *obtained,
159 int allowed_changes);
160
161/**
162 * Open a Video Capture device and set specification
163 *
164 * \param instance_id the video capture device instance ID
165 * \param desired desired video capture spec
166 * \param obtained obtained video capture spec
167 * \param allowed_changes allow changes or not
168 * \returns device, or NULL on failure; call SDL_GetError() for more
169 * information.
170 *
171 * \since This function is available since SDL 3.0.0.
172 *
173 * \sa SDL_OpenVideoCapture
174 * \sa SDL_SetVideoCaptureSpec
175 * \sa SDL_GetVideoCaptureSpec
176 */
178 const SDL_VideoCaptureSpec *desired,
179 SDL_VideoCaptureSpec *obtained,
180 int allowed_changes);
181
182/**
183 * Get device name
184 *
185 * \param instance_id the video capture device instance ID
186 * \returns device name, shouldn't be freed
187 *
188 * \since This function is available since SDL 3.0.0.
189 *
190 * \sa SDL_GetVideoCaptureDevices
191 */
192extern DECLSPEC const char * SDLCALL SDL_GetVideoCaptureDeviceName(SDL_VideoCaptureDeviceID instance_id);
193
194/**
195 * Get the obtained video capture spec
196 *
197 * \param device opened video capture device
198 * \param spec The SDL_VideoCaptureSpec to be initialized by this function.
199 * \returns 0 on success or a negative error code on failure; call
200 * SDL_GetError() for more information.
201 *
202 * \since This function is available since SDL 3.0.0.
203 *
204 * \sa SDL_SetVideoCaptureSpec
205 * \sa SDL_OpenVideoCaptureWithSpec
206 */
207extern DECLSPEC int SDLCALL SDL_GetVideoCaptureSpec(SDL_VideoCaptureDevice *device, SDL_VideoCaptureSpec *spec);
208
209
210/**
211 * Get frame format of video capture device.
212 *
213 * The value can be used to fill SDL_VideoCaptureSpec structure.
214 *
215 * \param device opened video capture device
216 * \param index format between 0 and num -1
217 * \param format pointer output format (SDL_PixelFormatEnum)
218 * \returns 0 on success or a negative error code on failure; call
219 * SDL_GetError() for more information.
220 *
221 * \since This function is available since SDL 3.0.0.
222 *
223 * \sa SDL_GetNumVideoCaptureFormats
224 */
225extern DECLSPEC int SDLCALL SDL_GetVideoCaptureFormat(SDL_VideoCaptureDevice *device,
226 int index,
227 Uint32 *format);
228
229/**
230 * Number of available formats for the device
231 *
232 * \param device opened video capture device
233 * \returns number of formats or a negative error code on failure; call
234 * SDL_GetError() for more information.
235 *
236 * \since This function is available since SDL 3.0.0.
237 *
238 * \sa SDL_GetVideoCaptureFormat
239 * \sa SDL_SetVideoCaptureSpec
240 */
241extern DECLSPEC int SDLCALL SDL_GetNumVideoCaptureFormats(SDL_VideoCaptureDevice *device);
242
243/**
244 * Get frame sizes of the device and the specified input format.
245 *
246 * The value can be used to fill SDL_VideoCaptureSpec structure.
247 *
248 * \param device opened video capture device
249 * \param format a format that can be used by the device (SDL_PixelFormatEnum)
250 * \param index framesize between 0 and num -1
251 * \param width output width
252 * \param height output height
253 * \returns 0 on success or a negative error code on failure; call
254 * SDL_GetError() for more information.
255 *
256 * \since This function is available since SDL 3.0.0.
257 *
258 * \sa SDL_GetNumVideoCaptureFrameSizes
259 */
260extern DECLSPEC int SDLCALL SDL_GetVideoCaptureFrameSize(SDL_VideoCaptureDevice *device, Uint32 format, int index, int *width, int *height);
261
262/**
263 * Number of different framesizes available for the device and pixel format.
264 *
265 * \param device opened video capture device
266 * \param format frame pixel format (SDL_PixelFormatEnum)
267 * \returns number of framesizes or a negative error code on failure; call
268 * SDL_GetError() for more information.
269 *
270 * \since This function is available since SDL 3.0.0.
271 *
272 * \sa SDL_GetVideoCaptureFrameSize
273 * \sa SDL_SetVideoCaptureSpec
274 */
275extern DECLSPEC int SDLCALL SDL_GetNumVideoCaptureFrameSizes(SDL_VideoCaptureDevice *device, Uint32 format);
276
277
278/**
279 * Get video capture status
280 *
281 * \param device opened video capture device
282 * \returns 0 on success or a negative error code on failure; call
283 * SDL_GetError() for more information.
284 *
285 * \since This function is available since SDL 3.0.0.
286 *
287 * \sa SDL_VideoCaptureStatus
288 */
290
291/**
292 * Start video capture
293 *
294 * \param device opened video capture device
295 * \returns 0 on success or a negative error code on failure; call
296 * SDL_GetError() for more information.
297 *
298 * \since This function is available since SDL 3.0.0.
299 *
300 * \sa SDL_StopVideoCapture
301 */
302extern DECLSPEC int SDLCALL SDL_StartVideoCapture(SDL_VideoCaptureDevice *device);
303
304/**
305 * Acquire a frame.
306 *
307 * The frame is a memory pointer to the image data, whose size and format are
308 * given by the the obtained spec.
309 *
310 * Non blocking API. If there is a frame available, frame->num_planes is non
311 * 0. If frame->num_planes is 0 and returned code is 0, there is no frame at
312 * that time.
313 *
314 * After used, the frame should be released with SDL_ReleaseVideoCaptureFrame
315 *
316 * \param device opened video capture device
317 * \param frame pointer to get the frame
318 * \returns 0 on success or a negative error code on failure; call
319 * SDL_GetError() for more information.
320 *
321 * \since This function is available since SDL 3.0.0.
322 *
323 * \sa SDL_ReleaseVideoCaptureFrame
324 */
326
327/**
328 * Release a frame.
329 *
330 * Let the back-end re-use the internal buffer for video capture.
331 *
332 * All acquired frames should be released before closing the device.
333 *
334 * \param device opened video capture device
335 * \param frame frame pointer.
336 * \returns 0 on success or a negative error code on failure; call
337 * SDL_GetError() for more information.
338 *
339 * \since This function is available since SDL 3.0.0.
340 *
341 * \sa SDL_AcquireVideoCaptureFrame
342 */
344
345/**
346 * Stop Video Capture
347 *
348 * \param device opened video capture device
349 * \returns 0 on success or a negative error code on failure; call
350 * SDL_GetError() for more information.
351 *
352 * \since This function is available since SDL 3.0.0.
353 *
354 * \sa SDL_StartVideoCapture
355 */
356extern DECLSPEC int SDLCALL SDL_StopVideoCapture(SDL_VideoCaptureDevice *device);
357
358/**
359 * Use this function to shut down video_capture processing and close the
360 * video_capture device.
361 *
362 * \param device opened video capture device
363 *
364 * \since This function is available since SDL 3.0.0.
365 *
366 * \sa SDL_OpenVideoCaptureWithSpec
367 * \sa SDL_OpenVideoCapture
368 */
369extern DECLSPEC void SDLCALL SDL_CloseVideoCapture(SDL_VideoCaptureDevice *device);
370
371/* Ends C function definitions when using C++ */
372#ifdef __cplusplus
373}
374#endif
375#include <SDL3/SDL_close_code.h>
376
377#endif /* SDL_video_capture_h_ */
uint8_t Uint8
Definition SDL_stdinc.h:150
uint64_t Uint64
Definition SDL_stdinc.h:187
uint32_t Uint32
Definition SDL_stdinc.h:174
int SDL_GetVideoCaptureFrameSize(SDL_VideoCaptureDevice *device, Uint32 format, int index, int *width, int *height)
struct SDL_VideoCaptureDevice SDL_VideoCaptureDevice
Uint32 SDL_VideoCaptureDeviceID
SDL_VideoCaptureDeviceID * SDL_GetVideoCaptureDevices(int *count)
SDL_VideoCaptureDevice * SDL_OpenVideoCapture(SDL_VideoCaptureDeviceID instance_id)
const char * SDL_GetVideoCaptureDeviceName(SDL_VideoCaptureDeviceID instance_id)
SDL_VideoCaptureStatus SDL_GetVideoCaptureStatus(SDL_VideoCaptureDevice *device)
int SDL_AcquireVideoCaptureFrame(SDL_VideoCaptureDevice *device, SDL_VideoCaptureFrame *frame)
int SDL_ReleaseVideoCaptureFrame(SDL_VideoCaptureDevice *device, SDL_VideoCaptureFrame *frame)
SDL_VideoCaptureStatus
@ SDL_VIDEO_CAPTURE_INIT
@ SDL_VIDEO_CAPTURE_FAIL
@ SDL_VIDEO_CAPTURE_STOPPED
@ SDL_VIDEO_CAPTURE_PLAYING
int SDL_GetVideoCaptureFormat(SDL_VideoCaptureDevice *device, int index, Uint32 *format)
int SDL_SetVideoCaptureSpec(SDL_VideoCaptureDevice *device, const SDL_VideoCaptureSpec *desired, SDL_VideoCaptureSpec *obtained, int allowed_changes)
SDL_VideoCaptureDevice * SDL_OpenVideoCaptureWithSpec(SDL_VideoCaptureDeviceID instance_id, const SDL_VideoCaptureSpec *desired, SDL_VideoCaptureSpec *obtained, int allowed_changes)
void SDL_CloseVideoCapture(SDL_VideoCaptureDevice *device)
int SDL_StopVideoCapture(SDL_VideoCaptureDevice *device)
int SDL_GetNumVideoCaptureFrameSizes(SDL_VideoCaptureDevice *device, Uint32 format)
int SDL_StartVideoCapture(SDL_VideoCaptureDevice *device)
int SDL_GetVideoCaptureSpec(SDL_VideoCaptureDevice *device, SDL_VideoCaptureSpec *spec)
int SDL_GetNumVideoCaptureFormats(SDL_VideoCaptureDevice *device)