diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h index e4ac69a88..1b81edad9 100644 --- a/include/SDL3/SDL_camera.h +++ b/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. *