TSdlCamera
SDL Camera.
Definition
Unit: Neslib.Sdl3.Video
Properties
| Name | Description |
|---|---|
| Format | The spec that a camera is using when generating images. |
| ID | The instance ID of this opened camera. |
| PermissionState | Whether camera access has been approved by the user. |
| Properties | The properties associated with the opened camera. |
Operators
| Name | Description |
|---|---|
| Equal(TSdlCamera, TSdlCamera) | Used to compare against another TSdlCamera. |
| Equal(TSdlCamera, Pointer) | Used to compare against nil. |
| Implicit | Used to set the value to nil. |
| NotEqual(TSdlCamera, TSdlCamera) | Used to compare against another TSdlCamera. |
| NotEqual(TSdlCamera, Pointer) | Used to compare against nil. |
Methods
| Name | Description |
|---|---|
| AcquireFrame | Acquire a frame. |
| Close | Shut down camera processing and close the camera device. |
| Open(TSdlCameraID, TSdlCameraSpec) | Open a video recording device (a "camera"). |
| Open(TSdlCameraID) | Open a video recording device (a "camera") using its preferred format. |
| ReleaseFrame | Release a frame of video acquired from the camera. |
Property Descriptions
Format
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.
If the system is waiting for the user to approve access to the camera, as some platforms require, this will raise an error, but this isn't necessarily a fatal error; you should either wait for an TSdlEventKind.CameraDeviceApproved (or TSdlEventKind.CameraDeviceDenied) event, or poll PermissionState occasionally.
property Format: TSdlCameraSpec read GetFormat
Type: TSdlCameraSpec
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
It is safe to use this property from any thread
ID
The instance ID of this opened camera.
property ID: TSdlCameraID read GetID
Type: TSdlCameraID
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
It is safe to use this property from any thread
PermissionState
Whether 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 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.
This property can be used to check the status of that approval. It will return Waiting if still waiting for user response, Approved if the camera is approved for use, and Denied if the user denied access.
Instead of polling with this property, you can wait for a TSdlEventKind.CameraDeviceApproved (or TSdlEventKind.CameraDeviceDenied) event in the standard SDL event loop, which is guaranteed to be sent once when permission to use the camera is decided.
If a camera is declined, there's nothing to be done but call Close to dispose of it.
property PermissionState: TSdlCameraPermissionState read GetPermissionState
Type: TSdlCameraPermissionState
See Also
Remarks
It is safe to use this property from any thread
Properties
The properties associated with the opened camera.
property Properties: TSdlProperties read GetProperties
Type: TSdlProperties
Exceptions
ESdlError: Raised on failure.
Remarks
It is safe to use this property from any thread
Operator Descriptions
Equal(TSdlCamera, TSdlCamera)
Used to compare against another TSdlCamera.
class operator Equal(const ALeft, ARight: TSdlCamera): Boolean; inline; static
Parameters
ALeft: TSdlCamera
ARight: TSdlCamera
Returns
Boolean
Equal(TSdlCamera, Pointer)
Used to compare against nil.
class operator Equal(const ALeft: TSdlCamera; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlCamera
ARight: Pointer
Returns
Boolean
Implicit(Pointer)
Used to set the value to nil.
class operator Implicit(const AValue: Pointer): TSdlCamera; inline; static
Parameters
AValue: Pointer
Returns
NotEqual(TSdlCamera, TSdlCamera)
Used to compare against another TSdlCamera.
class operator NotEqual(const ALeft, ARight: TSdlCamera): Boolean; inline; static
Parameters
ALeft: TSdlCamera
ARight: TSdlCamera
Returns
Boolean
NotEqual(TSdlCamera, Pointer)
Used to compare against nil.
class operator NotEqual(const ALeft: TSdlCamera; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlCamera
ARight: Pointer
Returns
Boolean
Method Descriptions
AcquireFrame(UInt64)
Acquire a frame.
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-nil surface is returned, and ATimestampNS will be filled with a non-zero value.
Note that an error case can also return nil, but a nil 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 Close is called, so real failure here is almost always an out of memory condition.
After use, the frame should be released with ReleaseFrame. If you don't do this, the system may stop providing more video!
Do not call Free on the returned surface! It must be given back to the camera subsystem with ReleaseFrame!
If the system is waiting for the user to approve access to the camera, as some platforms require, this will return nil (no frames available); you should either wait for an TSdlEventKind.CameraDeviceApproved (or TSdlEventKind.CameraDeviceDenied) event, or poll PermissionState occasionally.
function AcquireFrame(out ATimestampNS: UInt64): TSdlSurface; inline
Parameters
ATimestampNS: UInt64
: Is set to the frame's timestamp.
Returns
TSdlSurface: A new frame of video on success, nil if none is currently available.
See Also
Remarks
It is safe to call this method from any thread.
Close
Shut down camera processing and close the camera device.
procedure Close; inline
See Also
Remarks
It is safe to call this method from any thread, but no thread may reference the device once this method is called.
Open(TSdlCameraID, TSdlCameraSpec)
Open a video recording device (a "camera").
You can open the device with any reasonable spec, and if the hardware can't directly support it, it will convert data seamlessly to the requested format. This might incur overhead, including scaling of image data.
You can see the exact specs a device can support without conversion with TSdlCameraID.SupportedFormats.
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; use Format 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 TSdlEventKind.CameraDeviceApproved (or TSdlEventKind.CameraDeviceDenied) event, or poll PermissionState occasionally until it returns Approved or Denied. On platforms that don't require explicit user approval (and perhaps in places where the user previously permitted access), the approval event might come immediately, but it might come seconds, minutes, or hours later!
class function Open(const AInstanceID: TSdlCameraID; const ASpec: TSdlCameraSpec): TSdlCamera; overload; inline; static
Exceptions
ESdlError: Raised on failure.
Parameters
AInstanceID: TSdlCameraID
: The camera device instance ID.
ASpec: TSdlCameraSpec
: The desired format for data the device will provide.
Returns
TSdlCamera: The opened camera.
See Also
Remarks
It is safe to call this method from any thread.
Open(TSdlCameraID)
Open a video recording device (a "camera") using its preferred format.
This version will choose a format for you (and you can use TSdlSurface's conversion/scaling functions directly if necessary).
You can use Format to get the actual data format. You can see the exact specs a device can support without conversion with TSdlCameraID.SupportedFormats.
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; use Format 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 TSdlEventKind.CameraDeviceApproved (or TSdlEventKind.CameraDeviceDenied) event, or poll PermissionState occasionally until it returns Approved or Denied. On platforms that don't require explicit user approval (and perhaps in places where the user previously permitted access), the approval event might come immediately, but it might come seconds, minutes, or hours later!
class function Open(const AInstanceID: TSdlCameraID): TSdlCamera; overload; inline; static
Exceptions
ESdlError: Raised on failure.
Parameters
AInstanceID: TSdlCameraID
: The camera device instance ID.
Returns
TSdlCamera: The opened camera.
See Also
Remarks
It is safe to call this method from any thread.
ReleaseFrame(TSdlSurface)
Release a frame of video acquired from the camera.
Let the back-end re-use the internal buffer for camera.
This method must be called only on surface objects returned by AcquireFrame. This method 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.
If the app needs to keep the surface for a significant time, they should make a copy of it and release the original.
The app should not use the surface again after calling this function; assume the surface is freed and the pointer is invalid.
procedure ReleaseFrame(const AFrame: TSdlSurface); inline
Parameters
AFrame: TSdlSurface
: The video frame surface to release.
See Also
Remarks
It is safe to call this method from any thread.