mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-10-26 12:27:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source
This commit is contained in:
SDL Wiki Bot
2024-02-20 20:57:27 +00:00
parent f59c66a97f
commit 31fe061ab5
1 changed files with 75 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
include/SDL3/SDL_camera.h
View File

@@ -119,8 +119,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
*
* \param index the index of the camera driver; the value ranges from 0 to
* SDL_GetNumCameraDrivers() - 1
* \returns the name of the camera driver at the requested index, or NULL if an
* invalid index was specified.
* \returns the name of the camera driver at the requested index, or NULL if
* an invalid index was specified.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -139,8 +139,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetCameraDriver(int index);
* call to this function, of course). As such, you should not modify or free
* the returned string.
*
* \returns the name of the current camera driver or NULL if no driver has been
* initialized.
* \returns the name of the current camera driver or NULL if no driver has
* been initialized.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -151,10 +151,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentCameraDriver(void);
/**
* Get a list of currently connected camera devices.
*
* \param count a pointer filled in with the number of camera devices. Can be NULL.
* \returns a 0 terminated array of camera instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* \param count a pointer filled in with the number of camera devices. Can be
* NULL.
* \returns a 0 terminated array of camera instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -167,19 +168,19 @@ extern DECLSPEC SDL_CameraDeviceID *SDLCALL SDL_GetCameraDevices(int *count);
/**
* Get the list of native formats/sizes a camera supports.
*
* This returns a list of all formats and frame sizes that a specific
* camera can offer. This is useful if your app can accept a variety
* of image formats and sizes and so want to find the optimal spec
* that doesn't require conversion.
* This returns a list of all formats and frame sizes that a specific camera
* can offer. This is useful if your app can accept a variety of image formats
* and sizes and so want to find the optimal spec that doesn't require
* conversion.
*
* This function isn't strictly required; if you call SDL_OpenCameraDevice
* with a NULL spec, SDL will choose a native format for you, and if you
* instead specify a desired format, it will transparently convert to the
* requested format on your behalf.
*
* If `count` is not NULL, it will be filled with the number of elements
* in the returned array. Additionally, the last element of the array
* has all fields set to zero (this element is not included in `count`).
* If `count` is not NULL, it will be filled with the number of elements in
* the returned array. Additionally, the last element of the array has all
* fields set to zero (this element is not included in `count`).
*
* The returned list is owned by the caller, and should be released with
* SDL_free() when no longer needed.
@@ -188,14 +189,15 @@ extern DECLSPEC SDL_CameraDeviceID *SDLCALL SDL_GetCameraDevices(int *count);
* final element and `*count` set to zero; this is what will happen on
* Emscripten builds, since that platform won't tell _anything_ about
* available cameras until you've opened one, and won't even tell if there
* _is_ a camera until the user has given you permission to check through
* a scary warning popup.
* _is_ a camera until the user has given you permission to check through a
* scary warning popup.
*
* \param devid the camera device instance ID to query.
* \param count a pointer filled in with the number of elements in the list. Can be NULL.
* \returns a 0 terminated array of SDL_CameraSpecs, which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* \param count a pointer filled in with the number of elements in the list.
* Can be NULL.
* \returns a 0 terminated array of SDL_CameraSpecs, which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -213,7 +215,8 @@ extern DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraDeviceSupportedFormats(SDL_
* SDL_free() when done with it.
*
* \param instance_id the camera device instance ID
* \returns Human-readable device name, or NULL on error; call SDL_GetError() for more information.
* \returns Human-readable device name, or NULL on error; call SDL_GetError()
* for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -228,8 +231,8 @@ extern DECLSPEC char * SDLCALL SDL_GetCameraDeviceName(SDL_CameraDeviceID instan
*
* Most platforms will report UNKNOWN, but mobile devices, like phones, can
* often make a distiction between cameras on the front of the device (that
* points towards the user, for taking "selfies") and cameras on the back
* (for filming in the direction the user is facing).
* points towards the user, for taking "selfies") and cameras on the back (for
* filming in the direction the user is facing).
*
* \param instance_id the camera device instance ID
* \returns The position of the camera on the system hardware.
@@ -249,24 +252,24 @@ extern DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraDevicePosition(SDL_Camer
* directly support it, it will convert data seamlessly to the requested
* format. This might incur overhead, including scaling of image data.
*
* If you would rather accept whatever format the device offers, you can
* pass a NULL spec here and it will choose one for you (and you can use
* If you would rather accept whatever format the device offers, you can pass
* a NULL spec here and it will choose one for you (and you can use
* SDL_Surface's conversion/scaling functions directly if necessary).
*
* You can call SDL_GetCameraFormat() to get the actual data format if
* passing a NULL spec here. You can see the exact specs a device can
* support without conversion with SDL_GetCameraSupportedSpecs().
* You can call SDL_GetCameraFormat() to get the actual data format if passing
* a NULL spec here. You can see the exact specs a device can support without
* conversion with SDL_GetCameraSupportedSpecs().
*
* SDL will not attempt to emulate framerate; it will try to set the
* hardware to the rate closest to the requested speed, but it won't
* attempt to limit or duplicate frames artificially; call
* SDL_GetCameraFormat() to see the actual framerate of the opened the device,
* and check your timestamps if this is crucial to your app!
* SDL will not attempt to emulate framerate; it will try to set the hardware
* to the rate closest to the requested speed, but it won't attempt to limit
* or duplicate frames artificially; call SDL_GetCameraFormat() to see the
* actual framerate of the opened the device, and check your timestamps if
* this is crucial to your app!
*
* Note that the camera is not usable until the user approves its use! On
* some platforms, the operating system will prompt the user to permit access
* to the camera, and they can choose Yes or No at that point. Until they do,
* the camera will not be usable. The app should either wait for an
* Note that the camera is not usable until the user approves its use! On some
* platforms, the operating system will prompt the user to permit access to
* the camera, and they can choose Yes or No at that point. Until they do, the
* camera will not be usable. The app should either wait for an
* SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event,
* or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On
* platforms that don't require explicit user approval (and perhaps in places
@@ -274,7 +277,8 @@ extern DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraDevicePosition(SDL_Camer
* immediately, but it might come seconds, minutes, or hours later!
*
* \param instance_id the camera device instance ID
* \param spec The desired format for data the device will provide. Can be NULL.
* \param spec The desired format for data the device will provide. Can be
* NULL.
* \returns device, or NULL on failure; call SDL_GetError() for more
* information.
*
@@ -290,8 +294,8 @@ extern DECLSPEC SDL_Camera *SDLCALL SDL_OpenCameraDevice(SDL_CameraDeviceID inst
/**
* Query if camera access has been approved by the user.
*
* Cameras will not function between when the device is opened by the app
* and when the user permits access to the hardware. On some platforms, this
* Cameras will not function between when the device is opened by the app and
* when the user permits access to the hardware. On some platforms, this
* presents as a popup dialog where the user has to explicitly approve access;
* on others the approval might be implicit and not alert the user at all.
*
@@ -308,7 +312,8 @@ extern DECLSPEC SDL_Camera *SDLCALL SDL_OpenCameraDevice(SDL_CameraDeviceID inst
* SDL_CloseCamera() to dispose of it.
*
* \param camera the opened camera device to query
* \returns -1 if user denied access to the camera, 1 if user approved access, 0 if no decision has been made yet.
* \returns -1 if user denied access to the camera, 1 if user approved access,
* 0 if no decision has been made yet.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -353,8 +358,8 @@ extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *cam
/**
* Get the spec that a camera is using when generating images.
*
* Note that this might not be the native format of the hardware, as SDL
* might be converting to this format behind the scenes.
* Note that this might not be the native format of the hardware, as SDL might
* be converting to this format behind the scenes.
*
* If the system is waiting for the user to approve access to the camera, as
* some platforms require, this will return -1, but this isn't necessarily a
@@ -381,31 +386,34 @@ extern DECLSPEC int SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSp
* 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.
* 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.
* 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!
* 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!
* 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
* 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_IsCameraApproved()
* occasionally until it returns non-zero.
*
* \param camera opened camera device
* \param timestampNS a pointer filled in with the frame's timestamp, or 0 on error. Can be NULL.
* \returns A new frame of video on success, NULL if none is currently available.
* \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
* error. Can be NULL.
* \returns A new frame of video on success, NULL if none is currently
* available.
*
* \threadsafety It is safe to call this function from any thread.
*
@@ -422,9 +430,9 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *camera,
*
* This function _must_ be called only on surface objects returned by
* SDL_AcquireCameraFrame(). This function should be called as quickly as
* possible after acquisition, as SDL keeps a small FIFO queue of surfaces
* for video frames; if surfaces aren't released in a timely manner, SDL
* may drop upcoming video frames from the camera.
* possible after acquisition, as SDL keeps a small FIFO queue of surfaces for
* video frames; if surfaces aren't released in a timely manner, SDL may drop
* upcoming video frames from the camera.
*
* If the app needs to keep the surface for a significant time, they should
* make a copy of it and release the original.
@@ -446,14 +454,13 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *camera,
extern DECLSPEC int SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame);
/**
* Use this function to shut down camera processing and close the
* camera device.
* Use this function to shut down camera processing and close the camera
* device.
*
* \param camera opened camera device
*
* \threadsafety It is safe to call this function from any thread, but
* no thread may reference `device` once this function
* is called.
* \threadsafety It is safe to call this function from any thread, but no
* thread may reference `device` once this function is called.
*
* \since This function is available since SDL 3.0.0.
*