mirrors/SDL
1
0
Fork 0
Code Issues Pull Requests 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
Show Stats 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 * \param index the index of the camera driver; the value ranges from 0 to
* SDL_GetNumCameraDrivers() - 1 * SDL_GetNumCameraDrivers() - 1
* \returns the name of the camera driver at the requested index, or NULL if an * \returns the name of the camera driver at the requested index, or NULL if
* invalid index was specified. * an invalid index was specified.
* *
* \threadsafety It is safe to call this function from any thread. * \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 * call to this function, of course). As such, you should not modify or free
* the returned string. * the returned string.
* *
* \returns the name of the current camera driver or NULL if no driver has been * \returns the name of the current camera driver or NULL if no driver has
* initialized. * been initialized.
* *
* \threadsafety It is safe to call this function from any thread. * \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. * Get a list of currently connected camera devices.
* *
* \param count a pointer filled in with the number of camera devices. Can be NULL. * \param count a pointer filled in with the number of camera devices. Can be
* \returns a 0 terminated array of camera instance IDs which should be * NULL.
* freed with SDL_free(), or NULL on error; call SDL_GetError() for * \returns a 0 terminated array of camera instance IDs which should be freed
* more details. * with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* *
* \threadsafety It is safe to call this function from any thread. * \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. * Get the list of native formats/sizes a camera supports.
* *
* This returns a list of all formats and frame sizes that a specific * This returns a list of all formats and frame sizes that a specific camera
* camera can offer. This is useful if your app can accept a variety * can offer. This is useful if your app can accept a variety of image formats
* of image formats and sizes and so want to find the optimal spec * and sizes and so want to find the optimal spec that doesn't require
* that doesn't require conversion. * conversion.
* *
* This function isn't strictly required; if you call SDL_OpenCameraDevice * 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 * 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 * instead specify a desired format, it will transparently convert to the
* requested format on your behalf. * requested format on your behalf.
* *
* If `count` is not NULL, it will be filled with the number of elements * If `count` is not NULL, it will be filled with the number of elements in
* in the returned array. Additionally, the last element of the array * the returned array. Additionally, the last element of the array has all
* has all fields set to zero (this element is not included in `count`). * fields set to zero (this element is not included in `count`).
* *
* The returned list is owned by the caller, and should be released with * The returned list is owned by the caller, and should be released with
* SDL_free() when no longer needed. * 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 * final element and `*count` set to zero; this is what will happen on
* Emscripten builds, since that platform won't tell _anything_ about * Emscripten builds, since that platform won't tell _anything_ about
* available cameras until you've opened one, and won't even tell if there * 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 * _is_ a camera until the user has given you permission to check through a
* a scary warning popup. * scary warning popup.
* *
* \param devid the camera device instance ID to query. * \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. * \param count a pointer filled in with the number of elements in the list.
* \returns a 0 terminated array of SDL_CameraSpecs, which should be * Can be NULL.
* freed with SDL_free(), or NULL on error; call SDL_GetError() for * \returns a 0 terminated array of SDL_CameraSpecs, which should be freed
* more details. * with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* *
* \threadsafety It is safe to call this function from any thread. * \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. * SDL_free() when done with it.
* *
* \param instance_id the camera device instance ID * \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. * \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 * Most platforms will report UNKNOWN, but mobile devices, like phones, can
* often make a distiction between cameras on the front of the device (that * 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 * points towards the user, for taking "selfies") and cameras on the back (for
* (for filming in the direction the user is facing). * filming in the direction the user is facing).
* *
* \param instance_id the camera device instance ID * \param instance_id the camera device instance ID
* \returns The position of the camera on the system hardware. * \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 * directly support it, it will convert data seamlessly to the requested
* format. This might incur overhead, including scaling of image data. * format. This might incur overhead, including scaling of image data.
* *
* If you would rather accept whatever format the device offers, you can * If you would rather accept whatever format the device offers, you can pass
* pass a NULL spec here and it will choose one for you (and you can use * a NULL spec here and it will choose one for you (and you can use
* SDL_Surface's conversion/scaling functions directly if necessary). * SDL_Surface's conversion/scaling functions directly if necessary).
* *
* You can call SDL_GetCameraFormat() to get the actual data format if * You can call SDL_GetCameraFormat() to get the actual data format if passing
* passing a NULL spec here. You can see the exact specs a device can * a NULL spec here. You can see the exact specs a device can support without
* support without conversion with SDL_GetCameraSupportedSpecs(). * conversion with SDL_GetCameraSupportedSpecs().
* *
* SDL will not attempt to emulate framerate; it will try to set the * SDL will not attempt to emulate framerate; it will try to set the hardware
* hardware to the rate closest to the requested speed, but it won't * to the rate closest to the requested speed, but it won't attempt to limit
* attempt to limit or duplicate frames artificially; call * or duplicate frames artificially; call SDL_GetCameraFormat() to see the
* SDL_GetCameraFormat() to see the actual framerate of the opened the device, * actual framerate of the opened the device, and check your timestamps if
* and check your timestamps if this is crucial to your app! * this is crucial to your app!
* *
* Note that the camera is not usable until the user approves its use! On * Note that the camera is not usable until the user approves its use! On some
* some platforms, the operating system will prompt the user to permit access * platforms, the operating system will prompt the user to permit access to
* to the camera, and they can choose Yes or No at that point. Until they do, * the camera, and they can choose Yes or No at that point. Until they do, the
* the camera will not be usable. The app should either wait for an * camera will not be usable. The app should either wait for an
* SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event,
* or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On
* platforms that don't require explicit user approval (and perhaps in places * 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! * immediately, but it might come seconds, minutes, or hours later!
* *
* \param instance_id the camera device instance ID * \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 * \returns device, or NULL on failure; call SDL_GetError() for more
* information. * 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. * Query if camera access has been approved by the user.
* *
* Cameras will not function between when the device is opened by the app * Cameras will not function between when the device is opened by the app and
* and when the user permits access to the hardware. On some platforms, this * 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; * 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. * 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. * SDL_CloseCamera() to dispose of it.
* *
* \param camera the opened camera device to query * \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. * \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. * 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 * Note that this might not be the native format of the hardware, as SDL might
* might be converting to this format behind the scenes. * be converting to this format behind the scenes.
* *
* If the system is waiting for the user to approve access to the camera, as * 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 * 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 * The frame is a memory pointer to the image data, whose size and format are
* given by the spec requested when opening the device. * 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 * This is a non blocking API. If there is a frame available, a non-NULL
* returned, and timestampNS will be filled with a non-zero value. * 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 * Note that an error case can also return NULL, but a NULL by itself is
* and just signifies that a new frame is not yet available. Note that even if a * normal and just signifies that a new frame is not yet available. Note that
* camera device fails outright (a USB camera is unplugged while in use, etc), SDL * even if a camera device fails outright (a USB camera is unplugged while in
* will send an event separately to notify the app, but continue to provide blank * use, etc), SDL will send an event separately to notify the app, but
* frames at ongoing intervals until SDL_CloseCamera() is called, so real * continue to provide blank frames at ongoing intervals until
* failure here is almost always an out of memory condition. * 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 * After use, the frame should be released with SDL_ReleaseCameraFrame(). If
* don't do this, the system may stop providing more video! * 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 * Do not call SDL_FreeSurface() on the returned surface! It must be given
* to the camera subsystem with SDL_ReleaseCameraFrame! * back to the camera subsystem with SDL_ReleaseCameraFrame!
* *
* If the system is waiting for the user to approve access to the camera, as * 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 * some platforms require, this will return NULL (no frames available); you
* either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or
* SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved() * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved()
* occasionally until it returns non-zero. * occasionally until it returns non-zero.
* *
* \param camera opened camera device * \param camera opened camera device
* \param timestampNS a pointer filled in with the frame's timestamp, or 0 on error. Can be NULL. * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
* \returns A new frame of video on success, NULL if none is currently available. * 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. * \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 * This function _must_ be called only on surface objects returned by
* SDL_AcquireCameraFrame(). This function should be called as quickly as * SDL_AcquireCameraFrame(). This function should be called as quickly as
* possible after acquisition, as SDL keeps a small FIFO queue of surfaces * possible after acquisition, as SDL keeps a small FIFO queue of surfaces for
* for video frames; if surfaces aren't released in a timely manner, SDL * video frames; if surfaces aren't released in a timely manner, SDL may drop
* may drop upcoming video frames from the camera. * upcoming video frames from the camera.
* *
* If the app needs to keep the surface for a significant time, they should * If the app needs to keep the surface for a significant time, they should
* make a copy of it and release the original. * 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); extern DECLSPEC int SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_Surface *frame);
/** /**
* Use this function to shut down camera processing and close the * Use this function to shut down camera processing and close the camera
* camera device. * device.
* *
* \param camera opened camera device * \param camera opened camera device
* *
* \threadsafety It is safe to call this function from any thread, but * \threadsafety It is safe to call this function from any thread, but no
* no thread may reference `device` once this function * thread may reference `device` once this function is called.
* is called.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *