camera topic

CategoryCamera

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.

Functions

sdlAcquireCameraFrame(Pointer<SdlCamera> camera, Pointer<Uint64> timestampNs) → Pointer<SdlSurface> camera
Acquire a frame.
sdlCloseCamera(Pointer<SdlCamera> camera) → void camera
Use this function to shut down camera processing and close the camera device.
sdlGetCameraDriver(int index) → String? camera
Use this function to get the name of a built in camera driver.
sdlGetCameraFormat(Pointer<SdlCamera> camera, Pointer<SdlCameraSpec> spec) → bool camera
Get the spec that a camera is using when generating images.
sdlGetCameraId(Pointer<SdlCamera> camera) → int camera
Get the instance ID of an opened camera.
sdlGetCameraName(int instanceId) → String? camera
Get the human-readable device name for a camera.
sdlGetCameraPermissionState(Pointer<SdlCamera> camera) → int camera
Query if camera access has been approved by the user.
sdlGetCameraPosition(int instanceId) → int camera
Get the position of the camera in relation to the system.
sdlGetCameraProperties(Pointer<SdlCamera> camera) → int camera
Get the properties associated with an opened camera.
sdlGetCameras(Pointer<Int32> count) → Pointer<Uint32> camera
Get a list of currently connected camera devices.
sdlGetCameraSupportedFormats(int instanceId, Pointer<Int32> count) → Pointer<Pointer<SdlCameraSpec>> camera
Get the list of native formats/sizes a camera supports.
sdlGetCurrentCameraDriver() → String? camera
Get the name of the current camera driver.
sdlGetNumCameraDrivers() → int camera
Use this function to get the number of built-in camera drivers.
sdlOpenCamera(int instanceId, Pointer<SdlCameraSpec> spec) → Pointer<SdlCamera> camera
Open a video recording device (a "camera").
sdlReleaseCameraFrame(Pointer<SdlCamera> camera, Pointer<SdlSurface> frame) → void camera
Release a frame of video acquired from a camera.