QT(19)-QCamera

QT(19）-QCamera

1 公有类型
- 1.1 帧速率
- 1.2 捕获模式
- 1.3 错误类型
- 1.4 摄像头锁定状态改变的原因
- 1.5 摄像头锁定的整体状态
- 1.6 摄像头可以应用锁定的类型
- 1.7 QCamera::Position
- 1.8 QCamera::State
- 1.9 QCamera::Status
2 公有函数
- 2.1 构造函数:
- 2.2 析构函数:
- 2.3 成员函数:
3 公有槽
4 信号

1 公有类型

1.1 帧速率

struct FrameRateRange
{qreal	maximumFrameRate;qreal	minimumFrameRate;
}

当最小帧率等于最大帧率时，表示帧率固定。如果不是，实际帧率在最小值和最大值之间波动。

1.2 捕获模式

QCamera::CaptureMode

QCamera::CaptureViewfinder (0): 摄像头仅配置为显示取景器，这意味着摄像头被激活用于预览，但不捕获图片或视频。这个模式常用于实时查看而不进行实质性的捕获操作。
QCamera::CaptureStillImage (0x01): 摄像头配置为捕获静态图像。在这种模式下，摄像头被优化用于拍照，可以捕获单个图片帧。
QCamera::CaptureVideo (0x02): 摄像头配置为视频捕获。此模式下，摄像头用于录制连续的视频帧。

这些模式可以单独使用，也可以组合使用，这样可以允许同时设置多个模式（如果摄像头硬件支持的话）。例如，可以同时设置 CaptureStillImage 和 CaptureVideo，如果摄像头能够同时处理静态图像捕获和视频录制的话。

1.3 错误类型

QCamera::Error

QCamera::NoError (0): 没有错误发生。这意味着摄像头操作正常，没有检测到任何问题。
QCamera::CameraError (1): 发生了一个通用的摄像头错误。这是一个泛型错误，表明在操作摄像头时出现了问题，但没有更具体的错误信息。
QCamera::InvalidRequestError (2): 系统资源不支持请求的功能。这意味着尝试执行的操作不被当前系统的摄像头或相关资源支持。
QCamera::ServiceMissingError (3): 没有可用的摄像头服务。这个错误表明应用程序尝试访问的摄像头服务不存在，可能是因为硬件问题、驱动程序未安装或系统配置问题。
QCamera::NotSupportedFeatureError (4): 不支持的功能。这表明尝试使用的摄像头特性或功能不被当前的摄像头硬件或驱动程序支持。

1.4 摄像头锁定状态改变的原因

QCamera::LockChangeReason

QCamera::LockChangeReason 枚举定义了摄像头锁定状态改变的原因。这些状态变更原因有助于理解和响应摄像头的锁定机制，尤其是在自动对焦和曝光控制等方面。以下是各个常量的详细说明：
QCamera::UserRequest (0): 锁定状态因用户请求而改变，通常是为了解锁摄像头设置。这表明状态变更是由用户的操作引起的，如用户主动改变对焦或曝光设置。
QCamera::LockAcquired (1): 锁定状态成功变更为 QCamera::Locked。这意味着摄像头已成功获取所需的锁定（例如自动对焦锁定），并且现在处于锁定状态。
QCamera::LockFailed (2): 摄像头未能获取请求的锁定，可能是由于自动对焦失败、曝光超出支持范围等原因。这表明尽管有尝试，但摄像头未能实现或维持请求的锁定状态。
QCamera::LockLost (3): 摄像头无法维持请求的锁定。锁定状态改变为 QCamera::Unlocked。这通常发生在摄像头无法保持当前的焦点或曝光设置时。
QCamera::LockTemporaryLost (4): 锁定丢失，但摄像头正在努力重新获取。这个值常用于连续对焦模式中，当摄像头失去焦点时，焦点锁定状态会改变为 Qcamera::Searching，原因是 LockTemporaryLost。这表明摄像头正在尝试恢复到先前的锁定状态。

了解这些锁定变更原因有助于开发者编写更为精细和响应用户操作的摄像头控制逻辑，从而提升应用程序的用户体验和性能。

1.5 摄像头锁定的整体状态

QCamera::LockStatus 枚举定义了摄像头锁定的整体状态，这些状态反映了摄像头对焦、曝光或白平衡锁定的当前状况。这些状态有助于开发者了解摄像头当前的操作模式和行为。以下是每个常量的详细描述：

QCamera::Unlocked (0): 应用程序对摄像头设置的值不感兴趣。摄像头可能会保持这个参数不变，这在对焦功能中很常见，或者为了保持取景器图像的质量，不断调整曝光和白平衡。在这种状态下，摄像头没有被锁定到特定的焦点、曝光或白平衡设置。
QCamera::Searching (1): 应用程序已经请求摄像头的对焦、曝光或白平衡锁定，使用了 QCamera::searchAndLock() 方法。这个状态表明摄像头正在聚焦或计算曝光和白平衡。在此阶段，摄像头正努力确定最佳的设置值。
QCamera::Locked (2): 摄像头的对焦、曝光或白平衡已经锁定。摄像头已经准备好进行捕获，应用程序可以检查曝光是否保持不变。通常情况下，“锁定”状态意味着请求的参数被锁定，除非在需要不断更新参数的情况下（例如，在连续对焦模式下，只要物体处于焦点中，即使实际对焦距离可能不断变化，焦点也被视为锁定）。

这些状态使应用程序能够更精确地控制摄像头行为，例如，在捕获关键瞬间之前确保摄像头已经正确对焦和调整了曝光。通过这种方式，可以提高图片或视频质量，并确保在需要时能够捕获最佳图像。

1.6 摄像头可以应用锁定的类型

QCamera::LockType 枚举定义了摄像头可以应用锁定的类型。这些锁定类型用于控制摄像头的不同功能，如曝光、白平衡和对焦。QCamera::LockTypes 是一个通过 QFlags 定义的类型，它允许组合不同的 LockType 值来同时应用多种锁定。以下是 LockType 枚举的详细描述：

QCamera::NoLock (0): 没有应用任何锁定。这个值表示摄像头的所有功能都处于自动调节模式，没有任何特定的锁定限制。
QCamera::LockExposure (0x01): 锁定摄像头的曝光设置。在这种锁定类型下，摄像头的曝光设置被固定，不会根据环境光线的变化自动调整。
QCamera::LockWhiteBalance (0x02): 锁定摄像头的白平衡设置。启用这种锁定后，摄像头会保持当前的白平衡设置，不会根据环境光源的颜色变化进行调整。
QCamera::LockFocus (0x04): 锁定摄像头的对焦点。这意味着一旦锁定，摄像头的焦点不会随着场景中物体的移动或距离的改变而改变。

它允许将多个 LockType 值通过位或操作组合起来，这样可以同时请求多种类型的锁定。例如，如果应用程序需要在拍摄过程中保持曝光和对焦不变，可以将 LockExposure 和 LockFocus 组合使用。

这种灵活性使得开发者可以根据需要精确控制摄像头的行为，以适应不同的拍摄条件和要求。

1.7 QCamera::Position

QCamera::Position 枚举用于指定摄像头在系统硬件上的物理位置。这对于区分设备上前置和后置摄像头特别有用，尤其是在移动设备或具有多个摄像头的系统上。以下是各个常量的详细描述：

QCamera::UnspecifiedPosition (0): 摄像头位置未指定或未知。这个值用于表示无法确定摄像头的具体位置，或者位置信息不适用的情况。
QCamera::BackFace (1): 摄像头位于系统硬件的背面。例如，在移动设备上，这意味着摄像头位于与屏幕相反的一侧。后置摄像头通常用于拍摄远距离的物体或景色。
QCamera::FrontFace (2): 摄像头位于系统硬件的前面。例如，在移动设备上，这表示摄像头与屏幕在同一侧。前置摄像头常用于自拍或视频通话，其取景器帧通常会水平镜像，使用户能够像看镜子一样看到自己。然而，捕获的图像或视频并不会被镜像。

通过识别摄像头的物理位置，应用程序可以提供更符合用户期望的行为，例如，自动选择后置摄像头进行拍照或视频录制，选择前置摄像头进行自拍或视频通话。此外，处理镜像视图也是前置摄像头特有的需求，因此知道摄像头的位置可以帮助适当调整用户界面和图像处理流程。

1.8 QCamera::State

QCamera::State 枚举定义了摄像头的不同工作状态，表示摄像头当前的操作模式和可用性。这些状态有助于管理摄像头的生命周期和配置过程。以下是各个常量的详细描述：

QCamera::UnloadedState (0): 这是摄像头的初始状态，此时摄像头未加载。在这个状态下，除了支持的捕获模式之外，摄像头的能力是未知的。虽然在这个状态下支持的设置未知，但仍允许设置摄像头捕获设置，如编解码器、分辨率或帧率。
QCamera::LoadedState (1): 摄像头已加载并准备配置。在这个状态下，允许查询摄像头的能力，设置捕获分辨率、编解码器等。但是，取景器在加载状态下不处于活动状态。在加载状态下，摄像头消耗电力。
QCamera::ActiveState (2): 当摄像头启动后，进入活动状态。在这个状态下，取景器显示视频帧，摄像头准备好进行捕获。活动状态表示摄像头正在运行，并且可以执行捕获任务，如拍照或录像。

通过这些状态，QCamera 类提供了对摄像头操作的详细控制，允许开发者根据应用程序的需求来管理摄像头资源。例如，可以在应用程序不需要摄像头时将其卸载以节省电力，或者在需要进行视频捕获之前加载和配置摄像头。

1.9 QCamera::Status

QCamera::Status 枚举详细定义了摄像头的当前状态，这些状态提供了关于摄像头操作和可用性的更细致信息。以下是每个状态的详细描述：

QCamera::ActiveStatus (8): 摄像头已启动并能产生数据。在活动状态下，取景器显示视频帧。根据后端，更改某些摄像头设置（如捕获模式、编解码器或分辨率）可能会导致摄像头状态变更为 LoadedStatus 和 StartingStatus，以应用设置，然后在摄像头准备就绪时恢复到 ActiveStatus。
QCamera::StartingStatus (6): 摄像头正在启动，作为状态变为 QCamera::ActiveState 的结果。此时，摄像头服务还未准备好进行捕获。
QCamera::StoppingStatus (7): 摄像头正在停止，作为状态从 QCamera::ActiveState 变更到 QCamera::LoadedState 或 QCamera::UnloadedState 的结果。
QCamera::StandbyStatus (5): 摄像头处于省电的待机模式。在 QCamera::LoadedState 状态下，经过一段时间的不活动后，摄像头可能进入待机模式。
QCamera::LoadedStatus (4): 摄像头已加载并准备配置。这个状态表明摄像头设备已打开，并且可以查询支持的图像和视频捕获设置，如分辨率、帧率和编解码器。
QCamera::LoadingStatus (2): 摄像头设备正在加载，作为状态从 QCamera::UnloadedState 变更到 QCamera::LoadedState 或 QCamera::ActiveState 的结果。
QCamera::UnloadingStatus (3): 摄像头设备正在卸载，作为状态从 QCamera::LoadedState 或 QCamera::ActiveState 变更到 QCamera::UnloadedState 的结果。
QCamera::UnloadedStatus (1): 摄像头的初始状态，此时摄像头未加载。包括支持的捕获设置在内的摄像头能力可能未知。
QCamera::UnavailableStatus (0): 摄像头或摄像头后端不可用。

这些状态为开发者提供了精确的摄像头状态信息，帮助他们更好地管理摄像头资源，优化应用程序的性能，并处理各种摄像头操作相关的情况。

2 公有函数

2.1 构造函数:

QCamera(QCamera::Position position, QObject *parent = nullptr): 根据摄像头的物理位置（前置或后置）创建一个 QCamera 对象。
QCamera(const QCameraInfo &cameraInfo, QObject *parent = nullptr): 使用指定的 QCameraInfo 对象来初始化 QCamera，可以选择特定的摄像头。
QCamera(const QByteArray &deviceName, QObject *parent = nullptr): 使用设备名称来初始化 QCamera。
QCamera(QObject *parent = nullptr): 默认构造函数，创建一个 QCamera 对象。

2.2 析构函数:

virtual ~QCamera(): 虚析构函数，确保子类的适当清理。

2.3 成员函数:

QCamera::CaptureModes captureMode() const: 返回当前设置的捕获模式。
QCamera::Error error() const: 返回最后的错误代码。
QString errorString() const: 返回关于最后错误的详细描述。
QCameraExposure *exposure() const: 返回控制摄像头曝光的对象。
QCameraFocus *focus() const: 返回控制摄像头对焦的对象。
QCameraImageProcessing *imageProcessing() const: 返回处理摄像头图像的对象。
bool isCaptureModeSupported(QCamera::CaptureModes mode) const: 检查特定的捕获模式是否被支持。
QCamera::LockStatus lockStatus() const: 返回摄像头的锁定状态。
QCamera::LockStatus lockStatus(QCamera::LockType lockType) const: 返回指定类型锁定的状态。
QCamera::LockTypes requestedLocks() const: 返回请求的锁定类型。
void setViewfinder(QVideoWidget *viewfinder): 设置视频取景器。
void setViewfinder(QGraphicsVideoItem *viewfinder): 设置图形视图项为取景器。
void setViewfinder(QAbstractVideoSurface *surface): 设置视频表面为取景器。
void setViewfinderSettings(const QCameraViewfinderSettings &settings): 设置取景器的配置。
QCamera::State state() const: 返回摄像头的状态。
QCamera::Status status() const: 返回摄像头的详细状态。
QCamera::LockTypes supportedLocks() const: 返回支持的锁定类型。
QList< QCamera::FrameRateRange> supportedViewfinderFrameRateRanges(…) const: 返回支持的取景器帧率范围。
QList< QVideoFrame::PixelFormat> supportedViewfinderPixelFormats(…) const: 返回支持的取景器像素格式。
QList< QSize> supportedViewfinderResolutions(…) const: 返回支持的取景器分辨率。
QList < QCameraViewfinderSettings> supportedViewfinderSettings(…) const: 返回支持的取景器设置。
QCameraViewfinderSettings viewfinderSettings() const: 获取当前取景器的设置。

3 公有槽

QCamera 类的公共槽（Public Slots）提供了一组函数，使得可以在运行时通过信号和槽机制控制摄像头的行为。这些槽可以被 Qt 事件处理系统或者其他 Qt 对象通过信号连接和调用。下面是每个公共槽的简要说明：

load(): 加载摄像头设备，使其准备就绪但不开始捕获。这个槽用于将摄像头从未加载状态转变为加载状态，这时可以查询摄像头的能力并进行配置。
searchAndLock(QCamera::LockTypes locks): 请求锁定指定类型的摄像头功能，如对焦、曝光或白平衡。这通常用于在拍照或录像前确保摄像头设置稳定。
searchAndLock(): 请求锁定所有支持的摄像头功能，通常是对焦、曝光和白平衡。这个槽函数不需要参数，表示锁定所有可能的类型。
setCaptureMode(QCamera::CaptureModes mode): 设置摄像头的捕获模式，如静态图像、视频等。这个槽允许在运行时改变摄像头的工作模式。
start(): 启动摄像头并开始捕获视频流到取景器或直接进行视频或图像捕获。这个槽函数会将摄像头从加载状态或未加载状态转变为活动状态。
stop(): 停止摄像头的活动，包括视频捕获和取景器的预览。这将把摄像头从活动状态转换回加载状态或未加载状态，取决于之前的状态。
unload(): 卸载摄像头设备，释放相关资源。这个槽函数用于从加载状态或活动状态转换回未加载状态。
unlock(QCamera::LockTypes locks): 解锁指定类型的摄像头功能。这通常在捕获完成后使用，以允许摄像头自动调整对焦、曝光和白平衡。
unlock(): 解锁所有之前锁定的摄像头功能。这个槽函数不需要参数，表示解锁所有之前通过 searchAndLock 锁定的功能。

这些槽为开发者提供了灵活的方式来控制摄像头的状态和功能，使得可以根据应用程序的需求动态调整摄像头的配置和行为。通过信号和槽机制，可以方便地在 Qt 的事件驱动框架中集成摄像头控制逻辑。

4 信号

在 QCamera 类中，信号（Signals）用于通知应用程序有关摄像头状态的变化或特定事件的发生。这些信号可以被应用程序捕获，以便进行适当的响应或处理。以下是 QCamera 类中定义的信号及其描述：

captureModeChanged(QCamera::CaptureModes mode): 当摄像头的捕获模式改变时发出。它提供了新的捕获模式作为参数。
errorOccurred(QCamera::Error value): 当摄像头遇到错误时发出。它提供了错误类型作为参数，允许应用程序识别和响应具体的错误情况。
lockFailed(): 当摄像头尝试锁定（对焦、曝光或白平衡）但失败时发出。这可以用于通知用户锁定操作未成功。
lockStatusChanged(QCamera::LockType lock, QCamera::LockStatus status, QCamera::LockChangeReason reason): 当摄像头的锁定状态改变时发出。它提供了锁定类型、新的锁定状态和状态变化的原因。
lockStatusChanged(QCamera::LockStatus status, QCamera::LockChangeReason reason): 这是重载形式，用于通知锁定状态的通用变化，而不是特定类型的锁定。
locked(): 当摄像头成功锁定（对焦、曝光或白平衡）时发出。这可以用来通知应用程序摄像头已准备好进行捕获。
stateChanged(QCamera::State state): 当摄像头的状态改变时发出。它提供了新的状态作为参数。
statusChanged(QCamera::Status status): 当摄像头的详细状态改变时发出。这个信号提供了新的详细状态作为参数。