ScreenLockDetector/README.md

# Qt Screen Lock Detection Demo

一个基于 Qt5 + CMake 的跨平台应用程序，用于检测系统的锁屏状态和电源状态（睡眠/唤醒），并在锁屏时自动停止所有渲染。

**支持平台：**
- ✅ **Linux** (Ubuntu, Deepin, Fedora 等)
- ✅ **macOS** (10.12 及以上版本)

## 功能特性

### 核心功能

- ✅ **自动检测锁屏状态**：
  - Linux: 通过 DBus 监听系统的锁屏/解锁事件
  - macOS: 通过 NSDistributedNotificationCenter 监听系统通知

- ✅ **电源状态监控**：
  - Linux: 通过 DBus login1 服务监听系统睡眠/唤醒事件
  - macOS: 通过 NSWorkspace 监听系统电源状态变化

- ✅ **双渲染引擎支持**：
  - **Vulkan 渲染器**：高性能 GPU 加速渲染（需要 Vulkan SDK）
    - Linux: 支持 Vulkan 1.0+
    - macOS: 支持 MoltenVK（Vulkan over Metal）
    - 特性：MSAA 抗锯齿、动态几何、文字渲染（FreeType）
  - **QPainter 渲染器**：传统 Qt 绘制（兼容性备选）

- ✅ **自动停止渲染**：屏幕锁定或系统睡眠时自动停止所有渲染，节省系统资源

- ✅ **实时动画演示**：
  - 动态旋转圆圈
  - 波浪效果
  - 渐变背景
  - 实时文字显示

- ✅ **手动控制**：提供手动启用/禁用渲染的按钮

- ✅ **状态监控**：实时显示锁屏状态、电源状态、渲染状态和帧数统计

- ✅ **多平台支持**：
  - Linux: 支持 GNOME、KDE、XFCE、Deepin DDE、UKUI 等主流桌面环境
  - macOS: 原生系统通知支持，MoltenVK 集成

## 技术架构

### 核心组件

1. **ScreenLockDetector** - 跨平台锁屏检测器
   - **基础架构**: `ScreenLockDetectorBase` 抽象基类
   - **Linux**: `ScreenLockDetectorLinux` - 通过 Qt DBus 监听系统锁屏信号
     - 支持 GNOME ScreenSaver、systemd-logind 和 Deepin DDE 接口
   - **macOS**: `ScreenLockDetectorMacOS` - 通过 NSDistributedNotificationCenter 监听系统通知
     - 监听 com.apple.screenIsLocked/Unlocked 通知
   - 发出锁屏/解锁信号供其他组件订阅

2. **PowerMonitor** - 跨平台电源监视器
   - **基础架构**: `PowerMonitorBase` 抽象基类
   - **Linux**: `PowerMonitorLinux` - 通过 DBus login1 服务监听
     - 监听 org.freedesktop.login1.Manager 的 PrepareForSleep 信号
   - **macOS**: `PowerMonitorMacOS` - 通过 NSWorkspace 监听
     - 监听 NSWorkspaceWillSleepNotification 和 NSWorkspaceDidWakeNotification
   - 发出睡眠/唤醒信号

3. **RenderWidgetBase** - 渲染组件抽象接口
   - 定义统一的渲染器接口
   - 支持动态切换不同渲染后端

4. **VulkanWidget** - Vulkan 渲染组件
   - 使用 volk 动态加载 Vulkan 函数
   - 支持 MSAA 多重采样抗锯齿
   - 集成 FreeType 字体渲染
   - **macOS**: 专门的 CAMetalLayer 支持（MoltenVK）
   - 自动处理窗口大小调整和设备丢失恢复

5. **CustomWidget** - QPainter 渲染组件
   - 传统 Qt 绘制实现
   - 作为 Vulkan 不可用时的备选方案
   - 实现了相同的动画效果

6. **MainWindow** - 主窗口
   - 整合各个组件
   - 提供用户界面和控制面板
   - 实时状态显示

### 技术栈

- **语言**：C++11 / Objective-C++ (macOS)
- **GUI 框架**：Qt 5.15.2 (或更高版本)
- **构建系统**：CMake 3.10+
- **图形 API**：
  - Vulkan 1.0+ (通过 volk 动态加载)
  - MoltenVK (macOS)
  - QPainter (备选方案)
- **字体渲染**：FreeType 2.x
- **系统接口**：
  - Linux: Qt DBus, X11
  - macOS: Foundation Framework, AppKit, QuartzCore (CAMetalLayer)
- **平台**：Linux / macOS 10.12+

### 项目结构

```
ScreenLockDetector/
├── CMakeLists.txt                    # CMake 构建配置（跨平台）
├── README.md                         # 项目文档
├── build.sh                          # Linux 编译脚本
├── run.sh                            # Linux 运行脚本
├── build_mac.sh                      # macOS 编译脚本
├── run_mac.sh                        # macOS 运行脚本
├── docs/                             # 文档目录
├── third_party/                      # 第三方库
│   └── volk/                         # Vulkan 函数加载器
├── shaders/                          # GLSL 着色器源码
└── src/
    ├── main.cpp                      # 程序入口
    ├── mainwindow.h/cpp              # 主窗口
    ├── screenlockdetector.h/cpp      # 锁屏检测器工厂类
    ├── powermonitor.h/cpp            # 电源监视器工厂类
    ├── renderwidgetbase.h            # 渲染组件抽象接口
    ├── vulkanwidget.h/cpp            # Vulkan 渲染组件
    ├── vulkanrenderer.h/cpp          # Vulkan 渲染器核心
    ├── customwidget.h/cpp            # QPainter 渲染组件
    └── platform/                     # 平台特定代码
        ├── README.md                 # 平台代码组织说明
        ├── screenlockdetector_base.h/cpp      # 锁屏检测基类
        ├── screenlockdetector_linux.h/cpp     # Linux 实现
        ├── screenlockdetector_macos.h/mm      # macOS 实现
        ├── powermonitor_base.h/cpp            # 电源监视基类
        ├── powermonitor_linux.h/cpp           # Linux 实现
        ├── powermonitor_macos.h/mm            # macOS 实现
        └── vulkanwidget_macos.h/mm            # macOS Vulkan 辅助
```

## 系统要求

### Linux
- Linux Ubuntu 18.04 或更高版本（也支持 Deepin OS、Fedora 等）
- Qt 5.15.2 或更高版本
- CMake 3.10 或更高版本
- GCC/G++ 编译器（支持 C++11）
- DBus 系统服务
- X11 开发库
- **可选**：Vulkan SDK 1.0+ (用于 Vulkan 渲染)
- **可选**：FreeType 开发库 (用于 Vulkan 文字渲染)

### macOS
- macOS 10.12 (Sierra) 或更高版本
- Qt 5.15.2 或更高版本（可通过 Homebrew 或 MacPorts 安装）
- CMake 3.10 或更高版本
- Xcode Command Line Tools
- Foundation 和 Cocoa 框架（系统自带）
- **可选**：Vulkan SDK 1.4+ (包含 MoltenVK，用于 Vulkan 渲染)
- **可选**：FreeType 库 (用于 Vulkan 文字渲染)

## 安装与编译

### macOS 平台

#### 1. 安装依赖

使用 Homebrew 或 MacPorts 安装 Qt5：

**Homebrew:**
```bash
# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Qt5
brew install qt@5

# 安装 CMake（如果尚未安装）
brew install cmake

# 可选：安装 FreeType（用于文字渲染）
brew install freetype
```

**MacPorts:**
```bash
sudo port install qt5
sudo port install cmake
sudo port install freetype
```

**Vulkan SDK（可选，用于 Vulkan 渲染）:**
```bash
# 从 LunarG 下载并安装
# https://vulkan.lunarg.com/sdk/home

# 或者下载到 ~/VulkanSDK/
# 安装后设置环境变量
export VULKAN_SDK=~/VulkanSDK/1.4.328.1/macOS
export DYLD_LIBRARY_PATH=$VULKAN_SDK/lib:$DYLD_LIBRARY_PATH
export VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json
```

#### 2. 编译项目

```bash
# 赋予脚本执行权限
chmod +x build_mac.sh run_mac.sh

# 编译
./build_mac.sh
```

脚本会自动搜索 Qt 和 Vulkan SDK 安装路径。

### Linux 平台

#### 1. 安装依赖

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install qt5-default qtbase5-dev libqt5dbus5 \
                     libx11-dev cmake g++

# 可选：Vulkan 开发库
sudo apt-get install vulkan-tools libvulkan-dev

# 可选：FreeType 开发库
sudo apt-get install libfreetype6-dev

# Fedora
sudo dnf install qt5-qtbase-devel qt5-qtbase-gui \
                 libX11-devel cmake gcc-c++

# 可选：Vulkan 和 FreeType
sudo dnf install vulkan-tools vulkan-headers freetype-devel
```

#### 2. 编译项目

```bash
# 赋予脚本执行权限
chmod +x build.sh run.sh

# 编译
./build.sh
```

编译成功后，可执行文件将生成在 `build/bin/ScreenLockDetector`

## 运行应用

### macOS 平台

```bash
# 使用运行脚本（推荐，自动设置环境变量）
./run_mac.sh

# 或直接运行
./build/bin/ScreenLockDetector
```

### Linux 平台

```bash
# 使用运行脚本（推荐）
./run.sh

# 或直接运行
./build/bin/ScreenLockDetector
```

## 使用说明

1. **启动应用**：运行应用后，会看到一个带有动态动画的窗口
   - 如果 Vulkan 可用，默认使用 Vulkan 渲染器
   - 否则回退到 QPainter 渲染器

2. **查看渲染器类型**：
   - 窗口标题显示当前使用的渲染器（Vulkan 或 QPainter）
   - Vulkan 渲染器提供更好的性能和效果

3. **测试锁屏检测**：
   - **macOS**: 使用快捷键 `Ctrl + Cmd + Q` 或从菜单栏选择"锁定屏幕"
   - **Linux**: 使用快捷键 `Ctrl + Alt + L` 或 `Super + L`
   - 观察动画是否停止
   - 解锁后动画应自动恢复

4. **测试电源监控**：
   - 合上笔记本屏幕或选择"睡眠"
   - 观察控制台输出睡眠/唤醒消息
   - 唤醒后渲染会自动恢复

5. **查看状态信息**：
   - **Renderer Type**：当前使用的渲染器类型
   - **Detector Status**：锁屏检测器是否正常工作
   - **Screen Lock Status**：当前屏幕锁定状态（🔒 LOCKED / 🔓 UNLOCKED）
   - **Rendering Status**：渲染是否启用（✓ ENABLED / ✗ DISABLED）
   - **Frame Count**：已渲染的总帧数
   - **FPS**：当前帧率（仅 Vulkan）

6. **手动控制**（可选）：
   - **Enable Rendering**：手动启用渲染
   - **Disable Rendering**：手动禁用渲染
   - **Reset Frame Count**：重置帧数计数器

## 工作原理

### 锁屏检测机制

#### Linux: DBus 监听

应用程序通过 Qt DBus 连接到 Linux 系统的锁屏服务：

1. **Deepin DDE 接口**（Deepin OS）
   ```
   Service: com.deepin.dde.lockFront
   Path: /com/deepin/dde/lockFront
   Interface: com.deepin.dde.lockFront
   Signals: Visible(bool)
   ```

2. **GNOME ScreenSaver 接口**
   ```
   Service: org.gnome.ScreenSaver
   Path: /org/gnome/ScreenSaver
   Interface: org.gnome.ScreenSaver
   Signal: ActiveChanged(bool)
   ```

3. **KylinOS UKUI 接口**
   ```
   Service: org.ukui.ScreenSaver
   Path: /
   Interface: org.ukui.ScreenSaver
   Signals: lock(), unlock()
   ```

#### macOS: 分布式通知中心

应用程序通过 NSDistributedNotificationCenter 监听 macOS 系统通知：

1. **屏幕锁定通知**
   ```
   Notification: com.apple.screenIsLocked
   当用户锁定屏幕时发送
   ```

2. **屏幕解锁通知**
   ```
   Notification: com.apple.screenIsUnlocked
   当用户解锁屏幕时发送
   ```

3. **屏幕保护程序通知**（辅助检测）
   ```
   Notifications:
   - com.apple.screensaver.didstart
   - com.apple.screensaver.didstop
   ```

### 电源监控机制

#### Linux: DBus login1 服务

```
Service: org.freedesktop.login1
Path: /org/freedesktop/login1
Interface: org.freedesktop.login1.Manager
Signal: PrepareForSleep(bool entering_sleep)
```

#### macOS: NSWorkspace 通知

```
NSWorkspaceWillSleepNotification - 系统即将睡眠
NSWorkspaceDidWakeNotification - 系统已经唤醒
```

### Vulkan 渲染流程

1. **初始化**：
   - 使用 volk 动态加载 Vulkan 函数
   - 创建 Vulkan 实例（macOS 需要 portability 扩展）
   - 选择物理设备（GPU）
   - 创建逻辑设备和队列
   - **macOS**: 创建 CAMetalLayer 用于 MoltenVK 渲染

2. **渲染管线**：
   - 创建 swap chain（交换链）
   - 创建 render pass（渲染通道）
   - 加载 SPIR-V 着色器
   - 创建图形管线（背景、几何、线条、文字）
   - 设置 MSAA 多重采样

3. **每帧渲染**：
   - 获取 swap chain 图像
   - 记录命令缓冲
   - 绘制背景、几何和文字
   - 提交到 GPU 队列
   - 呈现到屏幕

### 渲染控制

当检测到锁屏或睡眠时：
1. 相应的检测器发出信号
2. `MainWindow` 接收信号并调用渲染器的 `setRenderingEnabled(false)`
3. 渲染器停止渲染定时器
4. GPU 进入空闲状态，节省资源

当检测到解锁或唤醒时：
1. 相应的检测器发出信号
2. `MainWindow` 调用 `setRenderingEnabled(true)`
3. 渲染器重启渲染定时器
4. 动画恢复正常渲染

## 平台特定架构

### 设计模式

项目采用 **工厂模式 + 策略模式** 实现跨平台支持：

1. **抽象基类** (`*_base.h/cpp`)
   - 定义统一接口
   - 实现公共功能

2. **平台实现** (`*_linux.h/cpp`, `*_macos.h/mm`)
   - 继承基类
   - 实现平台特定 API

3. **工厂类** (`screenlockdetector.h/cpp`, `powermonitor.h/cpp`)
   - 根据编译平台自动选择实现
   - 提供统一的公共 API

详见：`src/platform/README.md`

## 故障排除

### macOS 平台

#### 问题 1：Vulkan 实例创建失败

**错误信息**：`Failed to create Vulkan instance, error code: -9`

**原因**：MoltenVK 未正确安装或配置

**解决方案**：
```bash
# 确保 Vulkan SDK 已安装
ls ~/VulkanSDK/1.4.328.1/macOS/lib/libMoltenVK.dylib

# 设置环境变量
export VULKAN_SDK=~/VulkanSDK/1.4.328.1/macOS
export DYLD_LIBRARY_PATH=$VULKAN_SDK/lib:$DYLD_LIBRARY_PATH
export VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json

# 使用 run_mac.sh 脚本运行（已包含配置）
./run_mac.sh
```

#### 问题 2：CAMetalLayer 错误

**错误信息**：`VK_ERROR_SURFACE_LOST_KHR: On-screen rendering requires a layer of type CAMetalLayer`

**原因**：已在新版本中修复，确保使用最新代码

**解决方案**：重新编译项目

#### 问题 3：应用无法检测到锁屏

**解决方案**：
```bash
# 查看应用日志
./run_mac.sh 2>&1 | grep "ScreenLock"

# 确保应用有必要的权限
# 系统偏好设置 > 安全性与隐私 > 隐私
```

### Linux 平台

#### 问题 1：Vulkan 不可用

**错误信息**：`Vulkan headers not found`

**解决方案**：
```bash
# 安装 Vulkan 开发库
sudo apt-get install vulkan-tools libvulkan-dev

# 或手动下载 Vulkan Headers
git clone https://github.com/KhronosGroup/Vulkan-Headers.git
# 更新 CMakeLists.txt 中的 VULKAN_HEADERS_DIR
```

#### 问题 2：锁屏检测不工作

**解决方案**：
```bash
# 检查 DBus 服务
ps aux | grep dbus

# 检查 GNOME ScreenSaver 是否可用
qdbus org.gnome.ScreenSaver

# 查看应用日志输出
./run.sh 2>&1 | grep "ScreenLockDetector"
```

### 通用问题

#### 问题：编译错误 - Qt5 not found

**解决方案**：
```bash
# 设置 Qt5_DIR 环境变量
export Qt5_DIR=/path/to/qt/lib/cmake/Qt5

# 或修改 CMakeLists.txt 中的 Qt5_DIR 路径
```

## 性能优化

### Vulkan 渲染器

- **MSAA**：自动选择最佳采样数（最高 8x）
- **三缓冲**：使用 3 个并行帧减少延迟
- **动态加载**：使用 volk 避免链接 Vulkan 库
- **命令缓冲复用**：减少 CPU 开销

### 资源节省

- 锁屏时自动停止渲染（节省 GPU 资源）
- 睡眠时自动停止所有活动（节省电池）
- 最小化时暂停渲染（可选）

## 扩展开发

### 添加新的平台特性

详见：`src/platform/README.md`

### 自定义着色器

编辑 `shaders/` 目录中的 GLSL 文件，然后重新编译：

```bash
./compile_shaders.sh
./build_mac.sh  # 或 ./build.sh
```

### 添加新的渲染效果

在 `VulkanRenderer` 或 `CustomWidget` 中添加自定义绘制代码。

## 许可证

本项目仅用于学习和演示目的。

## 作者

Qt Screen Lock Detection Demo Team

## 更新日志

### v3.0.0 (2025-11-11)
- ✅ **重大更新**: 新增 Vulkan 渲染支持
- ✅ **重大更新**: 新增电源监控功能（睡眠/唤醒检测）
- ✅ macOS: 完整的 MoltenVK 支持（包含 CAMetalLayer）
- ✅ 双渲染引擎：Vulkan + QPainter
- ✅ MSAA 抗锯齿支持
- ✅ FreeType 字体渲染集成
- ✅ 重构项目结构：创建 `platform/` 目录统一管理平台代码
- ✅ 改进的跨平台架构（Factory + Strategy 模式）
- ✅ 完善的文档和故障排除指南

### v2.0.0 (2025)
- ✅ 新增 macOS 平台支持
- ✅ 实现跨平台架构（Linux + macOS）
- ✅ macOS: 使用 NSDistributedNotificationCenter 监听系统通知
- ✅ 创建平台特定的构建和运行脚本

### v1.1.0 (2025)
- ✅ 新增 Deepin OS (DDE) 锁屏检测支持
- ✅ 优化多桌面环境兼容性

### v1.0.0 (2025)
- ✅ 初始版本发布
- ✅ 支持 GNOME 和 systemd-logind 锁屏检测
- ✅ 实现自动渲染控制
- ✅ 提供丰富的动画演示效果

## 技术支持

如有问题或建议，欢迎提出！

### 相关文档

- [平台代码组织说明](src/platform/README.md)
- [Vulkan 渲染架构](docs/)
- [CMake 构建配置](CMakeLists.txt)

### 相关链接

- [Qt Documentation](https://doc.qt.io/qt-5/)
- [Vulkan SDK](https://vulkan.lunarg.com/sdk/home)
- [MoltenVK (macOS)](https://github.com/KhronosGroup/MoltenVK)
- [volk - Vulkan Meta-Loader](https://github.com/zeux/volk)