hoenking
/
ScreenLockDetector
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README

This commit is contained in:
hoenking 2025-11-11 20:52:14 +08:00
parent 61920ac49d
commit c5de82f0fb
1 changed files with 356 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

560
README.md
View File

@ -1,6 +1,6 @@
# Qt Screen Lock Detection Demo # Qt Screen Lock Detection Demo
一个基于 Qt5 + CMake 的跨平台应用程序，用于检测系统的锁屏状态，并在锁屏时自动停止所有 Paint 事件。 一个基于 Qt5 + CMake 的跨平台应用程序，用于检测系统的锁屏状态和电源状态（睡眠/唤醒），并在锁屏时自动停止所有渲染。
**支持平台：** **支持平台：**
- ✅ **Linux** (Ubuntu, Deepin, Fedora 等) - ✅ **Linux** (Ubuntu, Deepin, Fedora 等)
@ -8,35 +8,76 @@
## 功能特性 ## 功能特性
- ✅ **自动检测锁屏/休眠/睡眠状态**： ### 核心功能
- ✅ **自动检测锁屏状态**：
- Linux: 通过 DBus 监听系统的锁屏/解锁事件 - Linux: 通过 DBus 监听系统的锁屏/解锁事件
- macOS: 通过 NSDistributedNotificationCenter 监听系统通知 - macOS: 通过 NSDistributedNotificationCenter 监听系统通知
- ✅ **自动停止绘制**：屏幕锁定时自动停止所有 Paint 事件，节省系统资源
- ✅ **实时动画演示**：持续的动画效果，直观展示绘制的启用/禁用状态 - ✅ **电源状态监控**：
- ✅ **手动控制**：提供手动启用/禁用绘制的按钮 - 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 等主流桌面环境 - Linux: 支持 GNOME、KDE、XFCE、Deepin DDE、UKUI 等主流桌面环境
- macOS: 原生系统通知支持 - macOS: 原生系统通知支持，MoltenVK 集成
## 技术架构 ## 技术架构
### 核心组件 ### 核心组件
1. **ScreenLockDetector** - 跨平台锁屏检测器 1. **ScreenLockDetector** - 跨平台锁屏检测器
- **Linux**: 通过 Qt DBus 监听系统锁屏信号 - **基础架构**: `ScreenLockDetectorBase` 抽象基类
- **Linux**: `ScreenLockDetectorLinux` - 通过 Qt DBus 监听系统锁屏信号
- 支持 GNOME ScreenSaver、systemd-logind 和 Deepin DDE 接口 - 支持 GNOME ScreenSaver、systemd-logind 和 Deepin DDE 接口
- **macOS**: 通过 NSDistributedNotificationCenter 监听系统通知 - **macOS**: `ScreenLockDetectorMacOS` - 通过 NSDistributedNotificationCenter 监听系统通知
- 监听 com.apple.screenIsLocked/Unlocked 通知 - 监听 com.apple.screenIsLocked/Unlocked 通知
- 发出锁屏/解锁信号供其他组件订阅 - 发出锁屏/解锁信号供其他组件订阅
2. **CustomWidget** - 自定义绘制组件 2. **PowerMonitor** - 跨平台电源监视器
- 实现了动态动画效果（旋转圆圈、波浪效果等） - **基础架构**: `PowerMonitorBase` 抽象基类
- 60 FPS 刷新率 - **Linux**: `PowerMonitorLinux` - 通过 DBus login1 服务监听
- 可控制的绘制启用/禁用状态 - 监听 org.freedesktop.login1.Manager 的 PrepareForSleep 信号
- 帧数统计功能 - **macOS**: `PowerMonitorMacOS` - 通过 NSWorkspace 监听
- 监听 NSWorkspaceWillSleepNotification 和 NSWorkspaceDidWakeNotification
- 发出睡眠/唤醒信号
3. **MainWindow** - 主窗口 3. **RenderWidgetBase** - 渲染组件抽象接口
- 定义统一的渲染器接口
- 支持动态切换不同渲染后端
4. **VulkanWidget** - Vulkan 渲染组件
- 使用 volk 动态加载 Vulkan 函数
- 支持 MSAA 多重采样抗锯齿
- 集成 FreeType 字体渲染
- **macOS**: 专门的 CAMetalLayer 支持（MoltenVK）
- 自动处理窗口大小调整和设备丢失恢复
5. **CustomWidget** - QPainter 渲染组件
- 传统 Qt 绘制实现
- 作为 Vulkan 不可用时的备选方案
- 实现了相同的动画效果
6. **MainWindow** - 主窗口
- 整合各个组件 - 整合各个组件
- 提供用户界面和控制面板 - 提供用户界面和控制面板
- 实时状态显示 - 实时状态显示
@ -46,10 +87,49 @@
- **语言**：C++11 / Objective-C++ (macOS) - **语言**：C++11 / Objective-C++ (macOS)
- **GUI 框架**：Qt 5.15.2 (或更高版本) - **GUI 框架**：Qt 5.15.2 (或更高版本)
- **构建系统**：CMake 3.10+ - **构建系统**：CMake 3.10+
- **图形 API**：
- Vulkan 1.0+ (通过 volk 动态加载)
- MoltenVK (macOS)
- QPainter (备选方案)
- **字体渲染**：FreeType 2.x
- **系统接口**： - **系统接口**：
- Linux: Qt DBus - Linux: Qt DBus, X11
- macOS: Foundation Framework (NSDistributedNotificationCenter) - macOS: Foundation Framework, AppKit, QuartzCore (CAMetalLayer)
- **平台**：Linux Ubuntu / macOS 10.12+ - **平台**：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 辅助
```
## 系统要求 ## 系统要求
@ -59,13 +139,18 @@
- CMake 3.10 或更高版本 - CMake 3.10 或更高版本
- GCC/G++ 编译器（支持 C++11） - GCC/G++ 编译器（支持 C++11）
- DBus 系统服务 - DBus 系统服务
- X11 开发库
- **可选**：Vulkan SDK 1.0+ (用于 Vulkan 渲染)
- **可选**：FreeType 开发库 (用于 Vulkan 文字渲染)
### macOS ### macOS
- macOS 10.12 (Sierra) 或更高版本 - macOS 10.12 (Sierra) 或更高版本
- Qt 5.15.2 或更高版本（可通过 Homebrew 安装） - Qt 5.15.2 或更高版本（可通过 Homebrew 或 MacPorts 安装）
- CMake 3.10 或更高版本 - CMake 3.10 或更高版本
- Xcode Command Line Tools - Xcode Command Line Tools
- Foundation 和 Cocoa 框架（系统自带） - Foundation 和 Cocoa 框架（系统自带）
- **可选**：Vulkan SDK 1.4+ (包含 MoltenVK，用于 Vulkan 渲染)
- **可选**：FreeType 库 (用于 Vulkan 文字渲染)
## 安装与编译 ## 安装与编译
@ -73,8 +158,9 @@
#### 1. 安装依赖 #### 1. 安装依赖
使用 Homebrew 安装 Qt5： 使用 Homebrew 或 MacPorts 安装 Qt5：
**Homebrew:**
```bash ```bash
# 安装 Homebrew（如果尚未安装） # 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
@ -84,9 +170,29 @@ brew install qt@5
# 安装 CMake（如果尚未安装） # 安装 CMake（如果尚未安装）
brew install cmake brew install cmake
# 可选：安装 FreeType（用于文字渲染）
brew install freetype
``` ```
或者从 Qt 官网下载安装器：https://www.qt.io/download **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. 编译项目 #### 2. 编译项目
@ -98,39 +204,39 @@ chmod +x build_mac.sh run_mac.sh
./build_mac.sh ./build_mac.sh
``` ```
脚本会自动搜索 Qt 安装路径。如果需要手动指定，可以设置环境变量： 脚本会自动搜索 Qt 和 Vulkan SDK 安装路径。
```bash
export Qt5_DIR=/path/to/qt/lib/cmake/Qt5
./build_mac.sh
```
### Linux 平台 ### Linux 平台
#### 1. 确保 Qt5 已安装 #### 1. 安装依赖
```bash ```bash
# Ubuntu/Debian # Ubuntu/Debian
sudo apt-get install qt5-default qtbase5-dev libqt5dbus5 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 # Fedora
sudo dnf install qt5-qtbase-devel qt5-qtbase-gui sudo dnf install qt5-qtbase-devel qt5-qtbase-gui \
libX11-devel cmake gcc-c++
# 或使用自定义安装的 Qt # 可选：Vulkan 和 FreeType
ls $HOME/sdk/qt-5.15.2 sudo dnf install vulkan-tools vulkan-headers freetype-devel
``` ```
如果 Qt5 安装在其他位置，请修改 `CMakeLists.txt` 中的 Qt5_DIR 路径或设置环境变量。 #### 2. 编译项目
#### 2. 赋予脚本执行权限
```bash ```bash
# 赋予脚本执行权限
chmod +x build.sh run.sh chmod +x build.sh run.sh
```
#### 3. 编译项目 # 编译
```bash
./build.sh ./build.sh
``` ```
@ -140,71 +246,63 @@ chmod +x build.sh run.sh
### macOS 平台 ### macOS 平台
#### 方法 1：使用运行脚本（推荐）
```bash ```bash
# 使用运行脚本（推荐，自动设置环境变量）
./run_mac.sh ./run_mac.sh
```
#### 方法 2：直接运行可执行文件 # 或直接运行
```bash
./build/bin/ScreenLockDetector
```
#### 方法 3：手动设置环境变量并运行
```bash
export DYLD_LIBRARY_PATH=/path/to/qt/lib:$DYLD_LIBRARY_PATH
./build/bin/ScreenLockDetector ./build/bin/ScreenLockDetector
``` ```
### Linux 平台 ### Linux 平台
#### 方法 1：使用运行脚本（推荐）
```bash ```bash
# 使用运行脚本（推荐）
./run.sh ./run.sh
```
#### 方法 2：直接运行可执行文件 # 或直接运行
```bash
cd build/bin
./ScreenLockDetector
```
#### 方法 3：手动设置环境变量并运行
```bash
export LD_LIBRARY_PATH=$HOME/sdk/qt-5.15.2/lib:$LD_LIBRARY_PATH
./build/bin/ScreenLockDetector ./build/bin/ScreenLockDetector
``` ```
## 使用说明 ## 使用说明
1. **启动应用**：运行应用后，会看到一个带有动态动画的窗口 1. **启动应用**：运行应用后，会看到一个带有动态动画的窗口
- 如果 Vulkan 可用，默认使用 Vulkan 渲染器
- 否则回退到 QPainter 渲染器
2. **测试锁屏检测**： 2. **查看渲染器类型**：
- 窗口标题显示当前使用的渲染器（Vulkan 或 QPainter）
- Vulkan 渲染器提供更好的性能和效果
3. **测试锁屏检测**：
- **macOS**: 使用快捷键 `Ctrl + Cmd + Q` 或从菜单栏选择"锁定屏幕" - **macOS**: 使用快捷键 `Ctrl + Cmd + Q` 或从菜单栏选择"锁定屏幕"
- **Linux**: 使用快捷键 `Ctrl + Alt + L` 或 `Super + L` - **Linux**: 使用快捷键 `Ctrl + Alt + L` 或 `Super + L`
- 观察动画是否停止 - 观察动画是否停止
- 解锁后动画应自动恢复 - 解锁后动画应自动恢复
3. **查看状态信息**： 4. **测试电源监控**：
- **Detector Status**：检测器是否正常工作 - 合上笔记本屏幕或选择"睡眠"
- **Screen Lock Status**：当前屏幕锁定状态（🔒 LOCKED / 🔓 UNLOCKED） - 观察控制台输出睡眠/唤醒消息
- **Painting Status**：绘制是否启用（✓ ENABLED / ✗ DISABLED） - 唤醒后渲染会自动恢复
- **Frame Count**：已绘制的总帧数
4. **手动控制**（可选）： 5. **查看状态信息**：
- **Enable Painting**：手动启用绘制 - **Renderer Type**：当前使用的渲染器类型
- **Disable Painting**：手动禁用绘制 - **Detector Status**：锁屏检测器是否正常工作
- **Screen Lock Status**：当前屏幕锁定状态（🔒 LOCKED / 🔓 UNLOCKED）
- **Rendering Status**：渲染是否启用（✓ ENABLED / ✗ DISABLED）
- **Frame Count**：已渲染的总帧数
- **FPS**：当前帧率（仅 Vulkan）
6. **手动控制**（可选）：
- **Enable Rendering**：手动启用渲染
- **Disable Rendering**：手动禁用渲染
- **Reset Frame Count**：重置帧数计数器 - **Reset Frame Count**：重置帧数计数器
## 工作原理 ## 工作原理
### Linux: DBus 监听机制 ### 锁屏检测机制
#### Linux: DBus 监听
应用程序通过 Qt DBus 连接到 Linux 系统的锁屏服务： 应用程序通过 Qt DBus 连接到 Linux 系统的锁屏服务：
@ -224,7 +322,7 @@ export LD_LIBRARY_PATH=$HOME/sdk/qt-5.15.2/lib:$LD_LIBRARY_PATH
Signal: ActiveChanged(bool) Signal: ActiveChanged(bool)
``` ```
3. **KylinOS UKUI接口** 3. **KylinOS UKUI 接口**
``` ```
Service: org.ukui.ScreenSaver Service: org.ukui.ScreenSaver
Path: / Path: /
@ -232,7 +330,7 @@ export LD_LIBRARY_PATH=$HOME/sdk/qt-5.15.2/lib:$LD_LIBRARY_PATH
Signals: lock(), unlock() Signals: lock(), unlock()
``` ```
### macOS: 分布式通知中心 #### macOS: 分布式通知中心
应用程序通过 NSDistributedNotificationCenter 监听 macOS 系统通知： 应用程序通过 NSDistributedNotificationCenter 监听 macOS 系统通知：
@ -255,94 +353,141 @@ export LD_LIBRARY_PATH=$HOME/sdk/qt-5.15.2/lib:$LD_LIBRARY_PATH
- com.apple.screensaver.didstop - com.apple.screensaver.didstop
``` ```
### Paint 事件控制 ### 电源监控机制
当检测到锁屏时： #### Linux: DBus login1 服务
1. `ScreenLockDetector` 发出 `screenLocked()` 信号
2. `MainWindow` 接收信号并调用 `CustomWidget::setPaintingEnabled(false)`
3. `CustomWidget` 停止动画定时器
4. `paintEvent()` 检查启用状态，不再绘制动画内容
当检测到解锁时：
1. `ScreenLockDetector` 发出 `screenUnlocked()` 信号
2. `MainWindow` 调用 `CustomWidget::setPaintingEnabled(true)`
3. `CustomWidget` 重启动画定时器
4. 动画恢复正常绘制
## 项目结构
``` ```
ScreenLockDetector/ Service: org.freedesktop.login1
├── CMakeLists.txt # CMake 构建配置（跨平台） Path: /org/freedesktop/login1
├── README.md # 项目文档 Interface: org.freedesktop.login1.Manager
├── build.sh # Linux 编译脚本 Signal: PrepareForSleep(bool entering_sleep)
├── run.sh # Linux 运行脚本
├── build_mac.sh # macOS 编译脚本
├── run_mac.sh # macOS 运行脚本
└── src/
├── main.cpp # 程序入口
├── mainwindow.h # 主窗口头文件
├── mainwindow.cpp # 主窗口实现
├── screenlockdetector.h # 跨平台锁屏检测器头文件
├── screenlockdetector.cpp # 跨平台锁屏检测器实现
├── screenlockdetector_mac.h # macOS 特定实现头文件
├── screenlockdetector_mac.mm # macOS 特定实现（Objective-C++）
├── customwidget.h # 自定义组件头文件
└── customwidget.cpp # 自定义组件实现
``` ```
#### 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 平台 ### macOS 平台
#### 问题 1：应用无法检测到锁屏 #### 问题 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 ```bash
# 查看应用日志 # 查看应用日志
./run_mac.sh 2>&1 | grep "ScreenLock" ./run_mac.sh 2>&1 | grep "ScreenLock"
# 检查系统完整性保护（SIP）状态
csrutil status
# 确保应用有必要的权限 # 确保应用有必要的权限
``` # 系统偏好设置 > 安全性与隐私 > 隐私
#### 问题 2：编译错误 - Qt5 not found
**解决方案**：
```bash
# 使用 Homebrew 安装 Qt5
brew install qt@5
# 设置 Qt5_DIR 环境变量
export Qt5_DIR=$(brew --prefix qt@5)/lib/cmake/Qt5
./build_mac.sh
```
#### 问题 3：运行时找不到 Qt 库
**解决方案**：
```bash
# 设置 DYLD_LIBRARY_PATH
export DYLD_LIBRARY_PATH=$(brew --prefix qt@5)/lib:$DYLD_LIBRARY_PATH
# 或使用 run_mac.sh 脚本（已包含此配置）
./run_mac.sh
``` ```
### Linux 平台 ### Linux 平台
#### 问题 1：锁屏检测不工作 #### 问题 1：Vulkan 不可用
**可能原因**： **错误信息**：`Vulkan headers not found`
- DBus 服务未运行
- 桌面环境不支持标准 DBus 接口 **解决方案**：
- 权限不足 ```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 ```bash
@ -352,87 +497,82 @@ ps aux | grep dbus
# 检查 GNOME ScreenSaver 是否可用 # 检查 GNOME ScreenSaver 是否可用
qdbus org.gnome.ScreenSaver qdbus org.gnome.ScreenSaver
# 查看应用日志输出，确认连接状态 # 查看应用日志输出
```
### 问题 2：编译错误 - Qt5 not found
**解决方案**：
1. 确认 Qt5 安装路径：`ls $HOME/sdk/qt-5.15.2`
2. 修改 `CMakeLists.txt` 中的 Qt5_DIR 路径
3. 或设置环境变量：`export Qt5_DIR=$HOME/sdk/qt-5.15.2/lib/cmake/Qt5`
### 问题 3：运行时找不到 Qt 库
**解决方案**：
```bash
# 设置 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$HOME/sdk/qt-5.15.2/lib:$LD_LIBRARY_PATH
# 或使用 run.sh 脚本（已包含此配置）
./run.sh
```
### 问题 4：警告 - Failed to connect to screen lock detection service
**说明**：这是正常的，表示某些 DBus 接口在当前桌面环境中不可用。只要至少有一个接口连接成功，应用就能正常工作。
## 调试模式
应用程序会在控制台输出详细的调试信息：
```bash
# 运行并查看详细日志
./run.sh 2>&1 | tee app.log
# 查看特定类别的日志
./run.sh 2>&1 | grep "ScreenLockDetector" ./run.sh 2>&1 | grep "ScreenLockDetector"
``` ```
## 扩展与定制 ### 通用问题
### 添加更多动画效果 #### 问题：编译错误 - Qt5 not found
在 `customwidget.cpp` 中的 `drawBackground()`, `drawRotatingCircles()`, `drawWaveEffect()` 等方法中添加自定义绘制代码。 **解决方案**：
```bash
# 设置 Qt5_DIR 环境变量
export Qt5_DIR=/path/to/qt/lib/cmake/Qt5
### 支持其他桌面环境 # 或修改 CMakeLists.txt 中的 Qt5_DIR 路径
在 `screenlockdetector.cpp` 中添加更多 DBus 接口连接：
```cpp
bool ScreenLockDetector::connectToKDEScreenSaver()
{
// 添加 KDE Plasma 锁屏检测支持
// Service: org.kde.screensaver
// ...
}
``` ```
### 性能优化 ## 性能优化
调整动画刷新率（当前为 60 FPS）： ### Vulkan 渲染器
```cpp - **MSAA**：自动选择最佳采样数（最高 8x）
// 在 customwidget.cpp 构造函数中 - **三缓冲**：使用 3 个并行帧减少延迟
m_animationTimer->start(33); // 30 FPS (1000/30 ≈ 33ms) - **动态加载**：使用 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 Qt Screen Lock Detection Demo Team
## 更新日志 ## 更新日志
### v3.0.0 (2024-11-11)
- ✅ **重大更新**: 新增 Vulkan 渲染支持
- ✅ **重大更新**: 新增电源监控功能（睡眠/唤醒检测）
- ✅ macOS: 完整的 MoltenVK 支持（包含 CAMetalLayer）
- ✅ 双渲染引擎：Vulkan + QPainter
- ✅ MSAA 抗锯齿支持
- ✅ FreeType 字体渲染集成
- ✅ 重构项目结构：创建 `platform/` 目录统一管理平台代码
- ✅ 改进的跨平台架构（Factory + Strategy 模式）
- ✅ 完善的文档和故障排除指南
### v2.0.0 (2024) ### v2.0.0 (2024)
- ✅ **重大更新**: 新增 macOS 平台支持 - ✅ 新增 macOS 平台支持
- ✅ 实现跨平台架构（Linux + macOS） - ✅ 实现跨平台架构（Linux + macOS）
- ✅ macOS: 使用 NSDistributedNotificationCenter 监听系统通知 - ✅ macOS: 使用 NSDistributedNotificationCenter 监听系统通知
- ✅ 创建平台特定的构建和运行脚本 - ✅ 创建平台特定的构建和运行脚本
- ✅ 更新文档，包含 macOS 使用说明
### v1.1.0 (2024) ### v1.1.0 (2024)
- ✅ 新增 Deepin OS (DDE) 锁屏检测支持 - ✅ 新增 Deepin OS (DDE) 锁屏检测支持
@ -441,10 +581,22 @@ Qt Screen Lock Detection Demo
### v1.0.0 (2024) ### v1.0.0 (2024)
- ✅ 初始版本发布 - ✅ 初始版本发布
- ✅ 支持 GNOME 和 systemd-logind 锁屏检测 - ✅ 支持 GNOME 和 systemd-logind 锁屏检测
- ✅ 实现自动 Paint 事件控制 - ✅ 实现自动渲染控制
- ✅ 提供丰富的动画演示效果 - ✅ 提供丰富的动画演示效果
- ✅ 完整的状态监控和手动控制界面
## 反馈与贡献 ## 技术支持
如有问题或建议，欢迎提出！ 如有问题或建议，欢迎提出！
### 相关文档
- [平台代码组织说明](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)