# QtCameraDemo

**Repository Path**: icediv/qt-camera-demo

## Basic Information

- **Project Name**: QtCameraDemo
- **Description**: Qt5.12.9 官方demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2025-12-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qt5 摄像头 Demo 使用文档

## 项目简介

这是基于 Qt5 官方示例的摄像头演示项目，实现了完整的摄像头功能，包括拍照和视频录制。本项目使用 Qt Multimedia 模块，展示如何使用 Qt 的官方组件来控制摄像头设备。

## 核心功能

- 📷 **拍照功能**：支持静态图像捕获
- 🎥 **视频录制**：支持视频录制、暂停和停止
- 🎛️ **参数配置**：支持图像和视频的多种参数设置
- 📹 **实时预览**：摄像头画面实时显示
- 🎯 **自动对焦**：支持自动对焦和手动解锁

## 主要 Qt 组件说明

### 1. 核心类

- **QCamera**：摄像头控制核心类
- **QCameraImageCapture**：图像捕获类
- **QMediaRecorder**：媒体录制类
- **QCameraViewfinder**：摄像头预览窗口

## 详细功能实现指南

### 一、获取摄像头列表

使用 `QCameraInfo` 类获取系统中所有可用的摄像头设备。

```cpp
#include <QCameraInfo>

// 获取所有可用摄像头列表
const QList<QCameraInfo> availableCameras = QCameraInfo::availableCameras();

// 遍历摄像头列表
for (const QCameraInfo &cameraInfo : availableCameras) {
    QString description = cameraInfo.description();  // 摄像头描述
    QString deviceName = cameraInfo.deviceName();    // 设备名称
    
    // 判断是否为默认摄像头
    if (cameraInfo == QCameraInfo::defaultCamera()) {
        // 这是系统默认摄像头
    }
}

// 获取默认摄像头
QCameraInfo defaultCamera = QCameraInfo::defaultCamera();
```

**本项目实现位置**：`camera.cpp` 构造函数（第 75-88 行）

### 二、选择和切换摄像头

创建 QCamera 对象时传入 QCameraInfo 参数来选择特定摄像头。

```cpp
// 选择特定摄像头
void Camera::setCamera(const QCameraInfo &cameraInfo)
{
    // 创建摄像头对象
    m_camera.reset(new QCamera(cameraInfo));
    
    // 设置预览窗口
    m_camera->setViewfinder(ui->viewfinder);
    
    // 启动摄像头
    m_camera->start();
}
```

**本项目实现**：
- `setCamera()` 方法：`camera.cpp` 第 95-133 行
- 菜单切换：通过 "Devices" 菜单选择不同摄像头

### 三、摄像头参数设置

#### 3.1 图像参数设置（拍照模式）

支持的参数包括：

| 参数类型 | 说明 | Qt 类/方法 |
|---------|------|-----------|
| **图像编码格式** | JPEG、PNG 等 | `QImageEncoderSettings::setCodec()` |
| **图像质量** | 低、中、高、很高、非常高 5 个等级 | `QImageEncoderSettings::setQuality()` |
| **分辨率** | 如 1920x1080、1280x720 等 | `QImageEncoderSettings::setResolution()` |

**代码实现示例**：

```cpp
// 配置图像设置
QImageEncoderSettings imageSettings;

// 设置编码格式
imageSettings.setCodec("image/jpeg");

// 设置质量（0-4，对应 VeryLowQuality 到 VeryHighQuality）
imageSettings.setQuality(QMultimedia::VeryHighQuality);

// 设置分辨率
imageSettings.setResolution(QSize(1920, 1080));

// 应用设置
m_imageCapture->setEncodingSettings(imageSettings);
```

**本项目实现位置**：
- 设置对话框：`imagesettings.cpp`
- 配置方法：`camera.cpp` 的 `configureImageSettings()` 第 234-244 行

#### 3.2 视频参数设置（录制模式）

支持的参数包括：

**视频参数**：

| 参数类型 | 说明 | Qt 类/方法 |
|---------|------|-----------|
| **视频编码格式** | H.264、MPEG4、VP8 等 | `QVideoEncoderSettings::setCodec()` |
| **视频质量** | 5 个质量等级 | `QVideoEncoderSettings::setQuality()` |
| **分辨率** | 如 1920x1080、1280x720 等 | `QVideoEncoderSettings::setResolution()` |
| **帧率** | 如 30fps、60fps 等 | `QVideoEncoderSettings::setFrameRate()` |
| **容器格式** | MP4、AVI、MOV 等 | `QMediaRecorder::setContainerFormat()` |

**音频参数**：

| 参数类型 | 说明 | Qt 类/方法 |
|---------|------|-----------|
| **音频编码格式** | AAC、MP3、PCM 等 | `QAudioEncoderSettings::setCodec()` |
| **音频质量** | 5 个质量等级 | `QAudioEncoderSettings::setQuality()` |
| **采样率** | 如 44100Hz、48000Hz 等 | `QAudioEncoderSettings::setSampleRate()` |

**代码实现示例**：

```cpp
// 配置视频设置
QVideoEncoderSettings videoSettings;
videoSettings.setCodec("video/x-h264");
videoSettings.setQuality(QMultimedia::HighQuality);
videoSettings.setResolution(QSize(1920, 1080));
videoSettings.setFrameRate(30.0);

// 配置音频设置
QAudioEncoderSettings audioSettings;
audioSettings.setCodec("audio/aac");
audioSettings.setQuality(QMultimedia::HighQuality);
audioSettings.setSampleRate(48000);

// 设置容器格式
QString containerFormat = "video/mp4";

// 应用设置
m_mediaRecorder->setEncodingSettings(audioSettings, videoSettings, containerFormat);
```

**本项目实现位置**：
- 设置对话框：`videosettings.cpp`
- 配置方法：`camera.cpp` 的 `configureVideoSettings()` 第 218-232 行

#### 3.3 曝光补偿设置

```cpp
// 设置曝光补偿（范围通常是 -2.0 到 +2.0）
m_camera->exposure()->setExposureCompensation(0.5);  // +0.5 档
```

**本项目实现位置**：`camera.cpp` 第 376-379 行

### 四、执行拍照

#### 4.1 基本拍照流程

```cpp
// 1. 设置捕获模式为静态图像
m_camera->setCaptureMode(QCamera::CaptureStillImage);

// 2. 连接信号槽接收捕获结果
connect(m_imageCapture, &QCameraImageCapture::imageCaptured, 
        this, &Camera::processCapturedImage);
connect(m_imageCapture, &QCameraImageCapture::imageSaved, 
        this, &Camera::imageSaved);
connect(m_imageCapture, &QCameraImageCapture::error, 
        this, &Camera::displayCaptureError);

// 3. 执行拍照
m_imageCapture->capture();

// 4. 处理捕获的图像（在信号槽中）
void Camera::processCapturedImage(int requestId, const QImage& img)
{
    // 处理图像，如显示预览
    QPixmap pixmap = QPixmap::fromImage(img);
    ui->previewLabel->setPixmap(pixmap);
}

void Camera::imageSaved(int id, const QString &fileName)
{
    // 图像已保存到文件
    qDebug() << "Image saved to:" << fileName;
}
```

**本项目实现位置**：
- 拍照方法：`camera.cpp` 的 `takeImage()` 第 318-321 行
- 图像处理：`processCapturedImage()` 第 191-201 行
- 保存回调：`imageSaved()` 第 415-423 行

**操作步骤**：
1. 切换到 "Image" 标签页
2. 点击 "Capture Photo" 按钮
3. 图像会显示 4 秒预览后返回实时画面

### 五、执行视频录制

#### 5.1 基本录制流程

```cpp
// 1. 设置捕获模式为视频
m_camera->setCaptureMode(QCamera::CaptureVideo);

// 2. 连接媒体录制器信号
connect(m_mediaRecorder, &QMediaRecorder::stateChanged, 
        this, &Camera::updateRecorderState);
connect(m_mediaRecorder, &QMediaRecorder::durationChanged, 
        this, &Camera::updateRecordTime);
connect(m_mediaRecorder, &QMediaRecorder::error, 
        this, &Camera::displayRecorderError);

// 3. 开始录制
m_mediaRecorder->record();

// 4. 暂停录制
m_mediaRecorder->pause();

// 5. 停止录制
m_mediaRecorder->stop();

// 6. 静音控制
m_mediaRecorder->setMuted(true);  // 静音
```

**本项目实现位置**：
- 录制方法：`camera.cpp` 第 246-260 行
- 状态更新：`updateRecorderState()` 第 356-374 行
- 时间更新：`updateRecordTime()` 第 183-187 行

**操作步骤**：
1. 切换到 "Video" 标签页
2. 点击 "Record" 开始录制
3. 点击 "Pause" 暂停录制
4. 点击 "Stop" 停止并保存录制
5. 使用 "Mute" 按钮控制音频录制

### 六、自动对焦功能

```cpp
// 自动对焦
m_camera->searchAndLock();

// 解除对焦锁定
m_camera->unlock();

// 监听对焦状态
connect(m_camera, &QCamera::lockStatusChanged, 
        this, &Camera::updateLockStatus);

void Camera::updateLockStatus(QCamera::LockStatus status, QCamera::LockChangeReason reason)
{
    switch (status) {
    case QCamera::Searching:
        // 正在对焦
        break;
    case QCamera::Locked:
        // 对焦成功
        break;
    case QCamera::Unlocked:
        // 已解锁（或对焦失败）
        break;
    }
}
```

**本项目实现位置**：
- 对焦切换：`toggleLock()` 第 262-271 行
- 状态更新：`updateLockStatus()` 第 273-294 行

**操作步骤**：点击 "Focus" 按钮进行自动对焦

## 完整的使用流程

### 启动和配置

1. **启动应用程序**
   - 程序会自动使用系统默认摄像头
   - 通过 "File" → "Start Camera" 启动摄像头

2. **选择摄像头**
   - 菜单 "Devices" 列出所有可用摄像头
   - 点击选择要使用的摄像头

3. **配置参数**
   - 菜单 "File" → "Settings" 打开设置对话框
   - 根据当前模式（Image/Video）显示对应的参数设置界面

### 拍照操作

1. 切换到 "Image" 标签页
2. （可选）点击 "Focus" 进行自动对焦
3. （可选）调整曝光补偿滑块
4. 点击 "Capture Photo" 拍照
5. 查看预览图像（显示 4 秒后自动返回）

### 录像操作

1. 切换到 "Video" 标签页
2. （可选）点击 "Mute" 控制是否录制声音
3. 点击 "Record" 开始录制
4. 状态栏显示录制时长
5. 点击 "Pause" 暂停录制（可继续）
6. 点击 "Stop" 停止并保存录制

## 注意事项

### 1. 摄像头权限

- **Windows**：确保应用程序有摄像头访问权限
- **隐私设置**：在 Windows 设置中检查"相机"权限
- **防火墙/杀毒软件**：可能会阻止摄像头访问

### 2. 平台兼容性

- 不同平台支持的编码格式和参数可能不同
- 使用 `QMediaRecorder::supportedVideoCodecs()` 等方法查询支持的参数
- 某些摄像头可能不支持所有分辨率和帧率

### 3. 视频标签页无法点击问题

**问题原因**：摄像头驱动可能不报告视频录制支持，导致 `isCaptureModeSupported(QCamera::CaptureVideo)` 返回 false。

**解决方案**：修改 `camera.cpp` 第 129-130 行：

```cpp
// 原代码（可能导致视频标签页被禁用）
ui->captureWidget->setTabEnabled(0, (m_camera->isCaptureModeSupported(QCamera::CaptureStillImage)));
ui->captureWidget->setTabEnabled(1, (m_camera->isCaptureModeSupported(QCamera::CaptureVideo)));

// 修改为强制启用（推荐）
ui->captureWidget->setTabEnabled(0, true);
ui->captureWidget->setTabEnabled(1, true);
```

### 4. 文件保存位置

- 默认保存位置取决于系统配置
- 可以通过 `QCameraImageCapture::setCaptureDestination()` 设置保存位置
- 建议在代码中显式设置保存路径

### 5. 性能考虑

- 高分辨率和高帧率会占用更多系统资源
- 录制长时间视频需要足够的磁盘空间
- 建议根据实际需求选择合适的参数

### 6. 错误处理

项目已实现完善的错误处理机制：

```cpp
// 摄像头错误
connect(m_camera, &QCamera::error, this, &Camera::displayCameraError);

// 图像捕获错误
connect(m_imageCapture, &QCameraImageCapture::error, 
        this, &Camera::displayCaptureError);

// 录制错误
connect(m_mediaRecorder, &QMediaRecorder::error, 
        this, &Camera::displayRecorderError);
```

### 7. 资源释放

- 关闭应用前会自动停止摄像头
- 切换摄像头时会正确释放之前的资源
- 使用 `QScopedPointer` 确保自动内存管理

## 快捷键支持

- **CameraFocus 键**：触发自动对焦
- **Camera 键**：在图像模式下拍照，在视频模式下开始/停止录制

## 项目结构

```
camera-demo/
├── camera.h/cpp          # 主窗口类
├── camera.ui             # UI 界面文件
├── imagesettings.h/cpp   # 图像参数设置对话框
├── imagesettings.ui      # 图像设置界面
├── videosettings.h/cpp   # 视频参数设置对话框
├── videosettings.ui      # 视频设置界面
├── main.cpp              # 程序入口
├── camera.pro            # Qt 项目文件
└── README.md             # 本文档
```

## 编译和运行

### 依赖项

- Qt 5.x（需包含 Qt Multimedia 模块）
- 支持的编译器：MSVC、MinGW、GCC、Clang

### 编译步骤

```bash
# 使用 qmake
qmake camera.pro
make  # Windows 上使用 nmake 或 mingw32-make

# 或使用 Qt Creator
# 直接打开 camera.pro 文件并点击运行
```

## 技术要点总结

1. **QCameraInfo**：获取和枚举摄像头设备
2. **QCamera**：摄像头核心控制，管理捕获模式和状态
3. **QCameraImageCapture**：静态图像捕获
4. **QMediaRecorder**：视频和音频录制
5. **QImageEncoderSettings**：图像编码参数配置
6. **QVideoEncoderSettings**：视频编码参数配置
7. **QAudioEncoderSettings**：音频编码参数配置
8. **信号槽机制**：异步处理捕获和录制事件

## 扩展建议

1. **添加保存路径选择**：允许用户选择保存位置
2. **支持多种图像格式**：添加格式选择器
3. **实时滤镜效果**：使用 QVideoProbe 处理视频帧
4. **缩略图管理**：保存历史照片和视频的缩略图
5. **参数预设**：保存常用的参数配置方案

## 常见问题 FAQ

**Q: 为什么看不到摄像头画面？**  
A: 检查摄像头是否被其他程序占用，确认系统权限设置，尝试重启应用。

**Q: 录制的视频没有声音？**  
A: 检查是否点击了 "Mute" 按钮，确认麦克风权限。

**Q: 支持哪些视频格式？**  
A: 取决于系统和 Qt Multimedia 后端，Windows 上通常支持 MP4、AVI 等。

**Q: 如何获取支持的参数列表？**  
A: 使用 `QMediaRecorder::supportedVideoCodecs()`、`supportedResolutions()` 等方法查询。

---

**版权信息**：本项目基于 Qt 官方示例，遵循 BSD 许可证。