SDL 3.0
SDL_video_capture.h File Reference
+ Include dependency graph for SDL_video_capture.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_VideoCaptureSpec
 
struct  SDL_VideoCaptureFrame
 

Macros

#define SDL_VIDEO_CAPTURE_ALLOW_ANY_CHANGE   1
 

Typedefs

typedef Uint32 SDL_VideoCaptureDeviceID
 
typedef struct SDL_VideoCaptureDevice SDL_VideoCaptureDevice
 

Enumerations

enum  SDL_VideoCaptureStatus {
  SDL_VIDEO_CAPTURE_FAIL = -1 ,
  SDL_VIDEO_CAPTURE_INIT = 0 ,
  SDL_VIDEO_CAPTURE_STOPPED ,
  SDL_VIDEO_CAPTURE_PLAYING
}
 

Functions

SDL_VideoCaptureDeviceIDSDL_GetVideoCaptureDevices (int *count)
 
SDL_VideoCaptureDeviceSDL_OpenVideoCapture (SDL_VideoCaptureDeviceID instance_id)
 
int SDL_SetVideoCaptureSpec (SDL_VideoCaptureDevice *device, const SDL_VideoCaptureSpec *desired, SDL_VideoCaptureSpec *obtained, int allowed_changes)
 
SDL_VideoCaptureDeviceSDL_OpenVideoCaptureWithSpec (SDL_VideoCaptureDeviceID instance_id, const SDL_VideoCaptureSpec *desired, SDL_VideoCaptureSpec *obtained, int allowed_changes)
 
const char * SDL_GetVideoCaptureDeviceName (SDL_VideoCaptureDeviceID instance_id)
 
int SDL_GetVideoCaptureSpec (SDL_VideoCaptureDevice *device, SDL_VideoCaptureSpec *spec)
 
int SDL_GetVideoCaptureFormat (SDL_VideoCaptureDevice *device, int index, Uint32 *format)
 
int SDL_GetNumVideoCaptureFormats (SDL_VideoCaptureDevice *device)
 
int SDL_GetVideoCaptureFrameSize (SDL_VideoCaptureDevice *device, Uint32 format, int index, int *width, int *height)
 
int SDL_GetNumVideoCaptureFrameSizes (SDL_VideoCaptureDevice *device, Uint32 format)
 
SDL_VideoCaptureStatus SDL_GetVideoCaptureStatus (SDL_VideoCaptureDevice *device)
 
int SDL_StartVideoCapture (SDL_VideoCaptureDevice *device)
 
int SDL_AcquireVideoCaptureFrame (SDL_VideoCaptureDevice *device, SDL_VideoCaptureFrame *frame)
 
int SDL_ReleaseVideoCaptureFrame (SDL_VideoCaptureDevice *device, SDL_VideoCaptureFrame *frame)
 
int SDL_StopVideoCapture (SDL_VideoCaptureDevice *device)
 
void SDL_CloseVideoCapture (SDL_VideoCaptureDevice *device)
 

Detailed Description

Video Capture for the SDL library.

Definition in file SDL_video_capture.h.

Macro Definition Documentation

◆ SDL_VIDEO_CAPTURE_ALLOW_ANY_CHANGE

#define SDL_VIDEO_CAPTURE_ALLOW_ANY_CHANGE   1

Definition at line 57 of file SDL_video_capture.h.

Typedef Documentation

◆ SDL_VideoCaptureDevice

Definition at line 55 of file SDL_video_capture.h.

◆ SDL_VideoCaptureDeviceID

This is a unique ID for a video capture device for the time it is connected to the system, and is never reused for the lifetime of the application. If the device is disconnected and reconnected, it will get a new ID.

The ID value starts at 1 and increments from there. The value 0 is an invalid ID.

See also
SDL_GetVideoCaptureDevices

Definition at line 48 of file SDL_video_capture.h.

Enumeration Type Documentation

◆ SDL_VideoCaptureStatus

SDL Video Capture Status

Change states but calling the function in this order:

SDL_OpenVideoCapture() SDL_SetVideoCaptureSpec() -> Init SDL_StartVideoCapture() -> Playing SDL_StopVideoCapture() -> Stopped SDL_CloseVideoCapture()

Enumerator
SDL_VIDEO_CAPTURE_FAIL 

Failed

SDL_VIDEO_CAPTURE_INIT 

Init, spec hasn't been set

SDL_VIDEO_CAPTURE_STOPPED 

Stopped

SDL_VIDEO_CAPTURE_PLAYING 

Playing

Definition at line 90 of file SDL_video_capture.h.

91{
92 SDL_VIDEO_CAPTURE_FAIL = -1, /**< Failed */
93 SDL_VIDEO_CAPTURE_INIT = 0, /**< Init, spec hasn't been set */
94 SDL_VIDEO_CAPTURE_STOPPED, /**< Stopped */
95 SDL_VIDEO_CAPTURE_PLAYING /**< Playing */
SDL_VideoCaptureStatus
@ SDL_VIDEO_CAPTURE_INIT
@ SDL_VIDEO_CAPTURE_FAIL
@ SDL_VIDEO_CAPTURE_STOPPED
@ SDL_VIDEO_CAPTURE_PLAYING

Function Documentation

◆ SDL_AcquireVideoCaptureFrame()

int SDL_AcquireVideoCaptureFrame ( SDL_VideoCaptureDevice device,
SDL_VideoCaptureFrame frame 
)
extern

Acquire a frame.

The frame is a memory pointer to the image data, whose size and format are given by the the obtained spec.

Non blocking API. If there is a frame available, frame->num_planes is non 0. If frame->num_planes is 0 and returned code is 0, there is no frame at that time.

After used, the frame should be released with SDL_ReleaseVideoCaptureFrame

Parameters
deviceopened video capture device
framepointer to get the frame
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_ReleaseVideoCaptureFrame

◆ SDL_CloseVideoCapture()

void SDL_CloseVideoCapture ( SDL_VideoCaptureDevice device)
extern

Use this function to shut down video_capture processing and close the video_capture device.

Parameters
deviceopened video capture device
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenVideoCaptureWithSpec
SDL_OpenVideoCapture

◆ SDL_GetNumVideoCaptureFormats()

int SDL_GetNumVideoCaptureFormats ( SDL_VideoCaptureDevice device)
extern

Number of available formats for the device

Parameters
deviceopened video capture device
Returns
number of formats or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetVideoCaptureFormat
SDL_SetVideoCaptureSpec

◆ SDL_GetNumVideoCaptureFrameSizes()

int SDL_GetNumVideoCaptureFrameSizes ( SDL_VideoCaptureDevice device,
Uint32  format 
)
extern

Number of different framesizes available for the device and pixel format.

Parameters
deviceopened video capture device
formatframe pixel format (SDL_PixelFormatEnum)
Returns
number of framesizes or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetVideoCaptureFrameSize
SDL_SetVideoCaptureSpec

◆ SDL_GetVideoCaptureDeviceName()

const char * SDL_GetVideoCaptureDeviceName ( SDL_VideoCaptureDeviceID  instance_id)
extern

Get device name

Parameters
instance_idthe video capture device instance ID
Returns
device name, shouldn't be freed
Since
This function is available since SDL 3.0.0.
See also
SDL_GetVideoCaptureDevices

◆ SDL_GetVideoCaptureDevices()

SDL_VideoCaptureDeviceID * SDL_GetVideoCaptureDevices ( int *  count)
extern

Get a list of currently connected video capture devices.

Parameters
counta pointer filled in with the number of video capture devices
Returns
a 0 terminated array of video capture instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenVideoCapture

◆ SDL_GetVideoCaptureFormat()

int SDL_GetVideoCaptureFormat ( SDL_VideoCaptureDevice device,
int  index,
Uint32 format 
)
extern

Get frame format of video capture device.

The value can be used to fill SDL_VideoCaptureSpec structure.

Parameters
deviceopened video capture device
indexformat between 0 and num -1
formatpointer output format (SDL_PixelFormatEnum)
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetNumVideoCaptureFormats

◆ SDL_GetVideoCaptureFrameSize()

int SDL_GetVideoCaptureFrameSize ( SDL_VideoCaptureDevice device,
Uint32  format,
int  index,
int *  width,
int *  height 
)
extern

Get frame sizes of the device and the specified input format.

The value can be used to fill SDL_VideoCaptureSpec structure.

Parameters
deviceopened video capture device
formata format that can be used by the device (SDL_PixelFormatEnum)
indexframesize between 0 and num -1
widthoutput width
heightoutput height
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetNumVideoCaptureFrameSizes

◆ SDL_GetVideoCaptureSpec()

int SDL_GetVideoCaptureSpec ( SDL_VideoCaptureDevice device,
SDL_VideoCaptureSpec spec 
)
extern

Get the obtained video capture spec

Parameters
deviceopened video capture device
specThe SDL_VideoCaptureSpec to be initialized by this function.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_SetVideoCaptureSpec
SDL_OpenVideoCaptureWithSpec

◆ SDL_GetVideoCaptureStatus()

SDL_VideoCaptureStatus SDL_GetVideoCaptureStatus ( SDL_VideoCaptureDevice device)
extern

Get video capture status

Parameters
deviceopened video capture device
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_VideoCaptureStatus

◆ SDL_OpenVideoCapture()

SDL_VideoCaptureDevice * SDL_OpenVideoCapture ( SDL_VideoCaptureDeviceID  instance_id)
extern

Open a Video Capture device

Parameters
instance_idthe video capture device instance ID
Returns
device, or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetVideoCaptureDeviceName
SDL_GetVideoCaptureDevices
SDL_OpenVideoCaptureWithSpec

◆ SDL_OpenVideoCaptureWithSpec()

SDL_VideoCaptureDevice * SDL_OpenVideoCaptureWithSpec ( SDL_VideoCaptureDeviceID  instance_id,
const SDL_VideoCaptureSpec desired,
SDL_VideoCaptureSpec obtained,
int  allowed_changes 
)
extern

Open a Video Capture device and set specification

Parameters
instance_idthe video capture device instance ID
desireddesired video capture spec
obtainedobtained video capture spec
allowed_changesallow changes or not
Returns
device, or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenVideoCapture
SDL_SetVideoCaptureSpec
SDL_GetVideoCaptureSpec

◆ SDL_ReleaseVideoCaptureFrame()

int SDL_ReleaseVideoCaptureFrame ( SDL_VideoCaptureDevice device,
SDL_VideoCaptureFrame frame 
)
extern

Release a frame.

Let the back-end re-use the internal buffer for video capture.

All acquired frames should be released before closing the device.

Parameters
deviceopened video capture device
frameframe pointer.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_AcquireVideoCaptureFrame

◆ SDL_SetVideoCaptureSpec()

int SDL_SetVideoCaptureSpec ( SDL_VideoCaptureDevice device,
const SDL_VideoCaptureSpec desired,
SDL_VideoCaptureSpec obtained,
int  allowed_changes 
)
extern

Set specification

Parameters
deviceopened video capture device
desireddesired video capture spec
obtainedobtained video capture spec
allowed_changesallow changes or not
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenVideoCapture
SDL_OpenVideoCaptureWithSpec
SDL_GetVideoCaptureSpec

◆ SDL_StartVideoCapture()

int SDL_StartVideoCapture ( SDL_VideoCaptureDevice device)
extern

Start video capture

Parameters
deviceopened video capture device
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StopVideoCapture

◆ SDL_StopVideoCapture()

int SDL_StopVideoCapture ( SDL_VideoCaptureDevice device)
extern

Stop Video Capture

Parameters
deviceopened video capture device
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StartVideoCapture