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_DestroySurface () 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.2.0.

SEE ALSO

       •(3), SDL_ReleaseCameraFrame(3)

Simple Directmedia Layer                            SDL 3.2.8                          SDL_AcquireCameraFrame(3)