EG/VR_GUIDE.md

# VR模式使用指南

## 概述

本项目现已支持VR模式，通过SteamVR将Panda3D引擎的画面传输到VR头显设备。您可以在虚拟现实环境中体验和编辑3D场景。

## 系统要求

### 硬件要求
- 支持SteamVR的VR头显设备（如HTC Vive、Oculus Rift、Valve Index等）
- VR头显控制器（可选，用于交互）
- 满足VR运行要求的计算机配置

### 软件要求
- Windows 10/11 或 Linux（支持OpenVR）
- SteamVR运行时
- Python 3.7+
- 项目依赖库（见安装步骤）

## 安装与设置

### 1. 安装VR依赖
```bash
# 安装OpenVR Python库
pip install openvr==2.2.0

# 或者安装所有项目依赖
pip install -r requirements/requirements.txt
```

### 2. 安装SteamVR
1. 安装Steam客户端
2. 在Steam中搜索并安装"SteamVR"
3. 连接您的VR头显设备
4. 按照SteamVR设置向导完成房间设置

### 3. 验证VR设置
运行VR测试脚本来验证安装：
```bash
python vr_test.py
```

## 使用方法

### 启动VR模式

1. **启动SteamVR**
   - 在Steam中启动SteamVR
   - 确保VR头显已连接并处于就绪状态

2. **启动应用程序**
   ```bash
   python main.py
   ```

3. **进入VR模式**
   - 在菜单栏中选择 `VR` → `进入VR模式`
   - 系统会自动检测VR设备并初始化VR渲染

4. **戴上VR头显**
   - 现在您可以在VR环境中查看和操作3D场景

### VR菜单选项

- **进入VR模式**: 启用VR渲染，将画面输出到VR头显
- **退出VR模式**: 退出VR模式，回到桌面显示
- **VR状态**: 查看VR系统状态和设备信息
- **VR设置**: 配置VR渲染参数和性能选项

### VR交互

目前支持的VR交互功能：
- **头部追踪**: 自动追踪头显位置和朝向
- **房间规模移动**: 在设定的VR空间内移动
- **立体显示**: 为左右眼提供不同视角的立体图像

## 配置选项

### VR设置对话框

在 `VR` → `VR设置` 中可以配置：

- **渲染质量**: 调整VR渲染的画质等级
- **抗锯齿**: 设置抗锯齿级别
- **刷新率**: 配置VR头显刷新率
- **异步重投影**: 启用/禁用ATW技术

### 性能优化建议

1. **降低渲染分辨率**: 如果性能不足，可以降低VR渲染质量
2. **减少抗锯齿**: 关闭或降低抗锯齿级别
3. **优化场景复杂度**: 减少场景中的多边形数量
4. **关闭不必要的特效**: 暂时关闭高级渲染特效

## 故障排除

### 常见问题

**Q: 无法进入VR模式，提示"VR系统不可用"**
A: 请检查：
- SteamVR是否正在运行
- VR头显是否正确连接
- OpenVR库是否已安装 (`pip install openvr`)

**Q: VR画面卡顿或延迟**
A: 尝试：
- 降低VR渲染质量
- 关闭其他占用GPU的程序
- 检查VR头显连接线是否松动

**Q: VR菜单显示为灰色（不可用）**
A: 检查：
- VR管理器是否正确初始化
- 查看控制台错误信息
- 运行 `python vr_test.py` 进行诊断

**Q: 只能看到一只眼的画面**
A: 这可能是：
- VR渲染缓冲区创建失败
- OpenVR投影矩阵设置错误
- 检查图形驱动程序是否最新

### 诊断工具

使用内置的VR测试工具进行问题诊断：
```bash
python vr_test.py
```

该工具会检测：
- 基础环境和依赖
- VR管理器状态
- VR设备可用性
- VR初始化过程
- UI菜单集成

### 日志信息

VR相关的日志信息会输出到控制台，包括：
- VR系统初始化状态
- 渲染缓冲区创建信息
- 追踪数据更新
- 错误和警告信息

## 开发者信息

### VR架构

```
main.py (MyWorld)
├── core/vr_manager.py (VRManager)
│   ├── OpenVR集成
│   ├── 渲染缓冲区管理
│   ├── 相机控制
│   └── 追踪数据处理
└── ui/main_window.py
    ├── VR菜单
    ├── VR设置对话框
    └── VR事件处理
```

### 核心类

- **VRManager**: VR功能的核心管理类
- **MainWindow**: UI集成和事件处理
- **MyWorld**: VR管理器的宿主类

### 扩展开发

如需添加新的VR功能，可以：

1. 在 `VRManager` 中添加新方法
2. 在 `MainWindow` 中添加对应的UI控件
3. 更新VR设置对话框
4. 添加相应的测试代码

## 技术支持

如果遇到问题，请：

1. 运行 `python vr_test.py` 获取诊断信息
2. 检查控制台日志
3. 确认SteamVR和硬件设置正确
4. 提交问题时请包含详细的错误信息和系统配置

## 版本信息

- VR功能版本: 1.0.0
- 支持的OpenVR版本: 2.2.0+
- 兼容的SteamVR版本: 最新版本

---

**注意**: VR功能目前处于初始版本，可能还有一些限制和待完善的功能。我们会持续改进和优化VR体验。