railbird/react-native-vision-camera
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Use @linkcode for typedocs

Browse Source
This commit is contained in:
Marc Rousavy 2021-03-08 18:51:53 +01:00
parent b93bb2a68b
commit bfba6a95ee
8 changed files with 73 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
src/Camera.tsx
View File

@ -73,7 +73,24 @@ export type CameraScannerProps = Modify<
export interface CameraDeviceProps { export interface CameraDeviceProps {
// Properties // Properties
/** /**
* The Camera Device to use * The Camera Device to use.
*
* See the [Camera Devices](https://cuvent.github.io/react-native-vision-camera/docs/devices) section in the documentation for more information about Camera Devices.
*
* @example
* ```js
* const devices = useCameraDevices('wide-angle-camera')
* const device = devices.back
*
* return (
* <Camera
* device={device}
* isActive={true}
* style={StyleSheet.absoluteFill}
* />
* )
*
* ```
*/ */
device: CameraDevice; device: CameraDevice;
/** /**
@ -101,7 +118,7 @@ export interface CameraDeviceProps {
export interface CameraDynamicProps { export interface CameraDynamicProps {
/** /**
* Whether the Camera should actively stream video frames, or not. * Whether the Camera should actively stream video frames, or not. See the [documentation about the `isActive` prop](https://cuvent.github.io/react-native-vision-camera/docs/devices#the-isactive-prop) for more information.
* *
* This can be compared to a Video component, where `isActive` specifies whether the video is paused or not. * This can be compared to a Video component, where `isActive` specifies whether the video is paused or not.
* *
@ -125,7 +142,9 @@ export interface CameraDynamicProps {
*/ */
zoom?: number; zoom?: number;
/** /**
* Enables or disables the native pinch to zoom gesture * Enables or disables the native pinch to zoom gesture.
*
* If you want to implement a custom zoom gesture, see [the Zooming with Reanimated documentation](https://cuvent.github.io/react-native-vision-camera/docs/animated).
* *
* @default false * @default false
*/ */
@ -181,10 +200,12 @@ type RefType = React.Component<CameraProps> & Readonly<NativeMethods>;
/** /**
* ### A powerful `<Camera>` component. * ### A powerful `<Camera>` component.
* *
* Read the [VisionCamera documentation](https://cuvent.github.io/react-native-vision-camera/) for more information.
*
* The `<Camera>` component's most important (and therefore _required_) properties are: * The `<Camera>` component's most important (and therefore _required_) properties are:
* *
* * {@link CameraDeviceProps.device}: Specifies the {@link CameraDevice} to use. Get a {@link CameraDevice} by using the {@link useCameraDevices} hook, or manually by using the {@link Camera.getAvailableCameraDevices} function. * * {@linkcode CameraDeviceProps.device | device}: Specifies the {@linkcode CameraDevice} to use. Get a {@linkcode CameraDevice} by using the {@linkcode useCameraDevices | useCameraDevices()} hook, or manually by using the {@linkcode Camera.getAvailableCameraDevices Camera.getAvailableCameraDevices()} function.
* * {@link CameraDynamicProps.isActive}: A boolean value that specifies whether the Camera should actively stream video frames or not. This can be compared to a Video component, where `isActive` specifies whether the video is paused or not. If you fully unmount the `<Camera>` component instead of using `isActive={false}`, the Camera will take a bit longer to start again. * * {@linkcode CameraDynamicProps.isActive | isActive}: A boolean value that specifies whether the Camera should actively stream video frames or not. This can be compared to a Video component, where `isActive` specifies whether the video is paused or not. If you fully unmount the `<Camera>` component instead of using `isActive={false}`, the Camera will take a bit longer to start again.
* *
* @example * @example
* ```jsx * ```jsx
@ -240,7 +261,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
/** /**
* Take a single photo and write it's content to a temporary file. * Take a single photo and write it's content to a temporary file.
* *
* @throws {@link CameraCaptureError} When any kind of error occured. Use the {@link CameraCaptureError.code} property to get the actual error * @throws {@linkcode CameraCaptureError} When any kind of error occured while capturing the photo. Use the {@linkcode CameraCaptureError.code | code} property to get the actual error
* @example * @example
* ```js * ```js
* const photo = await camera.current.takePhoto({ * const photo = await camera.current.takePhoto({
@ -261,7 +282,9 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
/** /**
* Take a snapshot of the current preview view. * Take a snapshot of the current preview view.
* *
* This can be used as an alternative to {@link Camera.takePhoto} if speed is more important than quality * This can be used as an alternative to {@linkcode Camera.takePhoto | takePhoto()} if speed is more important than quality
*
* @throws {@linkcode CameraCaptureError} When any kind of error occured while taking a snapshot. Use the {@linkcode CameraCaptureError.code | code} property to get the actual error
* *
* @platform Android * @platform Android
* @example * @example
@ -292,7 +315,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* *
* @blocking This function is synchronized/blocking. * @blocking This function is synchronized/blocking.
* *
* @throws {@link CameraCaptureError} When any kind of error occured. Use the {@link CameraCaptureError.code} property to get the actual error * @throws {@linkcode CameraCaptureError} When any kind of error occured while starting the video recording. Use the {@linkcode CameraCaptureError.code | code} property to get the actual error
* *
* @example * @example
* ```js * ```js
@ -324,7 +347,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
/** /**
* Stop the current video recording. * Stop the current video recording.
* *
* @throws {@link CameraCaptureError} When any kind of error occured. Use the {@link CameraCaptureError.code} property to get the actual error * @throws {@linkcode CameraCaptureError} When any kind of error occured while stopping the video recording. Use the {@linkcode CameraCaptureError.code | code} property to get the actual error
* *
* @example * @example
* ```js * ```js
@ -351,7 +374,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* *
* Make sure the value doesn't exceed the CameraView's dimensions. * Make sure the value doesn't exceed the CameraView's dimensions.
* *
* @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error * @throws {@linkcode CameraRuntimeError} When any kind of error occured while focussing. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error
* @example * @example
* ```js * ```js
* await camera.current.focus({ * await camera.current.focus({
@ -372,9 +395,10 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* Get a list of video codecs the current camera supports. Returned values are ordered by efficiency (descending). * Get a list of video codecs the current camera supports. Returned values are ordered by efficiency (descending).
* *
* This function can only be called after the camera has been initialized, * This function can only be called after the camera has been initialized,
* so only use this after the {@link onInitialized} event has fired. * so only use this after the {@linkcode onInitialized | onInitialized()} event has fired.
* *
* @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error * @platform iOS
* @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting available video codecs. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error
*/ */
public async getAvailableVideoCodecs(): Promise<CameraVideoCodec[]> { public async getAvailableVideoCodecs(): Promise<CameraVideoCodec[]> {
try { try {
@ -387,9 +411,10 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* Get a list of photo codecs the current camera supports. Returned values are ordered by efficiency (descending). * Get a list of photo codecs the current camera supports. Returned values are ordered by efficiency (descending).
* *
* This function can only be called after the camera has been initialized, * This function can only be called after the camera has been initialized,
* so only use this after the {@link onInitialized} event has fired. * so only use this after the {@linkcode onInitialized | onInitialized()} event has fired.
* *
* @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error * @platform iOS
* @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting available photo codecs. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error
*/ */
public async getAvailablePhotoCodecs(): Promise<CameraPhotoCodec[]> { public async getAvailablePhotoCodecs(): Promise<CameraPhotoCodec[]> {
try { try {
@ -404,7 +429,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
/** /**
* Get a list of all available camera devices on the current phone. * Get a list of all available camera devices on the current phone.
* *
* @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error * @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting all available camera devices. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error
* @example * @example
* ```js * ```js
* const devices = await Camera.getAvailableCameraDevices() * const devices = await Camera.getAvailableCameraDevices()
@ -427,9 +452,9 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* Gets the current Camera Permission Status. Check this before mounting the Camera to ensure * Gets the current Camera Permission Status. Check this before mounting the Camera to ensure
* the user has permitted the app to use the camera. * the user has permitted the app to use the camera.
* *
* To actually prompt the user for camera permission, use {@link Camera.requestCameraPermission}. * To actually prompt the user for camera permission, use {@linkcode Camera.requestCameraPermission | requestCameraPermission()}.
* *
* @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error * @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting the current permission status. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error
*/ */
public static async getCameraPermissionStatus(): Promise<CameraPermissionStatus> { public static async getCameraPermissionStatus(): Promise<CameraPermissionStatus> {
try { try {
@ -442,9 +467,9 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* Gets the current Microphone-Recording Permission Status. Check this before mounting the Camera to ensure * Gets the current Microphone-Recording Permission Status. Check this before mounting the Camera to ensure
* the user has permitted the app to use the microphone. * the user has permitted the app to use the microphone.
* *
* To actually prompt the user for microphone permission, use {@link Camera.requestMicrophonePermission}. * To actually prompt the user for microphone permission, use {@linkcode Camera.requestMicrophonePermission | requestMicrophonePermission()}.
* *
* @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error * @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting the current permission status. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error
*/ */
public static async getMicrophonePermissionStatus(): Promise<CameraPermissionStatus> { public static async getMicrophonePermissionStatus(): Promise<CameraPermissionStatus> {
try { try {
@ -459,7 +484,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* If the user has previously blocked the app from using the camera, the alert will not be shown * If the user has previously blocked the app from using the camera, the alert will not be shown
* and `"denied"` will be returned. * and `"denied"` will be returned.
* *
* @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error * @throws {@linkcode CameraRuntimeError} When any kind of error occured while requesting permission. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error
*/ */
public static async requestCameraPermission(): Promise<CameraPermissionRequestResult> { public static async requestCameraPermission(): Promise<CameraPermissionRequestResult> {
try { try {
@ -474,7 +499,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* If the user has previously blocked the app from using the microphone, the alert will not be shown * If the user has previously blocked the app from using the microphone, the alert will not be shown
* and `"denied"` will be returned. * and `"denied"` will be returned.
* *
* @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error * @throws {@linkcode CameraRuntimeError} When any kind of error occured while requesting permission. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error
*/ */
public static async requestMicrophonePermission(): Promise<CameraPermissionRequestResult> { public static async requestMicrophonePermission(): Promise<CameraPermissionRequestResult> {
try { try {

10
src/CameraDevice.ts
View File

@ -20,7 +20,7 @@ export type PhysicalCameraDeviceType = 'ultra-wide-angle-camera' | 'wide-angle-c
export type LogicalCameraDeviceType = 'dual-camera' | 'dual-wide-camera' | 'triple-camera' | 'true-depth-camera'; export type LogicalCameraDeviceType = 'dual-camera' | 'dual-wide-camera' | 'triple-camera' | 'true-depth-camera';
/** /**
* Parses an array of physical device types into a single {@link PhysicalCameraDeviceType} or {@link LogicalCameraDeviceType}, depending what matches. * Parses an array of physical device types into a single {@linkcode PhysicalCameraDeviceType} or {@linkcode LogicalCameraDeviceType}, depending what matches.
* @method * @method
*/ */
export const parsePhysicalDeviceTypes = (physicalDeviceTypes: PhysicalCameraDeviceType[]): PhysicalCameraDeviceType | LogicalCameraDeviceType => { export const parsePhysicalDeviceTypes = (physicalDeviceTypes: PhysicalCameraDeviceType[]): PhysicalCameraDeviceType | LogicalCameraDeviceType => {
@ -80,7 +80,7 @@ export interface FrameRateRange {
} }
/** /**
* A Camera Device's video format. Do not create instances of this type yourself, only use {@link Camera.getAvailableCameraDevices}. * A Camera Device's video format. Do not create instances of this type yourself, only use {@linkcode Camera.getAvailableCameraDevices | Camera.getAvailableCameraDevices()}.
*/ */
export interface CameraDeviceFormat { export interface CameraDeviceFormat {
/** /**
@ -154,7 +154,7 @@ export interface CameraDeviceFormat {
} }
/** /**
* Represents a camera device discovered by the {@link Camera.getAvailableCameraDevices} function * Represents a camera device discovered by the {@linkcode Camera.getAvailableCameraDevices | Camera.getAvailableCameraDevices()} function
*/ */
export interface CameraDevice { export interface CameraDevice {
/** /**
@ -212,7 +212,9 @@ export interface CameraDevice {
*/ */
neutralZoom: number; neutralZoom: number;
/** /**
* All available formats for this camera device. Use this to find the best format for your use case and set it to the Camera's `format` property. * All available formats for this camera device. Use this to find the best format for your use case and set it to the Camera's {@linkcode Camera.format} property.
*
* See [the Camera Formats documentation](https://cuvent.github.io/react-native-vision-camera/docs/formats) for more information about Camera Formats.
*/ */
formats: CameraDeviceFormat[]; formats: CameraDeviceFormat[];
/** /**

14
src/CameraError.ts
View File

@ -37,7 +37,7 @@ export type SystemError = 'system/no-camera-manager';
export type UnknownError = 'unknown/unknown'; export type UnknownError = 'unknown/unknown';
/** /**
* Represents a JSON-style error cause. This contains native `NSError`/`Throwable` information, and can have recursive {@link ErrorWithCause.cause} properties until the ultimate cause has been found. * Represents a JSON-style error cause. This contains native `NSError`/`Throwable` information, and can have recursive {@linkcode ErrorWithCause.cause | .cause} properties until the ultimate cause has been found.
*/ */
export interface ErrorWithCause { export interface ErrorWithCause {
/** /**
@ -87,7 +87,7 @@ export interface ErrorWithCause {
type CameraErrorCode = PermissionError | ParameterError | DeviceError | FormatError | SessionError | CaptureError | SystemError | UnknownError; type CameraErrorCode = PermissionError | ParameterError | DeviceError | FormatError | SessionError | CaptureError | SystemError | UnknownError;
/** /**
* Represents any kind of error that occured in the {@link Camera} View Module. * Represents any kind of error that occured in the {@linkcode Camera} View Module.
*/ */
class CameraError<TCode extends CameraErrorCode> extends Error { class CameraError<TCode extends CameraErrorCode> extends Error {
private readonly _code: TCode; private readonly _code: TCode;
@ -117,20 +117,24 @@ class CameraError<TCode extends CameraErrorCode> extends Error {
/** /**
* Represents any kind of error that occured while trying to capture a video or photo. * Represents any kind of error that occured while trying to capture a video or photo.
*
* See the ["Camera Errors" documentation](https://cuvent.github.io/react-native-vision-camera/docs/errors) for more information about Camera Errors.
*/ */
export class CameraCaptureError extends CameraError<CaptureError> {} export class CameraCaptureError extends CameraError<CaptureError> {}
/** /**
* Represents any kind of error that occured in the Camera View Module. * Represents any kind of error that occured in the Camera View Module.
*
* See the ["Camera Errors" documentation](https://cuvent.github.io/react-native-vision-camera/docs/errors) for more information about Camera Errors.
*/ */
export class CameraRuntimeError extends CameraError< export class CameraRuntimeError extends CameraError<
PermissionError | ParameterError | DeviceError | FormatError | SessionError | SystemError | UnknownError PermissionError | ParameterError | DeviceError | FormatError | SessionError | SystemError | UnknownError
> {} > {}
/** /**
* Checks if the given `error` is of type {@link ErrorWithCause} * Checks if the given `error` is of type {@linkcode ErrorWithCause}
* @param {unknown} error Any unknown object to validate * @param {unknown} error Any unknown object to validate
* @returns `true` if the given `error` is of type {@link ErrorWithCause} * @returns `true` if the given `error` is of type {@linkcode ErrorWithCause}
*/ */
export const isErrorWithCause = (error: unknown): error is ErrorWithCause => export const isErrorWithCause = (error: unknown): error is ErrorWithCause =>
typeof error === 'object' && typeof error === 'object' &&
@ -155,7 +159,7 @@ const isCameraErrorJson = (error: unknown): error is { code: string; message: st
/** /**
* Tries to parse an error coming from native to a typed JS camera error. * Tries to parse an error coming from native to a typed JS camera error.
* @param {CameraError} nativeError The native error instance. This is a JSON in the legacy native module architecture. * @param {CameraError} nativeError The native error instance. This is a JSON in the legacy native module architecture.
* @returns A {@link CameraRuntimeError} or {@link CameraCaptureError}, or the `nativeError` itself if it's not parsable * @returns A {@linkcode CameraRuntimeError} or {@linkcode CameraCaptureError}, or the `nativeError` itself if it's not parsable
* @method * @method
*/ */
export const tryParseNativeCameraError = <T>(nativeError: T): (CameraRuntimeError | CameraCaptureError) | T => { export const tryParseNativeCameraError = <T>(nativeError: T): (CameraRuntimeError | CameraCaptureError) | T => {

6
src/PhotoFile.ts
View File

@ -3,7 +3,7 @@ import type { TemporaryFile } from './TemporaryFile';
export interface TakePhotoOptions { export interface TakePhotoOptions {
/** /**
* Specify the photo codec to use. To get a list of available photo codecs use the {@link Camera.getAvailablePhotoCodecs} function. * Specify the photo codec to use. To get a list of available photo codecs use the {@linkcode Camera.getAvailablePhotoCodecs | getAvailablePhotoCodecs()} function.
* *
* @platform iOS * @platform iOS
* @default undefined * @default undefined
@ -52,7 +52,7 @@ export interface TakePhotoOptions {
*/ */
enableAutoDistortionCorrection?: boolean; enableAutoDistortionCorrection?: boolean;
/** /**
* When set to `true`, metadata reading and mapping will be skipped. ({@link PhotoFile.metadata} will be null) * When set to `true`, metadata reading and mapping will be skipped. ({@linkcode PhotoFile.metadata} will be null)
* *
* This might result in a faster capture, as metadata reading and mapping requires File IO. * This might result in a faster capture, as metadata reading and mapping requires File IO.
* *
@ -66,7 +66,7 @@ export interface TakePhotoOptions {
/** /**
* Represents a Photo taken by the Camera written to the local filesystem. * Represents a Photo taken by the Camera written to the local filesystem.
* *
* Related: {@link Camera.takePhoto}, {@link Camera.takeSnapshot} * Related: {@linkcode Camera.takePhoto | Camera.takePhoto()}, {@linkcode Camera.takeSnapshot | Camera.takeSnapshot()}
*/ */
export interface PhotoFile extends TemporaryFile { export interface PhotoFile extends TemporaryFile {
width: number; width: number;

2
src/Snapshot.ts
View File

@ -9,7 +9,7 @@ export interface TakeSnapshotOptions {
quality?: number; quality?: number;
/** /**
* When set to `true`, metadata reading and mapping will be skipped. ({@link PhotoFile.metadata} will be `null`) * When set to `true`, metadata reading and mapping will be skipped. ({@linkcode PhotoFile.metadata} will be `null`)
* *
* This might result in a faster capture, as metadata reading and mapping requires File IO. * This might result in a faster capture, as metadata reading and mapping requires File IO.
* *

2
src/VideoFile.ts
View File

@ -47,7 +47,7 @@ export interface RecordVideoOptions {
/** /**
* Represents a Video taken by the Camera written to the local filesystem. * Represents a Video taken by the Camera written to the local filesystem.
* *
* Related: {@link Camera.startRecording}, {@link Camera.stopRecording} * Related: {@linkcode Camera.startRecording | Camera.startRecording()}, {@linkcode Camera.stopRecording | Camera.stopRecording()}
*/ */
export interface VideoFile extends TemporaryFile { export interface VideoFile extends TemporaryFile {
/** /**

12
src/hooks/useCameraDevices.ts
View File

@ -15,10 +15,10 @@ const DefaultCameraDevices: CameraDevices = {
}; };
/** /**
* Gets the best available `CameraDevice`. Devices with more cameras are preferred. * Gets the best available {@linkcode CameraDevice}. Devices with more cameras are preferred.
* *
* @returns The best matching `CameraDevice`. * @returns The best matching {@linkcode CameraDevice}.
* @throws {@link CameraRuntimeError} if no device was found. * @throws {@linkcode CameraRuntimeError} if no device was found.
* @example * @example
* ```jsx * ```jsx
* const device = useCameraDevice() * const device = useCameraDevice()
@ -29,11 +29,11 @@ const DefaultCameraDevices: CameraDevices = {
export function useCameraDevices(): CameraDevices; export function useCameraDevices(): CameraDevices;
/** /**
* Gets a `CameraDevice` for the requested device type. * Gets a {@linkcode CameraDevice} for the requested device type.
* *
* @param {PhysicalCameraDeviceType | LogicalCameraDeviceType} deviceType Specifies a device type which will be used as a device filter. * @param {PhysicalCameraDeviceType | LogicalCameraDeviceType} deviceType Specifies a device type which will be used as a device filter.
* @returns A `CameraDevice` for the requested device type. * @returns A {@linkcode CameraDevice} for the requested device type.
* @throws {@link CameraRuntimeError} if no device was found. * @throws {@linkcode CameraRuntimeError} if no device was found.
* @example * @example
* ```jsx * ```jsx
* const device = useCameraDevice('wide-angle-camera') * const device = useCameraDevice('wide-angle-camera')

2
src/utils/FormatFilter.ts
View File

@ -79,7 +79,7 @@ const getFormatAspectRatioOverflow = (format: CameraDeviceFormat, size: Size): n
/** /**
* Filters Camera Device Formats by the best matching aspect ratio for the given `viewSize`. * Filters Camera Device Formats by the best matching aspect ratio for the given `viewSize`.
* *
* @param {CameraDeviceFormat[]} formats A list of formats the current device has (see {@link CameraDevice.formats}) * @param {CameraDeviceFormat[]} formats A list of formats the current device has (see {@linkcode CameraDevice.formats})
* @param {Size} viewSize The size of the camera view which will be used to find the best aspect ratio. Defaults to the screen size. * @param {Size} viewSize The size of the camera view which will be used to find the best aspect ratio. Defaults to the screen size.
* @returns A list of Camera Device Formats that match the given `viewSize`' aspect ratio _as close as possible_. * @returns A list of Camera Device Formats that match the given `viewSize`' aspect ratio _as close as possible_.
* *