Module camera

Available on crate feature dep_sdl3 only.

Video capture for the SDL library.

This API lets apps read input from video sources, like webcams. Camera devices can be enumerated, queried, and opened. Once opened, it will provide SDL_Surface objects as new frames of video come in. These surfaces can be uploaded to an [SDL_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 SDL_GetCameraPermissionState() function, or waiting for an [SDL_EVENT_CAMERA_DEVICE_APPROVED] or [SDL_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.

Structs

SDL_Camera

The opaque structure used to identify an opened SDL camera.

SDL_CameraPosition

The position of camera in relation to system device.

SDL_CameraSpec

The details of an output format for a camera device.

Constants

SDL_CAMERA_POSITION_BACK_FACING

SDL_CAMERA_POSITION_FRONT_FACING

SDL_CAMERA_POSITION_UNKNOWN

Functions

SDL_AcquireCameraFrame^⚠

Acquire a frame.

SDL_CloseCamera^⚠

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

SDL_GetCameraDriver^⚠

Use this function to get the name of a built in camera driver.

SDL_GetCameraFormat^⚠

Get the spec that a camera is using when generating images.

SDL_GetCameraID^⚠

Get the instance ID of an opened camera.

SDL_GetCameraName^⚠

Get the human-readable device name for a camera.

SDL_GetCameraPermissionState^⚠

Query if camera access has been approved by the user.

SDL_GetCameraPosition^⚠

Get the position of the camera in relation to the system.

SDL_GetCameraProperties^⚠

Get the properties associated with an opened camera.

SDL_GetCameraSupportedFormats^⚠

Get the list of native formats/sizes a camera supports.

SDL_GetCameras^⚠

Get a list of currently connected camera devices.

SDL_GetCurrentCameraDriver^⚠

Get the name of the current camera driver.

SDL_GetNumCameraDrivers^⚠

Use this function to get the number of built-in camera drivers.

SDL_OpenCamera^⚠

Open a video recording device (a “camera”).

SDL_ReleaseCameraFrame^⚠

Release a frame of video acquired from a camera.

Type Aliases

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.