项目规划2：配置与调试模块技术规划与实现构思

zzy789999

2377人浏览 · 2026-04-11 15:47:54

zzy789999 · 2026-04-11 15:47:54 发布

前言

在本次 Vulkan 图形注入中间件项目中，我们的目标是逐步复现类似 OptiScaler 的超分代理能力，当前已经完成了 Proxy DLL 注入框架、Present 前图像注入链路，以及最小化的日志调试模块，顺利推进到阶段 2 的缩放效果验证。

Config & Debug 模块是整个项目的基础底座，看似没有超分算法、帧生成这些核心功能亮眼，却直接决定了项目的稳定性、兼容性与易用性。本文基于当前 MVP 阶段的实现基础，梳理后续配置与调试模块的完整规划，确保模块与项目整体架构深度适配，不做过度设计。

一、模块定位与需求背景

1.1 模块核心定位

Config & Debug 模块在项目中承担两大核心职责：

配置中枢：为超分算法、Hook 注入、兼容性适配等所有上层模块，提供统一、可靠的配置持久化与读取能力，是整个项目所有功能参数的统一入口。
调试窗口：为开发与测试提供实时的状态反馈、错误提示与性能信息，快速定位兼容问题、Hook 异常、渲染故障，降低问题排查门槛。

1.2 需求来源

当前 MVP 阶段已经验证了注入链路的可行性，但随着项目从 “阶段 1 清屏验证” 向 “阶段 2 缩放效果” 推进，现有调试能力已经不足以支撑开发：

日志输出全靠硬编码，调整输出粒度必须重新编译；
注入开关、缩放倍率、回退策略等参数没有配置入口，不同场景测试需要反复修改代码；
运行状态只能靠日志事后排查，没有实时可视化的调试信息。

因此我们计划在阶段 2 稳定后，逐步落地完整的 Config & Debug 模块，先从最小可用的 ini 配置开始，再逐步扩展调试面板能力。

二、核心需求拆解

2.1 配置模块（Config）核心需求

基础读写能力：基于原生 C++ 标准文件 I/O 实现 .ini 配置文件的读取、解析、写入与持久化，支持标准的 [Section] 节、Key=Value 键值对、行注释格式，全程无第三方库依赖。
配置项规划：贴合项目分阶段演进的节奏，先落地核心配置域，后续逐步扩展：

表格

配置节	核心用途	对应项目功能
General	全局基础配置	注入总开关、缩放倍率、回退策略控制
Debug	调试与日志配置	日志开关、日志等级、采样率、调试面板开关
Compatibility	兼容适配配置	Transfer usage 兼容处理、多队列兼容开关

兼容与容错：支持配置文件缺失时自动生成默认配置、无效配置项自动兜底，任何配置异常都不影响程序正常运行。
线程安全：提供线程安全的配置读写接口，支持多模块并发读取，运行时热重载配置不触发崩溃。

2.2 调试模块（Debug）核心需求

基础信息可视化：运行时实时展示项目核心状态，无需退出程序即可查看关键信息。
双实现方案：先落地极简文本渲染方案（零额外依赖），渲染链路稳定后再扩展 ImGui UI 方案。
核心展示内容：覆盖开发与测试最关注的核心信息：
- 基础信息：Swapchain 分辨率、当前图像格式、注入阶段
- 运行状态：Hook 注入结果、中间纹理创建状态、资源跟踪是否正常
- 性能数据：实时帧率、注入命令提交耗时
性能保障：调试能力默认关闭，仅在主动开启时执行渲染，无任何隐性性能开销。

三、技术选型与设计原则

3.1 核心技术选型

表格

功能模块	技术方案	选型思考
配置文件读写	原生 C++ 标准文件 I/O	1. 无第三方库依赖，避免引入兼容风险；2. 轻量高效，仅在启动 / 热重载时执行 IO 操作；3. 完全可控，可自定义解析规则适配项目特殊需求
调试 UI 界面	先文本渲染，后集成 ImGui	1. 极简方案零依赖，适配 MVP 阶段快速验证；2. 项目后续扩展 Overlay 层可基于 ImGui 实现，能力可直接复用
数据存储	`std::map` 嵌套结构	以 `std::map<节名, std::map<键名, 值>>` 的结构缓存配置数据，读写效率高，查找便捷，内存占用可控

3.2 核心设计原则

零侵入原则：模块不侵入上层业务逻辑，仅提供接口与数据，不修改其他模块的运行状态，避免引发渲染同步问题。
兜底优先原则：任何配置异常、文件损坏、解析失败场景，都有默认值兜底，绝对不会因为配置模块问题导致程序崩溃或注入失败。
贴合项目原则：所有功能完全贴合现有 Vulkan Proxy 架构，不做过度设计，跟随项目阶段逐步迭代。
分层演进原则：先做配置读写，再做调试文本，最后做 ImGui 面板，每一步都可独立验证，不阻塞核心渲染链路开发。

四、整体架构设计

模块采用分层架构设计，从上到下分为 4 层，层与层之间职责清晰、接口隔离，便于后续维护与扩展：

plaintext

┌─────────────────────────────────────────────────────────┐
│  对外接口层 （ConfigAPI / DebugAPI）                    │
│  给上层模块提供统一的读写、渲染接口，屏蔽内部实现细节   │
├─────────────────────────────────────────────────────────┤
│  核心业务层                                              │
│  ├──────────────────┬──────────────────────────────────┤ │
│  │ 配置核心子模块  │ 调试UI子模块                      │ │
│  │ 1. 文件读写     │ 1. 状态数据收集                  │ │
│  │ 2. 解析与序列化 │ 2. 文本/ImGui渲染                │ │
│  │ 3. 缓存管理     │ 3. 交互逻辑处理                  │ │
│  │ 4. 热重载逻辑   │ 4. 布局持久化                    │ │
│  └──────────────────┴──────────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│  平台适配层                                              │
│  Windows文件/路径适配 | 线程安全适配                     │
│  Vulkan渲染API适配                                      │
├─────────────────────────────────────────────────────────┤
│  基础依赖层                                              │
│  C/C++标准库 | 原生文件I/O | 现有Vulkan注入链路能力     │
└─────────────────────────────────────────────────────────┘

模块间联动设计

与 Hook 注入模块联动：配置模块提供注入开关、回退策略等参数，调试模块实时展示 Hook 注入结果与当前注入阶段。
与资源管理模块联动：配置模块控制中间纹理的创建策略、缩放倍率参数，调试模块展示资源创建状态。
与日志系统联动：统一管理日志开关、等级、输出采样率，对应当前已实现的日志系统做平滑扩展。

五、核心功能详细实现构思

5.1 INI 配置模块核心实现

5.1.1 配置文件格式规范

基于标准 ini 格式，适配当前项目需求制定统一规范，示例配置文件片段如下：

ini

# Vulkan Proxy 主配置文件
# 配置项修改后重启生效，支持运行时热重载

[General]
# 注入总开关 0=关闭 1=开启
EnableInjection=1
# 缩放倍率 0.5=下采样一半
ScaleFactor=0.5
# 不满足条件时自动回退到清屏模式
EnableFallback=1

[Debug]
# 日志等级 0=关闭 1=错误 2=警告 3=信息 4=调试
LogLevel=3
# 日志采样帧率（每N帧输出一次帧日志）
LogSampleRate=120
# 启用性能统计
EnablePerformanceStats=0

5.1.2 核心解析流程

启动初始化流程：启动时先校验配置文件是否存在，不存在则生成默认配置；存在则逐行解析，区分节、键值对、注释行，解析完成后存入缓存，同时校验必填配置项，缺失项自动填充默认值。
核心读写接口设计：采用单例模式设计 Config 类，提供线程安全的类型化读写接口，核心接口设计如下：

cpp

运行

class ConfigManager {
public:
    // 单例获取
    static ConfigManager& GetInstance();

    // 初始化与释放
    bool Init(const std::string& configPath);
    void Shutdown();

    // 类型化读取接口,带默认值兜底
    int GetInt(const std::string& section, const std::string& key, int defaultValue = 0);
    float GetFloat(const std::string& section, const std::string& key, float defaultValue = 0.0f);
    bool GetBool(const std::string& section, const std::string& key, bool defaultValue = false);
    std::string GetString(const std::string& section, const std::string& key, const std::string& defaultValue = "");

    // 写入接口
    bool SetInt(const std::string& section, const std::string& key, int value);
    bool SetFloat(const std::string& section, const std::string& key, float value);
    bool SetBool(const std::string& section, const std::string& key, bool value);
    bool SetString(const std::string& section, const std::string& key, const std::string& value);

    // 热重载与持久化
    bool Reload();
    bool SaveToFile();

private:
    // 私有构造,禁止外部实例化
    ConfigManager() = default;
    ~ConfigManager() = default;

    // 核心缓存结构
    std::map<std::string, std::map<std::string, std::string>> m_configCache;
    // 线程锁
    std::mutex m_mutex;
    // 配置文件路径
    std::string m_configPath;
    // 默认配置表
    void LoadDefaultConfig();
};

5.2 调试信息展示模块核心实现

5.2.1 方案一：极简文本渲染方案（优先落地）

适用于当前 MVP 阶段，基于 Vulkan 现有渲染管线实现固定位置的文本渲染，无任何额外依赖。

实现逻辑：复用注入命令的渲染通道，在清屏或缩放后叠加文本渲染，每帧更新一次核心数据；
核心特性：默认关闭，通过配置项开启，渲染开销极低，仅展示核心文本信息；
展示内容示例：

plaintext

Vulkan Proxy v0.1
Swapchain: 1920x1080
注入阶段: 缩放模式
FPS: 144 | 注入耗时: 0.2ms

5.2.2 方案二：ImGui 进阶 UI 方案（后续扩展）

待项目渲染链路完全稳定后，基于 ImGui 实现可交互的调试面板，支持更丰富的信息展示与参数调整。

面板可展示完整的运行状态、性能数据、警告错误信息；
支持实时修改配置参数，无需重启程序生效；
面板位置、大小自动持久化到配置文件。

六、开发里程碑与落地规划

结合项目的迭代节奏，把模块开发分为 4 个阶段，稳步落地：

表格

阶段	周期	核心产出	验收标准
第一阶段：日志系统优化	2 个工作日	1. 新增日志等级控制；2. 新增日志采样策略；3. 错误日志高亮	日志输出可控，高频日志不影响性能
第二阶段：配置模块核心开发	3 个工作日	1. 单例 ConfigManager 类框架搭建；2. INI 解析与序列化实现；3. 默认配置生成与兜底逻辑	所有接口可正常调用，配置读写正常，异常场景不崩溃
第三阶段：调试文本实现	3 个工作日	1. 极简文本渲染方案实现；2. 状态数据收集与展示；3. 配置项控制开关	调试信息可正常显示，开启后无明显性能损耗
第四阶段：联调与优化	2 个工作日	1. 与现有注入模块联调；2. 异常场景测试；3. 性能优化	与现有渲染链路无冲突，所有配置项生效