CameraDevice
namespace VideoKit {
/// <summary>
/// Camera device for streaming pixel buffers.
/// </summary>
class CameraDevice { ... }
}
The CameraDevice
abstracts a hardware camera device capable of streaming pixel buffers.
Discovering Camera Devices
Before using camera devices, you must first request necessary permissions then discover all available devices.
Checking for Permissions
/// <summary>
/// Check the current camera permission status.
/// </summary>
/// <param name="request">Request permissions if the user has not yet been asked.</param>
/// <returns>Camera permission status.</returns>
static Task<PermissionStatus> CheckPermissions (bool request = true);
Because camera input captures sensitive user data, permissions must explicitly be requested from the user. This method will show the native permission dialog to the user, and return the user's response:
/// <summary>
/// Device permissions status.
/// </summary>
enum PermissionStatus : int {
/// <summary>
/// User has not authorized or denied access to media device.
/// </summary>
Unknown = 0,
/// <summary>
/// User has denied access to media device.
/// </summary>
Denied = 2,
/// <summary>
/// User has authorized access to media device.
/// </summary>
Authorized = 3
}
Discovering Camera Devices
/// <summary>
/// Discover available camera devices.
/// </summary>
static Task<CameraDevice[]> Discover ();
Once camera permissions are granted, available camera devices can be discovered.
Identifying the Device
Camera devices can be identified in several ways:
Inspecting the Unique Identifier
/// <summary>
/// Camera unique ID.
/// </summary>
string uniqueId { get; }
The camera device reports its unique identifier as a string.
Inspecting the Camera Name
/// <summary>
/// Display friendly camera name.
/// </summary>
string name { get; }
The camera device reports its name as a human-friendly string.
Inspecting the Device Location
/// <summary>
/// Device location.
/// </summary>
Location location { get; }
Some camera devices are able to report their location relative to the current device.
See MediaDevice.Location
for more information.
Checking for the Default Device
/// <summary>
/// Whether this camera is the default camera device.
/// </summary>
bool defaultForMediaType { get; }
Some camera devices are able to report whether they are the default device for their media type.
Inspecting the Camera Facing
/// <summary>
/// Whether the camera is front facing.
/// </summary>
bool frontFacing { get; }
The camera device reports whether it is front-facing or not.
Inspecting the Field of View
/// <summary>
/// Field of view in degrees.
/// </summary>
(float width, float height) fieldOfView { get; }
The camera device reports its horizontal and vertical fields of view in degrees.
Checking Depth Streaming Support
/// <summary>
/// Whether depth streaming is supported.
/// </summary>
bool depthStreamingSupported { get; }
The camera device reports whether it supports depth streaming.
Currently, depth streaming is not supported. Support is planned for a future release.
Configuring the Camera Preview
Camera devices support specifying the preferred preview capture format.
Specifying the Preview Resolution
/// <summary>
/// Get or set the preview resolution.
/// </summary>
(int width, int height) previewResolution { get; set; }
The camera device allows for configuring the preview resolution.
The preview resolution should only be set before starting the preview stream.
The preview resolution is always specified in landscape format, so the width
must always
be larger than the height
.
Specifying the Preview Frame Rate
/// <summary>
/// Get or set the preview framerate.
/// </summary>
float frameRate { get; set; }
The camera device allows for configuring the preview frame rate.
The preview frame rate should only be set before starting the preview stream.
Specifying the Exposure Mode
/// <summary>
/// Get or set the exposure mode.
/// If the requested exposure mode is not supported, the camera device will ignore.
/// </summary>
ExposureMode exposureMode { get; set; } = ExposureMode.Continuous;
The camera device allows for setting the exposure mode. Below are supported exposure modes:
/// <summary>
/// Exposure mode.
/// </summary>
enum ExposureMode : int {
/// <summary>
/// Continuous auto exposure.
/// </summary>
Continuous = 0,
/// <summary>
/// Locked auto exposure.
/// </summary>
Locked = 1,
/// <summary>
/// Manual exposure.
/// </summary>
Manual = 2
}
Before setting an exposure mode, you must check to ensure that the camera device supports it:
/// <summary>
/// Check if a given exposure mode is supported by the camera device.
/// </summary>
/// <param name="mode">Exposure mode.</param>
bool IsExposureModeSupported (ExposureMode mode);
Using Auto Exposure
Camera devices support fine-grained automatic exposure control:
Specifying the Exposure Point
/// <summary>
/// Set the exposure point of interest.
/// The point is specified in normalized coordinates in range [0.0, 1.0].
/// </summary>
/// <param name="x">Normalized x coordinate.</param>
/// <param name="y">Normalized y coordinate.</param>
void SetExposurePoint (float x, float y);
The camera device allows for setting an exposure point of interest in normalized coordinates. Before setting the exposure point, you must check to ensure that the camera device supports it:
/// <summary>
/// Whether setting the exposure point is supported.
/// </summary>
bool exposurePointSupported { get; }
Specifying the Exposure Bias
/// <summary>
/// Get or set the exposure bias.
/// This value must be in the range returned by `exposureRange`.
/// </summary>
float exposureBias { get; set; }
The camera device allows for setting the exposure bias value. You must ensure that the value you set is within the supported range:
/// <summary>
/// Exposure bias range in EV.
/// </summary>
(float min, float max) exposureBiasRange { get; }
Using Manual Exposure
Camera devices support fully manual exposure control:
Inspecting the Exposure Duration Range
/// <summary>
/// Exposure duration range in seconds.
/// </summary>
(float min, float max) exposureDurationRange { get; }
The camera device reports its exposure duration range.
Inspecting the Exposure Sensitivity Range
/// <summary>
/// Exposure sensitivity range.
/// </summary>
(float min, float max) ISORange { get; }
The camera device reports its exposure sensitivity range.
Inspecting the Exposure Duration
/// <summary>
/// Get the current exposure duration in seconds.
/// </summary>
float exposureDuration { get; }
The camera device reports the current exposure duration.
Inspecting the Exposure Sensitivity
/// <summary>
/// Get the current exposure sensitivity.
/// </summary>
float ISO { get; }
The camera device reports the current exposure sensitivity.
Setting Manual Exposure
/// <summary>
/// Set manual exposure.
/// </summary>
/// <param name="duration">Exposure duration in seconds. MUST be in `exposureDurationRange`.</param>
/// <param name="ISO">Sensor sensitivity ISO value. MUST be in `ISORange`.</param>
void SetExposureDuration (float duration, float ISO);
For camera devices that support ExposureMode.Manual
, the
exposure duration can be set for full control over exposure.
Specifying the Focus Mode
/// <summary>
/// Get or set the focus mode.
/// </summary>
FocusMode focusMode { get; set; }
The camera device allows for setting the focus mode. Below are supported focus modes:
/// <summary>
/// Focus mode.
/// </summary>
enum FocusMode : int {
/// <summary>
/// Continuous autofocus.
/// </summary>
Continuous = 0,
/// <summary>
/// Locked focus.
/// </summary>
Locked = 1,
}
Before setting a focus mode, you must check to ensure that the camera device supports it:
/// <summary>
/// Check if a given focus mode is supported by the camera device.
/// </summary>
/// <param name="mode">Focus mode.</param>
bool IsFocusModeSupported (FocusMode mode);
Specifying the Focus Point
/// <summary>
/// Set the focus point of interest.
/// The point is specified in normalized coordinates in range [0.0, 1.0].
/// </summary>
/// <param name="x">Normalized x coordinate.</param>
/// <param name="y">Normalized y coordinate.</param>
void SetFocusPoint (float x, float y);
The camera device allows for setting a focus point of interest in normalized coordinates. Before setting the focus point, you must check to ensure that the camera device supports it:
/// <summary>
/// Whether setting the focus point is supported.
/// </summary>
bool focusPointSupported { get; }
Specifying the Zoom Ratio
/// <summary>
/// Get or set the zoom ratio.
/// This value must be in the range returned by `zoomRange`.
/// </summary>
float zoomRatio { get; set; }
The camera device allows for setting the optical zoom ratio. When setting the zoom ratio, you must ensure that the value is in the supported range:
/// <summary>
/// Zoom ratio range.
/// </summary>
(float min, float max) zoomRange { get; }
Specifying the White Balance Mode
/// <summary>
/// Get or set the white balance mode.
/// </summary>
WhiteBalanceMode whiteBalanceMode { get; set; }
The camera device allows for setting the white balance mode. Below are supported white balance modes:
/// <summary>
/// White balance mode.
/// </summary>
enum WhiteBalanceMode : int {
/// <summary>
/// Continuous auto white balance.
/// </summary>
Continuous = 0,
/// <summary>
/// Locked auto white balance.
/// </summary>
Locked = 1,
}
Before setting a white balance mode, you must check to ensure that the camera device supports it:
/// <summary>
/// Check if a given white balance mode is supported by the camera device.
/// </summary>
/// <param name="mode">White balance mode.</param>
bool IsWhiteBalanceModeSupported (WhiteBalanceMode mode);
Specifying the Video Stabilization Mode
/// <summary>
/// Get or set the video stabilization mode.
/// </summary>
VideoStabilizationMode videoStabilizationMode { get; set; }
The camera device allows for setting the video stabilization mode. Below are supported video stabilization modes:
/// <summary>
/// Video stabilization mode.
/// </summary>
enum VideoStabilizationMode : int {
/// <summary>
/// Disabled video stabilization.
/// </summary>
Off = 0,
/// <summary>
/// Standard video stabilization.
/// </summary>
Standard = 1
}
Before setting a video stabilization mode, you must check to ensure that the camera device supports it:
/// <summary>
/// Check if a given video stabilization mode is supported by the camera device.
/// </summary>
/// <param name="mode">Video stabilization mode.</param>
bool IsVideoStabilizationModeSupported (VideoStabilizationMode mode);
Streaming Pixel Buffers
The main function of the camera device is to stream PixelBuffer
instances to consumers.
Checking the Streaming Status
/// <summary>
/// Whether the device is running.
/// </summary>
bool running { get; }
The camera device reports whether it is currently streaming pixel buffers.
Starting the Stream
/// <summary>
/// Start the camera preview.
/// </summary>
/// <param name="handler">Delegate to receive preview image frames.</param>
void StartRunning (Action<PixelBuffer> handler);
To start streaming, a handler
must be provided to receive PixelBuffer
instances from
the camera device.
The provided handler
is invoked on a dedicated camera thread, not the Unity main thread.
Stopping the Stream
/// <summary>
/// Stop running.
/// </summary>
void StopRunning ();
When the camera device is running, this method can be used to stop streaming pixel buffers and cleanup resources.
Capturing Photos
Camera devices support capturing high-resolution photos.
Specifying the Photo Resolution
/// <summary>
/// Get or set the photo resolution.
/// </summary>
(int width, int height) photoResolution { get; set; }
The camera device allows for configuring the photo resolution.
The photo resolution should only be set before starting the preview stream.
The photo resolution is always specified in landscape format, so the width
must always
be larger than the height
.
Specifying the Flash Mode
/// <summary>
/// Get or set the photo flash mode.
/// </summary>
FlashMode flashMode { get; set; }
The camera device allows for setting the flash mode for photo capture. Below are supported flash modes:
/// <summary>
/// Photo flash mode.
/// </summary>
enum FlashMode : int {
/// <summary>
/// Never use flash.
/// </summary>
Off = 0,
/// <summary>
/// Always use flash.
/// </summary>
On = 1,
/// <summary>
/// Let the sensor detect if it needs flash.
/// </summary>
Auto = 2
}
Before setting the flash mode, you must check to ensure that the camera device supports it:
/// <summary>
/// Whether flash is supported for photo capture.
/// </summary>
bool flashSupported { get; }
Capturing a Photo
/// <summary>
/// Capture a photo.
/// </summary>
/// <param name="handler">Delegate to receive high-resolution photo.</param>
void CapturePhoto (Action<PixelBuffer> handler);
Capture a photo and provide a handler
to receive the photo PixelBuffer
.
The provided handler
is invoked on a dedicated camera thread, not the Unity main thread.
Using the Torch Unit
/// <summary>
/// Get or set the torch mode.
/// </summary>
TorchMode torchMode { get; set; }
Some camera devices have torch units that can be independently enabled or disabled. Below are supported torch modes:
/// <summary>
/// Torch mode.
/// </summary>
enum TorchMode : int {
/// <summary>
/// Disabled torch.
/// </summary>
Off = 0,
/// <summary>
/// Maximum supported torch level.
/// </summary>
Maximum = 100
}
Before enabling the torch unit, you must check to ensure that the camera device supports it:
/// <summary>
/// Whether torch is supported.
/// </summary>
bool torchSupported { get; }