Skip to content

README.md

Latest commit

 

History

History
464 lines (365 loc) · 10.4 KB

README.md

File metadata and controls

464 lines (365 loc) · 10.4 KB

🖼️ Native 运行容器 - Vulkan 渲染引擎

版本：v0.0.1
所属项目：Bit HCI
定位：BitUI 框架的原生运行容器和测试窗口

📋 项目概述

Native 模块是 Bit HCI 项目的原生测试窗口和运行容器，用于：

  • 提供跨平台窗口系统抽象（当前支持 Win32）
  • 实现 Vulkan 渲染管线
  • 作为 BitUI 框架的运行时验证环境
  • 测试和优化渲染性能

技术栈

技术 版本 用途
C++ C++20 核心实现语言
Vulkan 1.3 图形渲染 API
Win32 API - Windows 平台窗口管理
CMake 3.24+ 构建系统

🎯 当前状态

✅ 已完成功能（v0.0.1）

1. 窗口系统（Win32）

// src/platform/win32_window.h/cpp
✅ 窗口创建与管理
✅ 消息循环处理
✅ 窗口事件响应（关闭、调整大小）
✅ 基础窗口属性（800x600 默认尺寸）

特点：

  • 简洁的 Win32 封装
  • 无第三方依赖
  • 支持 Unicode（wmain）

2. Vulkan 基础设施

// src/vk/instance.h/cpp
✅ Vulkan 实例创建
✅ Win32 表面创建
✅ 物理设备选择
✅ 逻辑设备创建
✅ 队列族查询（图形 + 呈现）

实现细节：

  • API 版本：Vulkan 1.3
  • 启用扩展：VK_KHR_surface, VK_KHR_win32_surface, VK_KHR_swapchain
  • Debug 模式下启用验证层：VK_LAYER_KHRONOS_validation

3. 交换链系统

✅ 交换链创建和配置
✅ 格式选择（优先 B8G8R8A8_UNORM + SRGB_NONLINEAR）
✅ 呈现模式（优先 MAILBOX，回退 FIFO）
✅ 图像尺寸管理
✅ 多图像缓冲（minImageCount + 1）
✅ 交换链重建（窗口调整大小）

4. 渲染资源

✅ 图像视图（Image Views）
✅ 渲染通道（Render Pass）
  - 单个颜色附件
  - LOAD_OP_CLEAR + STORE_OP_STORE
  - 正确的子通道依赖
✅ 帧缓冲（Framebuffers）
✅ 命令池和命令缓冲
✅ 命令缓冲录制（基础清屏）

5. 同步机制

✅ 双缓冲帧同步
✅ 信号量（图像可用、渲染完成）
✅ 栅栏（飞行帧管理）
✅ 正确的同步原语使用

6. 渲染循环

✅ 基础渲染循环
✅ 图像获取（vkAcquireNextImageKHR）
✅ 命令提交（vkQueueSubmit）
✅ 图像呈现（vkQueuePresentKHR）
✅ 清屏颜色：深蓝色 (0.02, 0.02, 0.05, 1.0)
✅ 错误处理（OUT_OF_DATE、SUBOPTIMAL）

📊 代码结构

native/
├── CMakeLists.txt              # 构建配置
├── README.md                   # 本文档
│
├── src/
│   ├── main.cpp                # 主入口
│   │   └── [130 行] 初始化和主循环
│   │
│   ├── platform/               # 平台层
│   │   ├── win32_window.h      # Win32 窗口接口
│   │   └── win32_window.cpp    # Win32 窗口实现 [30 行]
│   │
│   └── vk/                     # Vulkan 层
│       ├── instance.h          # Vulkan 应用接口
│       └── instance.cpp        # Vulkan 应用实现 [346 行]
│
└── build/
    ├── bitui_native.exe        # 可执行文件
    └── [构建产物]

代码统计

模块 文件数 代码行数 状态
主程序 1 ~32 行 ✅ 完成
平台层 2 ~42 行 ✅ 完成
Vulkan 层 2 ~390 行 ✅ 完成
总计 5 ~464 行 80% 完成

🔧 构建与运行

前置要求

# 必需
- CMake 3.24+
- Vulkan SDK 1.3+
- Visual Studio 2019+ (Windows)
- 或 MinGW-w64 (Windows)

构建步骤

# 1. 进入 native 目录
cd native

# 2. 创建构建目录
mkdir build
cd build

# 3. 配置 CMake
cmake .. -G "MinGW Makefiles"  # MinGW
# 或
cmake .. -G "Visual Studio 17 2022"  # VS 2022

# 4. 构建
cmake --build . --config Release

# 5. 运行
./bitui_native.exe

运行效果

当前效果：

  • ✅ 打开 800x600 的窗口
  • ✅ 窗口标题："BitUI Vulkan (No 3rd-Party)"
  • ✅ 清屏为深蓝色（接近黑色）
  • ✅ 流畅的 60+ FPS
  • ✅ 支持窗口调整大小（自动重建交换链）
  • ✅ 正常的窗口关闭

🚀 下一步计划

近期任务（优先级排序）

1. 图形管线实现 🎯 高优先级

目标：渲染第一个三角形

任务清单：

  • 着色器模块
    • 顶点着色器（GLSL → SPIR-V）
    • 片段着色器（GLSL → SPIR-V）
    • 着色器加载和编译
  • 图形管线状态
    • 顶点输入状态
    • 输入装配状态（三角形列表）
    • 视口和裁剪状态
    • 光栅化状态
    • 多重采样状态
    • 深度/模板状态
    • 颜色混合状态
    • 动态状态
  • 管线布局
  • 图形管线创建

预期效果：

窗口中央显示一个彩色三角形
- 顶点颜色插值
- 流畅旋转动画（可选）

2. 顶点缓冲管理 🎯 高优先级

任务清单：

  • 顶点缓冲创建
    • Staging Buffer（暂存缓冲）
    • Device Local Buffer（设备本地缓冲）
    • 内存分配和绑定
  • 数据上传
    • CPU → GPU 数据传输
    • 命令缓冲录制
    • 传输队列使用
  • 索引缓冲（可选）

3. 输入系统 🎯 中优先级

任务清单：

  • 键盘输入处理
    • 按键事件捕获
    • 按键状态管理
    • 输入回调系统
  • 鼠标输入处理
    • 鼠标移动事件
    • 鼠标按钮事件
    • 鼠标滚轮事件
  • 输入到渲染的桥接

4. 资源管理器 🎯 中优先级

任务清单：

  • 缓冲管理器
    • 缓冲池
    • 自动内存管理
    • 缓冲复用
  • 纹理管理器
    • 图像加载（STB Image）
    • Mipmaps 生成
    • 采样器创建
  • 着色器管理器
    • 着色器编译缓存
    • 热重载支持

5. 文本渲染 🎯 低优先级

任务清单：

  • 字体加载（FreeType 或 STB TrueType）
  • 字形纹理生成
  • 文本布局引擎
  • UI 文本渲染

📐 架构设计

模块分层

┌─────────────────────────────────────┐
│         应用层（BitUI Runtime）      │
├─────────────────────────────────────┤
│      渲染抽象层（Renderer API）      │
├─────────────────────────────────────┤
│    资源管理层（Resource Manager）    │
├─────────────────────────────────────┤
│   Vulkan 封装层（VkApp）← 当前位置   │
├─────────────────────────────────────┤
│    平台层（Win32Window 等）          │
├─────────────────────────────────────┤
│      操作系统（Win32 / Linux）       │
└─────────────────────────────────────┘

设计原则

  1. 零第三方依赖（基础层）

    • 不依赖 GLFW/SDL
    • 直接使用 Win32 API
    • 仅依赖 Vulkan SDK

  2. 显式控制

    • 手动资源管理
    • 显式同步
    • 无隐藏开销

  3. 模块化设计

    • 平台层抽象
    • Vulkan 封装独立
    • 易于扩展新平台

  4. 性能优先

    • 最小化 CPU 开销
    • 优化 GPU 提交
    • 高效的同步机制

🔍 技术细节

Vulkan 资源管理

// 当前的资源生命周期
创建阶段：
  1. Vulkan Instance
  2. Surface（平台相关）
  3. Physical Device 选择
  4. Logical Device
  5. Swapchain
  6. Render Pass
  7. Framebuffers
  8. Command Buffers
  9. Sync Objects

运行阶段：
  - 等待栅栏
  - 获取图像
  - 提交命令
  - 呈现图像
  - 帧循环

销毁阶段：
  - 等待设备空闲
  - 反向销毁所有资源
  - 正确的销毁顺序

同步策略

// 双缓冲策略
Frame 0: {
  imageAvailable[0]  // 信号量：图像可用
  renderFinished[0]  // 信号量：渲染完成
  inFlight[0]        // 栅栏：帧飞行中
}

Frame 1: {
  imageAvailable[1]
  renderFinished[1]
  inFlight[1]
}

// 循环：currentFrame = (currentFrame + 1) & 1

交换链重建

触发条件：
1. VK_ERROR_OUT_OF_DATE_KHR（窗口调整大小）
2. VK_SUBOPTIMAL_KHR（次优配置）
3. 窗口最小化/恢复

重建流程：
1. vkDeviceWaitIdle()
2. 销毁旧资源
3. 重新创建交换链
4. 重新创建渲染资源
5. 重新录制命令缓冲

🐛 已知问题与限制

当前限制

  1. 平台支持

    • ✅ Windows（Win32）
    • ❌ Linux（计划中）
    • ❌ macOS（需要 MoltenVK）

  2. 功能限制

    • ✅ 基础清屏
    • ❌ 图形绘制
    • ❌ 文本渲染
    • ❌ 输入处理

  3. 性能优化

    • ⚠️ 单线程渲染
    • ⚠️ 无命令缓冲复用
    • ⚠️ 无资源池化

待修复问题

[ ] 窗口最小化时的渲染暂停
[ ] 高 DPI 显示器支持
[ ] 多显示器支持
[ ] 全屏模式切换
[ ] V-Sync 配置选项

📚 相关文档

外部资源

🎓 学习资源

推荐阅读

  1. Vulkan 基础

  2. 高级技术

  3. 最佳实践

🤝 贡献指南

开发流程

  1. 熟悉现有代码结构
  2. 选择任务（参考"下一步计划"）
  3. 创建功能分支
  4. 实现并测试
  5. 提交 Pull Request

代码规范

  • 使用 C++20 标准
  • RAII 资源管理
  • 明确的错误处理
  • 详细的注释

维护者：Bit Project 团队
最后更新：2025-10-11
模块版本：v0.0.1
状态：🔄 活跃开发中