Video capture for the SDL library. More...

Collaboration diagram for Camera Support:

Classes
struct	SDL::CameraParam
	Safely wrap Camera for non owning parameters. More...

class	SDL::Camera
	The opaque structure used to identify an opened SDL camera. More...

struct	SDL::CameraRef
	Semi-safe reference for Camera. More...

Typedefs
using	SDL::CameraRaw = SDL_Camera *
	Alias to raw representation for Camera.

using	SDL::CameraID = SDL_CameraID
	This is a unique ID for a camera device for the time it is connected to the system, and is never reused for the lifetime of the application. More...

using	SDL::CameraSpec = SDL_CameraSpec
	The details of an output format for a camera device. More...

using	SDL::CameraPosition = SDL_CameraPosition
	The position of camera in relation to system device. More...

Functions
int	SDL::GetNumCameraDrivers ()
	Use this function to get the number of built-in camera drivers. More...

const char *	SDL::GetCameraDriver (int index)
	Use this function to get the name of a built in camera driver. More...

const char *	SDL::GetCurrentCameraDriver ()
	Get the name of the current camera driver. More...

OwnArray< CameraID >	SDL::GetCameras ()
	Get a list of currently connected camera devices. More...

SDL_CameraSpec **	SDL::GetCameraSupportedFormats (CameraID instance_id, int *count)
	Get the list of native formats/sizes a camera supports. More...

const char *	SDL::GetCameraName (CameraID instance_id)
	Get the human-readable device name for a camera. More...

CameraPosition	SDL::GetCameraPosition (CameraID instance_id)
	Get the position of the camera in relation to the system. More...

Camera	SDL::OpenCamera (CameraID instance_id, OptionalRef< const CameraSpec > spec={})
	Open a video recording device (a "camera"). More...

int	SDL::GetCameraPermissionState (CameraParam camera)
	Query if camera access has been approved by the user. More...

CameraID	SDL::GetCameraID (CameraParam camera)
	Get the instance ID of an opened camera. More...

PropertiesRef	SDL::GetCameraProperties (CameraParam camera)
	Get the properties associated with an opened camera. More...

std::optional< CameraSpec >	SDL::GetCameraFormat (CameraParam camera)
	Get the spec that a camera is using when generating images. More...

Surface	SDL::AcquireCameraFrame (CameraParam camera, Uint64 *timestampNS=nullptr)
	Acquire a frame. More...

void	SDL::ReleaseCameraFrame (CameraParam camera, SurfaceParam frame)
	Release a frame of video acquired from a camera. More...

void	SDL::CloseCamera (CameraRaw camera)
	Use this function to shut down camera processing and close the camera device. More...

int	SDL::Camera::GetPermissionState ()
	Query if camera access has been approved by the user. More...

CameraID	SDL::Camera::GetID ()
	Get the instance ID of an opened camera. More...

PropertiesRef	SDL::Camera::GetProperties ()
	Get the properties associated with an opened camera. More...

std::optional< CameraSpec >	SDL::Camera::GetFormat ()
	Get the spec that a camera is using when generating images. More...

Surface	SDL::Camera::AcquireFrame (Uint64 *timestampNS=nullptr)
	Acquire a frame. More...

void	SDL::Camera::ReleaseFrame (SurfaceParam frame)
	Release a frame of video acquired from a camera. More...

void	SDL::Camera::Close ()
	Use this function to shut down camera processing and close the camera device. More...

Variables
constexpr CameraPosition	SDL::CAMERA_POSITION_UNKNOWN
	CAMERA_POSITION_UNKNOWN. More...

constexpr CameraPosition	SDL::CAMERA_POSITION_FRONT_FACING
	CAMERA_POSITION_FRONT_FACING. More...

constexpr CameraPosition	SDL::CAMERA_POSITION_BACK_FACING
	CAMERA_POSITION_BACK_FACING. More...

Detailed Description

This API lets apps read input from video sources, like webcams. Camera devices can be enumerated, queried, and opened. Once opened, it will provide Surface objects as new frames of video come in. These surfaces can be uploaded to an Texture or processed as pixels in memory.

Several platforms will alert the user if an app tries to access a camera, and some will present a UI asking the user if your application should be allowed to obtain images at all, which they can deny. A successfully opened camera will not provide images until permission is granted. Applications, after opening a camera device, can see if they were granted access by either polling with the Camera.GetPermissionState() function, or waiting for an EVENT_CAMERA_DEVICE_APPROVED or EVENT_CAMERA_DEVICE_DENIED event. Platforms that don't have any user approval process will report approval immediately.

Note that SDL cameras only provide video as individual frames; they will not provide full-motion video encoded in a movie file format, although an app is free to encode the acquired frames into any format it likes. It also does not provide audio from the camera hardware through this API; not only do many webcams not have microphones at all, many people–from streamers to people on Zoom calls–will want to use a separate microphone regardless of the camera. In any case, recorded audio will be available through SDL's audio API no matter what hardware provides the microphone.

Camera gotchas

Consumer-level camera hardware tends to take a little while to warm up, once the device has been opened. Generally most camera apps have some sort of UI to take a picture (a button to snap a pic while a preview is showing, some sort of multi-second countdown for the user to pose, like a photo booth), which puts control in the users' hands, or they are intended to stay on for long times (Pokemon Go, etc).

It's not uncommon that a newly-opened camera will provide a couple of completely black frames, maybe followed by some under-exposed images. If taking a single frame automatically, or recording video from a camera's input without the user initiating it from a preview, it could be wise to drop the first several frames (if not the first several seconds worth of frames!) before using images from a camera.

Typedef Documentation

◆ CameraID

using SDL::CameraID = typedef SDL_CameraID

If the device is disconnected and reconnected, it will get a new ID.

The value 0 is an invalid ID.

Since: This datatype is available since SDL 3.2.0.

See also: GetCameras

◆ CameraPosition

using SDL::CameraPosition = typedef SDL_CameraPosition

Since: This enum is available since SDL 3.2.0.

See also: GetCameraPosition

◆ CameraSpec

using SDL::CameraSpec = typedef SDL_CameraSpec

Cameras often support multiple formats; each one will be encapsulated in this struct.

Since: This struct is available since SDL 3.2.0.

See also: GetCameraSupportedFormats; Camera.GetFormat

Function Documentation

◆ AcquireCameraFrame()

Surface SDL::AcquireCameraFrame	(	CameraParam	camera,
		Uint64 *	timestampNS = `nullptr`
	)

inline

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

This is a non blocking API. If there is a frame available, a non-nullptr surface is returned, and timestampNS will be filled with a non-zero value.

Note that an error case can also return nullptr, but a nullptr by itself is normal and just signifies that a new frame is not yet available. Note that even if a camera device fails outright (a USB camera is unplugged while in use, etc), SDL will send an event separately to notify the app, but continue to provide blank frames at ongoing intervals until Camera.Close() is called, so real failure here is almost always an out of memory condition.

After use, the frame should be released with Camera.ReleaseFrame(). If you don't do this, the system may stop providing more video!

Do not call Surface.Destroy() on the returned surface! It must be given back to the camera subsystem with Camera.ReleaseFrame!

If the system is waiting for the user to approve access to the camera, as some platforms require, this will return nullptr (no frames available); you should either wait for an EVENT_CAMERA_DEVICE_APPROVED (or EVENT_CAMERA_DEVICE_DENIED) event, or poll Camera.GetPermissionState() occasionally until it returns non-zero.

Parameters

camera	opened camera device.
timestampNS	a pointer filled in with the frame's timestamp, or 0 on error. Can be nullptr.

Returns: a new frame of video on success, nullptr if none is currently available.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.ReleaseFrame

◆ AcquireFrame()

Surface SDL::Camera::AcquireFrame ( Uint64 * timestampNS = nullptr )

inline

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

This is a non blocking API. If there is a frame available, a non-nullptr surface is returned, and timestampNS will be filled with a non-zero value.

Note that an error case can also return nullptr, but a nullptr by itself is normal and just signifies that a new frame is not yet available. Note that even if a camera device fails outright (a USB camera is unplugged while in use, etc), SDL will send an event separately to notify the app, but continue to provide blank frames at ongoing intervals until Camera.Close() is called, so real failure here is almost always an out of memory condition.

After use, the frame should be released with Camera.ReleaseFrame(). If you don't do this, the system may stop providing more video!

Do not call Surface.Destroy() on the returned surface! It must be given back to the camera subsystem with Camera.ReleaseFrame!

If the system is waiting for the user to approve access to the camera, as some platforms require, this will return nullptr (no frames available); you should either wait for an EVENT_CAMERA_DEVICE_APPROVED (or EVENT_CAMERA_DEVICE_DENIED) event, or poll Camera.GetPermissionState() occasionally until it returns non-zero.

Parameters

timestampNS a pointer filled in with the frame's timestamp, or 0 on error. Can be nullptr.

Returns: a new frame of video on success, nullptr if none is currently available.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.ReleaseFrame

◆ Close()

void SDL::Camera::Close ( )

inline

Thread safety:: It is safe to call this function from any thread, but no thread may reference device once this function is called.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera

◆ CloseCamera()

void SDL::CloseCamera ( CameraRaw camera )

inline

Parameters

camera opened camera device.

Thread safety:: It is safe to call this function from any thread, but no thread may reference device once this function is called.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera

◆ GetCameraDriver()

const char * SDL::GetCameraDriver ( int index )

inline

The list of camera drivers is given in the order that they are normally initialized by default; the drivers that seem more reasonable to choose first (as far as the SDL developers believe) are earlier in the list.

The names of drivers are all simple, low-ASCII identifiers, like "v4l2", "coremedia" or "android". These never have Unicode characters, and are not meant to be proper names.

Parameters

index the index of the camera driver; the value ranges from 0 to GetNumCameraDrivers() - 1.

Returns: the name of the camera driver at the requested index, or nullptr if an invalid index was specified.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetNumCameraDrivers

◆ GetCameraFormat()

std::optional< CameraSpec > SDL::GetCameraFormat ( CameraParam camera )

inline

Note that this might not be the native format of the hardware, as SDL might be converting to this format behind the scenes.

If the system is waiting for the user to approve access to the camera, as some platforms require, this will return false, but this isn't necessarily a fatal error; you should either wait for an EVENT_CAMERA_DEVICE_APPROVED (or EVENT_CAMERA_DEVICE_DENIED) event, or poll Camera.GetPermissionState() occasionally until it returns non-zero.

Parameters

camera opened camera device.

Returns: the CameraSpec or std::nullopt if waiting for user approval.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera

◆ GetCameraID()

CameraID SDL::GetCameraID ( CameraParam camera )

inline

Parameters

camera an Camera to query.

Returns: the instance ID of the specified camera on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera

◆ GetCameraName()

const char * SDL::GetCameraName ( CameraID instance_id )

inline

Parameters

instance_id the camera device instance ID.

Returns: a human-readable device name or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetCameras

◆ GetCameraPermissionState()

int SDL::GetCameraPermissionState ( CameraParam camera )

inline

Cameras will not function between when the device is opened by the app and when the user permits access to the hardware. On some platforms, this presents as a popup dialog where the user has to explicitly approve access; on others the approval might be implicit and not alert the user at all.

This function can be used to check the status of that approval. It will return 0 if still waiting for user response, 1 if the camera is approved for use, and -1 if the user denied access.

Instead of polling with this function, you can wait for a EVENT_CAMERA_DEVICE_APPROVED (or EVENT_CAMERA_DEVICE_DENIED) event in the standard SDL event loop, which is guaranteed to be sent once when permission to use the camera is decided.

If a camera is declined, there's nothing to be done but call Camera.Close() to dispose of it.

Parameters

camera the opened camera device to query.

Returns: -1 if user denied access to the camera, 1 if user approved access, 0 if no decision has been made yet.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera; Camera.Close

◆ GetCameraPosition()

CameraPosition SDL::GetCameraPosition ( CameraID instance_id )

inline

Most platforms will report UNKNOWN, but mobile devices, like phones, can often make a distinction between cameras on the front of the device (that points towards the user, for taking "selfies") and cameras on the back (for filming in the direction the user is facing).

Parameters

instance_id the camera device instance ID.

Returns: the position of the camera on the system hardware.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetCameras

◆ GetCameraProperties()

PropertiesRef SDL::GetCameraProperties ( CameraParam camera )

inline

Parameters

camera the Camera obtained from Camera.Camera().

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetCameras()

OwnArray< CameraID > SDL::GetCameras ( )

inline

Parameters

count a pointer filled in with the number of cameras returned, may be nullptr.

Returns: a 0 terminated array of camera instance IDs or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera

◆ GetCameraSupportedFormats()

SDL_CameraSpec ** SDL::GetCameraSupportedFormats	(	CameraID	instance_id,
		int *	count
	)

inline

This returns a list of all formats and frame sizes that a specific camera can offer. This is useful if your app can accept a variety of image formats and sizes and so want to find the optimal spec that doesn't require conversion.

This function isn't strictly required; if you call Camera.Camera with a nullptr spec, SDL will choose a native format for you, and if you instead specify a desired format, it will transparently convert to the requested format on your behalf.

If count is not nullptr, it will be filled with the number of elements in the returned array.

Note that it's legal for a camera to supply an empty list. This is what will happen on Emscripten builds, since that platform won't tell anything about available cameras until you've opened one, and won't even tell if there is a camera until the user has given you permission to check through a scary warning popup.

Parameters

instance_id	the camera device instance ID.
count	a pointer filled in with the number of elements in the list, may be nullptr.

Returns: a nullptr terminated array of pointers to CameraSpec or nullptr on failure; call GetError() for more information. This is a single allocation that should be freed with free() when it is no longer needed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetCameras; Camera.Camera

◆ GetCurrentCameraDriver()

const char * SDL::GetCurrentCameraDriver ( )

inline

The names of drivers are all simple, low-ASCII identifiers, like "v4l2", "coremedia" or "android". These never have Unicode characters, and are not meant to be proper names.

Returns: the name of the current camera driver or nullptr if no driver has been initialized.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetFormat()

std::optional< CameraSpec > SDL::Camera::GetFormat ( )

inline

Note that this might not be the native format of the hardware, as SDL might be converting to this format behind the scenes.

If the system is waiting for the user to approve access to the camera, as some platforms require, this will return false, but this isn't necessarily a fatal error; you should either wait for an EVENT_CAMERA_DEVICE_APPROVED (or EVENT_CAMERA_DEVICE_DENIED) event, or poll Camera.GetPermissionState() occasionally until it returns non-zero.

Returns: the CameraSpec or std::nullopt if waiting for user approval.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera

◆ GetID()

CameraID SDL::Camera::GetID ( )

inline

Returns: the instance ID of the specified camera on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera

◆ GetNumCameraDrivers()

int SDL::GetNumCameraDrivers ( )

inline

This function returns a hardcoded number. This never returns a negative value; if there are no drivers compiled into this build of SDL, this function returns zero. The presence of a driver in this list does not mean it will function, it just means SDL is capable of interacting with that interface. For example, a build of SDL might have v4l2 support, but if there's no kernel support available, SDL's v4l2 driver would fail if used.

By default, SDL tries all drivers, in its preferred order, until one is found to be usable.

Returns: the number of built-in camera drivers.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetCameraDriver

◆ GetPermissionState()

int SDL::Camera::GetPermissionState ( )

inline

Cameras will not function between when the device is opened by the app and when the user permits access to the hardware. On some platforms, this presents as a popup dialog where the user has to explicitly approve access; on others the approval might be implicit and not alert the user at all.

This function can be used to check the status of that approval. It will return 0 if still waiting for user response, 1 if the camera is approved for use, and -1 if the user denied access.

Instead of polling with this function, you can wait for a EVENT_CAMERA_DEVICE_APPROVED (or EVENT_CAMERA_DEVICE_DENIED) event in the standard SDL event loop, which is guaranteed to be sent once when permission to use the camera is decided.

If a camera is declined, there's nothing to be done but call Camera.Close() to dispose of it.

Returns: -1 if user denied access to the camera, 1 if user approved access, 0 if no decision has been made yet.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.Camera; Camera.Close

◆ GetProperties()

PropertiesRef SDL::Camera::GetProperties ( )

inline

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ OpenCamera()

Camera SDL::OpenCamera	(	CameraID	instance_id,
		OptionalRef< const CameraSpec >	spec = `{}`
	)

inline

You can open the device with any reasonable spec, and if the hardware can't directly support it, it will convert data seamlessly to the requested format. This might incur overhead, including scaling of image data.

If you would rather accept whatever format the device offers, you can pass a nullptr spec here and it will choose one for you (and you can use Surface's conversion/scaling functions directly if necessary).

You can call Camera.GetFormat() to get the actual data format if passing a nullptr spec here. You can see the exact specs a device can support without conversion with GetCameraSupportedFormats().

SDL will not attempt to emulate framerate; it will try to set the hardware to the rate closest to the requested speed, but it won't attempt to limit or duplicate frames artificially; call Camera.GetFormat() to see the actual framerate of the opened the device, and check your timestamps if this is crucial to your app!

Note that the camera is not usable until the user approves its use! On some platforms, the operating system will prompt the user to permit access to the camera, and they can choose Yes or No at that point. Until they do, the camera will not be usable. The app should either wait for an EVENT_CAMERA_DEVICE_APPROVED (or EVENT_CAMERA_DEVICE_DENIED) event, or poll Camera.GetPermissionState() occasionally until it returns non-zero. On platforms that don't require explicit user approval (and perhaps in places where the user previously permitted access), the approval event might come immediately, but it might come seconds, minutes, or hours later!

Parameters

instance_id	the camera device instance ID.
spec	the desired format for data the device will provide. Can be std::nullopt.

Returns: an Camera object on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetCameras; Camera.GetFormat

◆ ReleaseCameraFrame()

void SDL::ReleaseCameraFrame	(	CameraParam	camera,
		SurfaceParam	frame
	)

inline

Let the back-end re-use the internal buffer for camera.

This function must be called only on surface objects returned by Camera.AcquireFrame(). This function should be called as quickly as possible after acquisition, as SDL keeps a small FIFO queue of surfaces for video frames; if surfaces aren't released in a timely manner, SDL may drop upcoming video frames from the camera.

If the app needs to keep the surface for a significant time, they should make a copy of it and release the original.

The app should not use the surface again after calling this function; assume the surface is freed and the pointer is invalid.

Parameters

camera	opened camera device.
frame	the video frame surface to release.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.AcquireFrame

◆ ReleaseFrame()

void SDL::Camera::ReleaseFrame ( SurfaceParam frame )

inline

Let the back-end re-use the internal buffer for camera.

This function must be called only on surface objects returned by Camera.AcquireFrame(). This function should be called as quickly as possible after acquisition, as SDL keeps a small FIFO queue of surfaces for video frames; if surfaces aren't released in a timely manner, SDL may drop upcoming video frames from the camera.

If the app needs to keep the surface for a significant time, they should make a copy of it and release the original.

The app should not use the surface again after calling this function; assume the surface is freed and the pointer is invalid.

Parameters

frame the video frame surface to release.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Camera.AcquireFrame

Variable Documentation

◆ CAMERA_POSITION_BACK_FACING

constexpr CameraPosition SDL::CAMERA_POSITION_BACK_FACING

constexpr

Initial value:

=

SDL_CAMERA_POSITION_BACK_FACING

◆ CAMERA_POSITION_FRONT_FACING

constexpr CameraPosition SDL::CAMERA_POSITION_FRONT_FACING

constexpr

Initial value:

=

SDL_CAMERA_POSITION_FRONT_FACING

◆ CAMERA_POSITION_UNKNOWN

constexpr CameraPosition SDL::CAMERA_POSITION_UNKNOWN

constexpr

Initial value:

=

SDL_CAMERA_POSITION_UNKNOWN

Classes

Typedefs

Functions

Variables

Detailed Description

Camera gotchas

Typedef Documentation

◆ CameraID

◆ CameraPosition

◆ CameraSpec

Function Documentation

◆ AcquireCameraFrame()

◆ AcquireFrame()

◆ Close()

◆ CloseCamera()

◆ GetCameraDriver()

◆ GetCameraFormat()

◆ GetCameraID()

◆ GetCameraName()

◆ GetCameraPermissionState()

◆ GetCameraPosition()

◆ GetCameraProperties()

◆ GetCameras()

◆ GetCameraSupportedFormats()

◆ GetCurrentCameraDriver()

◆ GetFormat()

◆ GetID()

◆ GetNumCameraDrivers()

◆ GetPermissionState()

◆ GetProperties()

◆ OpenCamera()

◆ ReleaseCameraFrame()

◆ ReleaseFrame()

Variable Documentation

◆ CAMERA_POSITION_BACK_FACING

◆ CAMERA_POSITION_FRONT_FACING

◆ CAMERA_POSITION_UNKNOWN