Back to Qt.io
Contact Us Blog Download Qt

Camera QML Type

与对焦和变焦相关的相机设置界面。更多

Import Statement: import QtMultimedia
In C++: QCamera

属性

信号

方法

详细说明

摄像头元素可在CaptureSession 中用于视频录制和图像拍摄。

您可以使用MediaDevices 列出可用的摄像头，并选择使用哪一个。

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

在支持该功能的硬件上，QCamera 可让您调整焦距和变焦。这还包括一些功能，如用于近距离工作的 "微距 "模式（如读取条形码或识别字母），或 "触摸对焦"--指示图像中感兴趣的区域，以便硬件尝试对焦。

Item {
    width: 640
    height: 360

    CaptureSession {
        camera: Camera {
            id: camera

            focusMode: Camera.FocusModeAutoNear
            customFocusPoint: Qt.point(0.2, 0.2) // Focus relative to top-left corner
        }
        videoOutput: videoOutput
    }

    VideoOutput {
        id: videoOutput
        anchors.fill: parent
    }
}

minimumZoomFactor 和maximumZoomFactor 属性提供了支持的缩放系数范围。zoomFactor 属性允许更改变焦系数。

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

在获取相机帧的原始数据后，相机硬件和软件会执行各种图像处理任务，以生成最终图像。这包括补偿环境光色、减少噪点以及对图像进行一些其他调整。

您可以通过 "相机属性 "控制其中的许多处理步骤。例如，您可以设置用于处理图像的白平衡（或色温）：

Camera {
    whiteBalanceMode: Camera.WhiteBalanceManual
    colorTemperature: 5600
}

有关摄像机图像处理的更多信息，请参阅摄像机图像处理。

有关更多信息，请参阅摄像机概述。

属性文档

active : bool

描述摄像机当前是否处于活动状态。


cameraDevice : cameraDevice

获取或设置当前激活的摄像机设备。

切换摄像机设备时，会更新QCamera 的功能。此外，QCamera 的控制属性（如focusMode,flashMode,focusDistance,zoomFactor ）也会更新如下：

  • 如果新设备支持某个属性，则该属性值将应用到摄像机设备。
  • 如果属性受支持，但其有效值范围已更改，则该属性将被箝位到新的范围并应用到摄像机设备。
  • 如果新的摄像机设备不支持某个属性，则该属性值将重置为默认值，并且不会对摄像机设备做任何更改。

cameraFormat : cameraFormat

获取或设置当前激活的摄像机格式。

注： 在 Android 目标设备上使用 FFMPEG 后端时，如果请求YUV420P格式，将收到全平面 4:2:0 YUV420P 或半平面 NV12/NV21 格式。这取决于设备 OEM 实施的编解码器。

另请参阅 cameraDevice::videoFormats 。


customFocusPoint : point

该属性以相对帧坐标表示自定义焦点的位置。这意味着QPointF(0,0) 指向帧的左上角，而QPointF(0.5,0.5) 指向帧的中心。

自定义对焦点仅在FocusPointCustom 对焦模式下使用。

您可以通过使用 Feature.CustomFocusPoint 标志查询 supportedFeatures() 来检查是否支持自定义对焦点。


error : enumeration [read-only]

返回摄像机的错误状态。

另请参阅 QCamera::Error 。


errorString : string [read-only]

返回描述摄像机错误状态的可读字符串。


exposureCompensation : real

以 EV 为单位获取或设置曝光补偿。

曝光补偿属性允许调整自动计算的曝光。


exposureMode : ExposureMode

使用的曝光模式。

另请参阅 QCamera::ExposureMode 和Camera::isExposureModeSupported()。


exposureTime : real [read-only]

以秒为单位返回相机的曝光时间。

另请参阅 manualExposureTime 。


flashMode : enumeration

如果相机有闪光灯，则获取或设置特定的闪光灯模式。

常量说明
Camera.FlashOff闪光灯关闭。
Camera.FlashOn闪光灯打开。
Camera.FlashAuto自动闪光。

另请参阅 isFlashModeSupported 和isFlashReady 。


flashReady : bool [read-only]

指示闪光灯是否已充电并可使用。


focusDistance : real

此属性定义摄像机设备在手动对焦模式下工作时的镜头对焦距离。有效值范围为 0 至 1，其中 0 表示最近的对焦距离，1 表示最远的对焦距离。最远距离通常为无限远，但并非所有设备都是如此。

只有当focusMode 设置为Camera.FocusModeManual ，且supportedFeatures 包含Camera.FocusDistance 标志时，设备才会应用此属性。

如果在focusMode 未设置为Camera.FocusModeManual 时为该属性赋值，则该属性会存储该值，但在Camera.FocusModeManual 激活之前不会影响设备。

在有效范围 [0, 1] 之外赋值对该属性没有影响。

如果supportedFeatures 不包含Camera.FocusDistance 标志，则任何设置该属性的尝试都将被忽略。

在自动对焦模式下，摄像机不会更新此属性。

默认值为 1。


focusMode : enumeration

此属性包含控制摄像机设备对焦模式的值。在所有自动对焦模式下，摄像机设备都会持续对焦。

注： 在自动对焦模式下，如果支持，focusPoint 属性可提供正在对焦的图像区域的信息和控制。

常数说明
Camera.FocusModeAuto连续自动对焦模式。
Camera.FocusModeAutoNear连续自动对焦，偏好靠近相机的物体。
Camera.FocusModeAutoFar连续自动对焦，偏好远离相机的物体。
Camera.FocusModeHyperfocal对焦至超焦距，实现最大景深。从这个距离的一半到无限远处的所有物体都会清晰可接受。
Camera.FocusModeInfinity严格对焦至无限远。
Camera.FocusModeManual镜头焦距设置为focusDistance 指定的值。

要检查相机设备是否支持特定对焦模式，请将相应的focusMode 值作为参数传递给isFocusModeSupported() 函数。如果不支持对焦模式值，函数将返回false 。为该属性指定不支持的模式没有任何作用。

如果将 focusMode 属性设置为Camera.FocusModeManual ，镜头将根据focusDistance 锁定焦点。

另请参阅 isFocusModeSupported().


focusPoint : point [read-only]

返回自动对焦系统当前使用的对焦点。


isoSensitivity : int [read-only]

描述相机当前使用的 ISO 感光度。


manualExposureTime : real

获取或设置手动曝光时间。

将此属性设置为-1（默认值）表示相机自动决定曝光时间。


manualIsoSensitivity : int

描述手动设置的 ISO 感光度

将此属性设置为-1（默认值）表示相机自动调整 ISO 感光度。


maximumZoomFactor : real [read-only]

此属性表示支持的最大变焦系数。

在不支持变焦的相机上将显示为1.0 。


minimumZoomFactor : real [read-only]

此属性表示支持的最小变焦系数。

在不支持变焦的相机上将是1.0 。


supportedFeatures : Features [read-only]

返回此摄像机支持的功能。

另请参阅 QCamera::Feature 。


torchMode : Camera::TorchMode

获取或设置正在使用的电筒模式。

手电筒是一种持续光源。它可以在光线不足的情况下进行视频记录。启用手电筒模式通常会覆盖当前设置的任何闪光灯模式。

另请参阅 QCamera::TorchMode 、Camera::isTorchModeSupported() 和Camera::flashMode 。


whiteBalanceMode : WhiteBalanceMode

获取或设置正在使用的白平衡模式。

另请参阅 QCamera::WhiteBalanceMode 。


zoomFactor : real

获取或设置当前变焦系数。数值将在minimumZoomFactor 和maximumZoomFactor 之间箝位。


信号文档

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

当错误状态变为error 时，将发出此信号。有关错误的描述见errorString 。

注： 相应的处理程序为onErrorOccurred 。


方法文档

colorTemperature()

获取或设置当前色温。

只有在支持白平衡手动设置（WhiteBalanceManual）的情况下，设置色温才会有效。在这种情况下，设置一个大于 0 的色温会自动将白平衡模式设置为白平衡手动模式。将色温设置为 0 会将白平衡模式重置为自动白平衡。


bool isExposureModeSupported(ExposureMode mode)

如果支持曝光mode ，则返回 true。


bool isFlashModeSupported(FlashMode mode)

如果支持闪光灯mode ，则返回 true。


bool isFlashReady()

如果闪光灯已充电，则返回 true。


bool isFocusModeSupported(FocusMode mode)

如果相机支持对焦mode ，则返回true 。

如果报告支持Camera.FocusModeManual ，则暗示也支持该功能Camera.FocusDistance 。


bool isTorchModeSupported(TorchMode mode)

如果支持手电筒mode ，则返回 true。


bool isWhiteBalanceModeSupported(WhiteBalanceMode mode)

如果白平衡mode 受支持，则返回 true。


void start()

启动摄像机。

与将活动属性设置为 true 相同。

如果由于某种原因无法启动摄像机，则会发出errorOccurred() 信号。


void stop()

停止摄像机。与将 active 属性设置为 false 相同。


void zoomTo(factor, rate)

使用rate 变焦至变焦系数factor 。

rate 以每秒 2 的幂来指定。如果变焦率为 1，则从变焦系数 1 变为 4 需要 2 秒。

注： 并非所有摄像机都支持使用特定速率。如果不支持，将尽可能快地进行缩放。


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.