Sync SDL3 wiki -> header
SDL Wiki Bot
parent
f59c66a97f
commit
31fe061ab5
|
|
@ -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.
|
||||
*
|
||||
|
|
|
|||
Loading…
Reference in New Issue