NAME¶

SDL_AcquireCameraFrame - Acquire a frame.

HEADER FILE¶

Defined in SDL3/SDL_camera.h

SYNOPSIS¶

#include "SDL3/SDL.h"

SDL_Surface * SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS);

DESCRIPTION¶

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-NULL surface is returned, and timestampNS will be filled with a non-zero value.

Note that an error case can also return NULL, but a NULL 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

SDL_CloseCamera () is called, so real failure here is almost always an out of memory condition.

After use, the frame should be released with

SDL_ReleaseCameraFrame (). If you don't do this, the system may stop providing more video!

Do not call SDL_FreeSurface () on the returned surface! It must be given back to the camera subsystem with

SDL_ReleaseCameraFrame !

If the system is waiting for the user to approve access to the camera, as some platforms require, this will return NULL (no frames available); you should either wait for an

SDL_EVENT_CAMERA_DEVICE_APPROVED
(or

SDL_EVENT_CAMERA_DEVICE_DENIED ) event, or poll SDL_GetCameraPermissionState () occasionally until it returns non-zero.

FUNCTION PARAMETERS¶

camera

opened camera device.

timestampNS

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

RETURN VALUE¶

( SDL_Surface
*) Returns a new frame of video on success, NULL if none is currently available.

THREAD SAFETY¶

It is safe to call this function from any thread.

AVAILABILITY¶

This function is available since SDL 3.1.3.

SEE ALSO¶

•(3), SDL_ReleaseCameraFrame(3)