Sync SDL3 wiki -> header

include/SDL3/SDL_camera.h

@@ -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.
  *