140 lines
8.1 KiB
Plaintext
140 lines
8.1 KiB
Plaintext
---
|
|
id: devices
|
|
title: Camera Devices
|
|
sidebar_label: Camera Devices
|
|
---
|
|
|
|
import useBaseUrl from '@docusaurus/useBaseUrl';
|
|
|
|
<div>
|
|
<svg xmlns="http://www.w3.org/2000/svg" width="283" height="535" style={{ float: 'right' }}>
|
|
<image href={useBaseUrl("img/demo.gif")} x="18" y="33" width="247" height="469" />
|
|
<image href={useBaseUrl("img/frame.png")} width="283" height="535" />
|
|
</svg>
|
|
</div>
|
|
|
|
### What are camera devices?
|
|
|
|
Camera devices are the physical (or "virtual") devices that can be used to record videos or capture photos.
|
|
|
|
* **Physical**: A physical camera device is a **camera lens on your phone**. Different physical camera devices have different specifications, such as different capture formats, field of views, frame rates, focal lengths, and more. Some phones have multiple physical camera devices.
|
|
|
|
> Examples: _"Backside Wide-Angle Camera"_, _"Frontside Wide-Angle Camera (FaceTime HD)"_, _"Ultra-Wide-Angle back camera"_.
|
|
|
|
* **Virtual**: A virtual camera device is a **combination of one or more physical camera devices**, and provides features such as _virtual-device-switchover_ while zooming or _combined photo delivery_ from all physical cameras to produce higher quality images.
|
|
|
|
> Examples: _"Triple-Camera"_, _"Dual-Wide-Angle Camera"_
|
|
|
|
### Get available camera devices
|
|
|
|
To get a list of all available camera devices, use [the `getAvailableCameraDevices` function](/docs/api/classes/Camera#getavailablecameradevices):
|
|
|
|
```ts
|
|
const devices = await Camera.getAvailableCameraDevices()
|
|
```
|
|
|
|
Each camera device provides properties describing the features of this device. For example, a camera device provides the `hasFlash` property which is `true` if the device supports activating the flash when taking photos or recording videos.
|
|
|
|
The most important properties are:
|
|
|
|
* `devices`: A list of physical device types this camera device consists of. For a **single physical camera device**, this property is always an array of one element. **For virtual multi-cameras** this property contains all the physical camera devices that are combined to create this virtual multi-camera device
|
|
* `position`: The position of the camera device relative to the phone (`front`, `back`)
|
|
* `hasFlash`: Whether this camera device supports using the flash to take photos or record videos
|
|
* `hasTorch`: Whether this camera device supports enabling/disabling the torch at any time ([`Camera.torch` prop](/docs/api/interfaces/CameraProps#torch))
|
|
* `isMultiCam`: Determines whether the camera device is a virtual multi-camera device which contains multiple combined physical camera devices.
|
|
* `minZoom`: The minimum available zoom factor. This value is often `1`. When you pass `zoom={0}` to the Camera, the `minZoom` factor will be applied.
|
|
* `neutralZoom`: The zoom factor where the camera is "neutral". For any wide-angle cameras this property might be the same as `minZoom`, where as for ultra-wide-angle cameras ("fish-eye") this might be a value higher than `minZoom` (e.g. `2`). It is recommended that you always start at `neutralZoom` and let the user manually zoom out to `minZoom` on demand.
|
|
* `maxZoom`: The maximum available zoom factor. When you pass `zoom={1}` to the Camera, the `maxZoom` factor will be applied.
|
|
* `formats`: A list of all available formats (See [Camera Formats](formats))
|
|
* `supportsParallelVideoProcessing`: Determines whether this camera devices supports using Video Recordings and Frame Processors at the same time. (See [`supportsParallelVideoProcessing`](#the-supportsparallelvideoprocessing-prop))
|
|
* `supportsFocus`: Determines whether this camera device supports focusing (See [Focusing](focusing))
|
|
|
|
:::note
|
|
See the [`CameraDevice` type](/docs/api/interfaces/CameraDevice) for full API reference
|
|
:::
|
|
|
|
For debugging purposes you can use the `id` or `name` properties to log and compare devices. You can also use the `devices` properties to determine the physical camera devices this camera device consists of, for example:
|
|
|
|
* For a single Wide-Angle camera, this would be `["wide-angle-camera"]`
|
|
* For a Triple-Camera, this would be `["wide-angle-camera", "ultra-wide-angle-camera", "telephoto-camera"]`
|
|
|
|
You can use the helper function `parsePhysicalDeviceTypes` to convert a list of physical devices to a single device descriptor type which can also describe virtual devices:
|
|
|
|
```ts
|
|
console.log(device.devices)
|
|
// --> ["wide-angle-camera", "ultra-wide-angle-camera", "telephoto-camera"]
|
|
|
|
const deviceType = parsePhysicalDeviceTypes(device.devices)
|
|
console.log(deviceType)
|
|
// --> "triple-camera"
|
|
```
|
|
|
|
Always choose a camera device that is best fitted for your use-case; so you might filter out any cameras that do not support flash, have low zoom values, are not on the back side of the phone, do not contain a format with high resolution or fps, and more.
|
|
|
|
:::caution
|
|
Make sure to be careful when filtering out unneeded camera devices, since not every phone supports all camera device types. Some phones don't even have front-cameras. You always want to have a camera device, even when it's not the one that has the best features.
|
|
:::
|
|
|
|
### The `useCameraDevices` hook
|
|
|
|
VisionCamera provides a hook to make camera device selection a lot easier. You can specify a device type to only find devices with the given type:
|
|
|
|
```tsx
|
|
function App() {
|
|
const devices = useCameraDevices('wide-angle-camera')
|
|
const device = devices.back
|
|
|
|
if (device == null) return <LoadingView />
|
|
return (
|
|
<Camera
|
|
style={StyleSheet.absoluteFill}
|
|
device={device}
|
|
/>
|
|
)
|
|
}
|
|
```
|
|
|
|
Or just return the "best matching camera device". This function prefers camera devices with more physical cameras, and always ranks "wide-angle" physical camera devices first.
|
|
|
|
> Example: `triple-camera` > `dual-wide-camera` > `dual-camera` > `wide-angle-camera` > `ultra-wide-angle-camera` > `telephoto-camera` > ...
|
|
|
|
```tsx
|
|
function App() {
|
|
const devices = useCameraDevices()
|
|
const device = devices.back
|
|
|
|
if (device == null) return <LoadingView />
|
|
return (
|
|
<Camera
|
|
style={StyleSheet.absoluteFill}
|
|
device={device}
|
|
/>
|
|
)
|
|
}
|
|
```
|
|
|
|
### The `supportsParallelVideoProcessing` prop
|
|
|
|
Camera devices provide the [`supportsParallelVideoProcessing` property](/docs/api/interfaces/CameraDevice#supportsparallelvideoprocessing) which determines whether the device supports using Video Recordings (`video={true}`) and Frame Processors (`frameProcessor={...}`) at the same time.
|
|
|
|
If this property is `false`, you can either enable `video`, or add a `frameProcessor`, but not both.
|
|
|
|
* On iOS this value is always `true`.
|
|
* On newer Android devices this value is always `true`.
|
|
* On older Android devices this value is `false` if the Camera's hardware level is `LEGACY` or `LIMITED`, `true` otherwise. (See [`INFO_SUPPORTED_HARDWARE_LEVEL`](https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL) or [the tables at "Regular capture"](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#regular-capture))
|
|
|
|
#### Examples
|
|
|
|
* An app that only supports **taking photos** (e.g. a vintage Polaroid Camera app) works on every Camera device because the `supportsParallelVideoProcessing` only affects _video processing_.
|
|
* An app that supports **taking photos** and **videos** (e.g. a Camera app) works on every Camera device because only a single _video processing_ feature is used (`video`).
|
|
* An app that only uses **Frame Processors** (e.g. the "Hotdog/Not Hotdog detector" app) (no taking photos or videos) works on every Camera device because it only uses a single _video processing_ feature (`frameProcessor`).
|
|
* An app that uses **Frame Processors** and supports **taking photos** and **videos** (e.g. Snapchat, Instagram) only works on Camera devices where `supportsParallelVideoProcessing` is `true`. (iPhones and newer Android Phones)
|
|
|
|
:::note
|
|
Actually the limitation also affects the `photo` feature, but VisionCamera will automatically fall-back to **Snapshot capture** if you are trying to use multiple features (`photo` + `video` + `frameProcessor`) and they are not natively supported. (See ["Taking Snapshots"](/docs/guides/capturing#taking-snapshots))
|
|
:::
|
|
|
|
<br />
|
|
|
|
#### 🚀 Next section: [Camera Lifecycle](lifecycle)
|