.\" This manpage content is licensed under Creative Commons
.\"  Attribution 4.0 International (CC BY 4.0)
.\"   https://creativecommons.org/licenses/by/4.0/
.\" This manpage was generated from SDL's wiki page for SDL_AcquireCameraFrame:
.\"   https://wiki.libsdl.org/SDL_AcquireCameraFrame
.\" Generated with SDL/build-scripts/wikiheaders.pl
.\"  revision SDL-3.1.0
.\" Please report issues in this manpage's content at:
.\"   https://github.com/libsdl-org/sdlwiki/issues/new
.\" Please report issues in the generation of this manpage from the wiki at:
.\"   https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20SDL_AcquireCameraFrame
.\" SDL can be found at https://libsdl.org/
.de URL
\$2 \(laURL: \$1 \(ra\$3
..
.if \n[.g] .mso www.tmac
.TH SDL_AcquireCameraFrame 3 "SDL 3.1.0" "SDL" "SDL3 FUNCTIONS"
.SH NAME
SDL_AcquireCameraFrame \- Acquire a frame\[char46]
.SH SYNOPSIS
.nf
.B #include \(dqSDL3/SDL.h\(dq
.PP
.BI "SDL_Surface * SDL_AcquireCameraFrame(SDL_Camera *camera, Uint64 *timestampNS);
.fi
.SH 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\[char46]

This is a non blocking API\[char46] If there is a frame available, a non-NULL
surface is returned, and timestampNS will be filled with a non-zero value\[char46]

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\[char46] 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

.BR SDL_CloseCamera
() is called, so real failure here is
almost always an out of memory condition\[char46]

After use, the frame should be released with

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

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

.BR 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

.BR SDL_EVENT_CAMERA_DEVICE_APPROVED
 (or

.BR SDL_EVENT_CAMERA_DEVICE_DENIED
) event, or
poll 
.BR SDL_IsCameraApproved
() occasionally until it
returns non-zero\[char46]

.SH FUNCTION PARAMETERS
.TP
.I camera
opened camera device
.TP
.I timestampNS
a pointer filled in with the frame's timestamp, or 0 on error\[char46] Can be NULL\[char46]
.SH RETURN VALUE
Returns A new frame of video on success, NULL if none is currently
available\[char46]

.SH THREAD SAFETY
It is safe to call this function from any thread\[char46]

.SH AVAILABILITY
This function is available since SDL 3\[char46]0\[char46]0\[char46]

.SH SEE ALSO
.BR SDL_ReleaseCameraFrame (3)