- Qt 6.12
- Qt Multimedia
- QML Types
- Camera
- Qt 6.12.0 Reference Documentation

# Camera QML Type

An interface for camera settings related to focus and zoom. More...

Import Statement: | `import QtMultimedia`
In C++: | QCamera

- List of all members, including inherited members

## Properties

- active : bool
- cameraDevice : cameraDevice
- cameraFormat : cameraFormat
- colorTemperature : int
- customFocusPoint : point
- error : enumeration
- errorString : string
- exposureCompensation : real
- exposureMode : enumeration
- exposureTime : real
- flashMode : enumeration
- flashReady : bool
- focusDistance : real
- focusMode : enumeration
- focusPoint : point
- isoSensitivity : int
- manualExposureTime : real
- manualIsoSensitivity : int
- maximumZoomFactor : real
- minimumZoomFactor : real
- supportedFeatures : enumeration
- torchMode : enumeration
- whiteBalanceMode : enumeration
- zoomFactor : real

## Signals

- void errorOccurred(Camera::Error error, string errorString)

## Methods

- bool isExposureModeSupported(ExposureMode mode)
- bool isFlashModeSupported(FlashMode mode)
- bool isFlashReady()
- bool isFocusModeSupported(FocusMode mode)
- bool isTorchModeSupported(TorchMode mode)
- bool isWhiteBalanceModeSupported(WhiteBalanceMode mode)
- void start()
- void stop()
- void zoomTo(factor, rate)

## Detailed Description

The Camera element can be used within a CaptureSession for video recording and image taking.

You can use MediaDevices to list available cameras and choose which one to use.

     MediaDevices {
         id: mediaDevices
     }
     CaptureSession {
         camera: Camera {
             cameraDevice: mediaDevices.defaultVideoInput
         }
     }

On hardware that supports it, Camera lets you adjust the focus and zoom. The minimumZoomFactor and maximumZoomFactor properties provide the range of supported zoom factors. The zoomFactor property allows changing the zoom factor.

     Camera {
         zoomFactor: maximumZoomFactor // zoom in as much as possible
     }

After capturing the raw data for a camera frame, the camera hardware and software performs various image processing tasks to produce the final image. This includes compensating for ambient light color, reducing noise, as well as making some other adjustments to the image.

You can control many of these processing steps through the Camera properties. For example, you can set the white balance (or color temperature) used for processing images:

     Camera {
         whiteBalanceMode: Camera.WhiteBalanceManual
         colorTemperature: 5600
     }

For more information on image processing of camera frames, see Camera Image Processing.

Most platforms require that the end-user grants permissions before a camera can be activated. It is therefore strongly recommended that application developers utilize the CameraPermission component when working with cameras. The following is a short example that requests permissions from the end-user when the application starts, and then activates the camera if permissions are granted.

     CameraPermission {
         id: cameraPermission
     }

     Camera {
         active: cameraPermission.status === Qt.PermissionStatus.Granted
     }

     Component.onCompleted: cameraPermission.request()

See the camera overview for more information.

## Property Documentation

### active : bool

Describes whether the camera is currently active.

### cameraDevice : cameraDevice

Gets or sets the currently active camera device.

When switching camera devices, the Camera's capabilities are updated. Additionally, the Camera's control properties (such as focusMode, flashMode, focusDistance, zoomFactor) are updated as follows:

- If a property is supported on the new device, the property value is applied to the camera device.
- If a property is supported but its range of valid values was changed, the property is clamped to the new range and applied to the camera device.
- If the new camera device does not support a property, the property value is reset to default, and no changes are made to the camera device.

### cameraFormat : cameraFormat

Gets or sets the currently active camera format.

Note: When using the FFMPEG backend on an Android target device if you request YUV420P format, you will receive either a fully planar 4:2:0 YUV420P or a semi-planar NV12/NV21. This depends on the codec implemented by the device OEM.

Note: On macOS, camera-devices are shared across multiple applications on the operating system. This means that another application may override the format set by this property. Application developers should account for receiving video frames that have a different resolution, pixel format and framerate than what is described by this property. This property does not change when the device's format is modified by another application. The format described by this property can be re-applied to the device by re-activating the Camera.

See also cameraDevice::videoFormats.

### colorTemperature : int

Gets or sets the current color temperature.

Setting a color temperature will only have an effect if WhiteBalanceManual is supported. In this case, setting a temperature greater 0 will automatically set the white balance mode to WhiteBalanceManual. Setting the temperature to 0 will reset the white balance mode to WhiteBalanceAuto.

### customFocusPoint : point

This property holds the position of custom focus point, in relative frame coordinates. This means that QPointF(0,0) points to the top-left corner of the frame, and QPointF(0.5,0.5) points to the center of the frame.

You can check whether custom focus points are supported by querying supportedFeatures() with the Feature.CustomFocusPoint flag.

### error : enumeration `[read-only]`

Returns the error state of the camera.

Constant | Description
--- | ---
`Camera.NoError` | No errors have occurred.
`Camera.CameraError` | An error has occurred.

### errorString : string `[read-only]`

Returns a human readable string describing a camera's error state.

### exposureCompensation : real

Gets or sets the exposure compensation in EV units.

Exposure compensation property allows to adjust the automatically calculated exposure.

### exposureMode : enumeration

The exposure mode being used.

Constant | Description
--- | ---
`Camera.ExposureAuto` | Automatic mode.
`Camera.ExposureManual` | Manual mode.
`Camera.ExposurePortrait` | Portrait exposure mode.
`Camera.ExposureNight` | Night mode.
`Camera.ExposureSports` | Spots exposure mode.
`Camera.ExposureSnow` | Snow exposure mode.
`Camera.ExposureBeach` | Beach exposure mode.
`Camera.ExposureAction` | Action mode. Since 5.5
`Camera.ExposureLandscape` | Landscape mode. Since 5.5
`Camera.ExposureNightPortrait` | Night portrait mode. Since 5.5
`Camera.ExposureTheatre` | Theatre mode. Since 5.5
`Camera.ExposureSunset` | Sunset mode. Since 5.5
`Camera.ExposureSteadyPhoto` | Steady photo mode. Since 5.5
`Camera.ExposureFireworks` | Fireworks mode. Since 5.5
`Camera.ExposureParty` | Party mode. Since 5.5
`Camera.ExposureCandlelight` | Candlelight mode. Since 5.5
`Camera.ExposureBarcode` | Barcode mode. Since 5.5

See also isExposureModeSupported().

### exposureTime : real `[read-only]`

Returns the Camera's exposure time in seconds.

See also manualExposureTime.

### flashMode : enumeration

Gets or sets a certain flash mode if the camera has a flash.

Assigning an unsupported mode to this property has no effect.

This property only has an effect when capturing images using ImageCapture

Constant | Description
--- | ---
`Camera.FlashOff` | Flash is Off.
`Camera.FlashOn` | Flash is On.
`Camera.FlashAuto` | Automatic flash.

See also isFlashModeSupported(), isFlashReady(), and flashReady.

### flashReady : bool `[read-only]`

Indicates if the flash is charged and ready to use.

### focusDistance : real

This property defines the lens focus distance when the camera device works in manual focus mode. Valid values range from 0 to 1, where 0 is the closest possible focus distance, and 1 is the farthest. The farthest point is typically at infinity, but this may not be the case for all devices.

This property is applied to the device only when focusMode is set to Camera.FocusModeManual, and supportedFeatures includes the `Camera.FocusDistance` flag.

If you assign a value to this property while focusMode is not set to `Camera.FocusModeManual`, the property stores the value but does not affect the device until `Camera.FocusModeManual` is active.

Assigning a value outside the valid range [0, 1] has no effect on this property.

If supportedFeatures does not include the `Camera.FocusDistance` flag, any attempt to set this property is ignored.

This property will not be updated by the camera when it is in an automatic focus mode.

The default value is 1.

### focusMode : enumeration

This property holds the value that controls focus mode for the camera device. In all autofocus modes, the camera device keeps focusing continuously.

Note: In automatic focusing modes and where supported, the focusPoint property provides information and control over the area of the image that is being focused.

Constant | Description
--- | ---
`Camera.FocusModeAuto` | Continuous auto focus mode.
`Camera.FocusModeAutoNear` | Continuous auto focus, preferring objects near to the camera.
`Camera.FocusModeAutoFar` | Continuous auto focus, preferring objects far away from the camera.
`Camera.FocusModeHyperfocal` | Focus to hyperfocal distance, with the maximum depth of field achieved. All objects at distances from half of this distance out to infinity will be acceptably sharp.
`Camera.FocusModeInfinity` | Focus strictly to infinity.
`Camera.FocusModeManual` | The lens focus distance is set to a value specified by focusDistance.

To check whether the camera device supports a particular focus mode, pass the corresponding `focusMode` value to the isFocusModeSupported() function as a parameter. The function returns `false` if the focus mode value is not supported. Assigning an unsupported mode to this property has no effect.

If you set the focusMode property to `Camera.FocusModeManual`, the lens locks to the focus according to focusDistance.

See also isFocusModeSupported().

### focusPoint : point `[read-only]`

Returns the point currently used by the auto focus system to focus onto.

### isoSensitivity : int `[read-only]`

Describes the ISO sensitivity currently used by the camera.

### manualExposureTime : real

Gets or sets a manual exposure time.

Setting this property to -1 (the default) means that the camera automatically determines the exposure time.

### manualIsoSensitivity : int

Describes a manually set ISO sensitivity

Setting this property to -1 (the default), implies that the camera automatically adjusts the ISO sensitivity.

### maximumZoomFactor : real `[read-only]`

This property holds the maximum zoom factor supported.

This will be `1.0` on cameras that do not support zooming.

### minimumZoomFactor : real `[read-only]`

This property holds the minimum zoom factor supported.

This will be `1.0` on cameras that do not support zooming.

### supportedFeatures : enumeration `[read-only]`

Returns the features supported by this camera. The value is bitmask that may contain any of the following flags. It stores an OR combination of Feature values.

Constant | Description
--- | ---
`Camera.ColorTemperature` | The Camera supports setting a custom colorTemperature.
`Camera.ExposureCompensation` | The Camera supports setting a custom exposureCompensation.
`Camera.IsoSensitivity` | The Camera supports setting a custom isoSensitivity.
`Camera.ManualExposureTime` | The Camera supports setting a manual exposure Time.
`Camera.CustomFocusPoint` | The Camera supports setting a custom focus point.
`Camera.FocusDistance` | The Camera supports setting the focusDistance property.

### torchMode : enumeration

Gets or sets the torch mode being used.

A torch is a continuous source of light. It can be used during video recording in low light conditions. Enabling torch mode will usually override any currently set flash mode.

Constant | Description
--- | ---
`Camera.TorchOff` | Torch is Off.
`Camera.TorchOn` | Torch is On.
`Camera.TorchAuto` | Automatic torch.

See also isTorchModeSupported() and flashMode.

### whiteBalanceMode : enumeration

Gets or sets the white balance mode being used.

Constant | Description
--- | ---
`Camera.WhiteBalanceAuto` | Auto white balance mode.
`Camera.WhiteBalanceManual` | Manual white balance. In this mode the white balance should be set with setColorTemperature()
`Camera.WhiteBalanceSunlight` | Sunlight white balance mode.
`Camera.WhiteBalanceCloudy` | Cloudy white balance mode.
`Camera.WhiteBalanceShade` | Shade white balance mode.
`Camera.WhiteBalanceTungsten` | Tungsten (incandescent) white balance mode.
`Camera.WhiteBalanceFluorescent` | Fluorescent white balance mode.
`Camera.WhiteBalanceFlash` | Flash white balance mode.
`Camera.WhiteBalanceSunset` | Sunset white balance mode.

See also isWhiteBalanceModeSupported().

### zoomFactor : real

Gets or sets the current zoom factor. Values will be clamped between minimumZoomFactor and maximumZoomFactor.

## Signal Documentation

### void errorOccurred(Camera::Error error, string errorString)

This signal is emitted when error state changes to error. A description of the error is provided as errorString.

Note: The corresponding handler is `onErrorOccurred`.

## Method Documentation

### bool isExposureModeSupported(ExposureMode mode)

Returns true if the exposure mode is supported.

### bool isFlashModeSupported(FlashMode mode)

Returns true if the flash mode is supported.

### bool isFlashReady()

Returns true if flash is charged.

### bool isFocusModeSupported(FocusMode mode)

Returns `true` if the focus mode is supported by the camera.

If Camera.FocusModeManual is reported as supported, the feature Camera.FocusDistance is implied to be supported as well.

### bool isTorchModeSupported(TorchMode mode)

Returns true if the torch mode is supported.

### bool isWhiteBalanceModeSupported(WhiteBalanceMode mode)

Returns true if the white balance mode is supported.

### void start()

Starts the camera.

Same as setting the active property to true.

If the camera can't be started for some reason, the errorOccurred() signal is emitted.

### void stop()

Stops the camera. Same as setting the active property to false.

### void zoomTo(factor, rate)

Zooms to a zoom factor factor using rate.

The rate is specified in powers of two per second. At a rate of 1 it would take 2 seconds to go from a zoom factor of 1 to 4.

Note: Using a specific rate is not supported on all cameras. If not supported, zooming will happen as fast as possible.