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:

# 安装 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:

sudo port install qt5
sudo port install cmake
sudo port install freetype

Vulkan SDK（可选，用于 Vulkan 渲染）:

# 从 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. 编译项目

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

# 编译
./build_mac.sh

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

Linux 平台

1. 安装依赖

# 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. 编译项目

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

# 编译
./build.sh

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

运行应用

macOS 平台

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

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

Linux 平台

# 使用运行脚本（推荐）
./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 未正确安装或配置

解决方案：

# 确保 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：应用无法检测到锁屏

解决方案：

# 查看应用日志
./run_mac.sh 2>&1 | grep "ScreenLock"

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

Linux 平台

问题 1：Vulkan 不可用

错误信息：Vulkan headers not found

解决方案：

# 安装 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：锁屏检测不工作

解决方案：

# 检查 DBus 服务
ps aux | grep dbus

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

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

通用问题

问题：编译错误 - Qt5 not found

解决方案：

# 设置 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 文件，然后重新编译：

./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 锁屏检测
• ✅ 实现自动渲染控制
• ✅ 提供丰富的动画演示效果

技术支持

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

相关文档

• 平台代码组织说明
• Vulkan 渲染架构
• CMake 构建配置

相关链接

• Qt Documentation
• Vulkan SDK
• MoltenVK (macOS)
• volk - Vulkan Meta-Loader