EG/demo/VR_ALVR_实现指南.md

# VR + ALVR 串流实现指南

## 🎯 概述

本指南详细介绍了如何在Panda3D引擎中实现VR支持，并通过ALVR串流到Quest等VR头显设备。

## 🏗️ 系统架构

### 核心组件

1. **VRManager** (`core/vr_manager.py`)
   - 负责VR系统初始化
   - 管理立体渲染（左右眼）
   - 处理VR设备跟踪
   - 集成OpenVR接口

2. **VRInputHandler** (`core/vr_input_handler.py`)
   - 处理VR控制器输入
   - 手势识别系统
   - 交互逻辑处理

3. **ALVRStreamer** (`core/alvr_streamer.py`)
   - ALVR服务器通信
   - 视频流编码和传输
   - 性能监控

4. **VRControlPanel** (`ui/vr_control_panel.py`)
   - VR系统GUI控制界面
   - 实时状态监控
   - 参数调整面板

## 🔧 安装和配置

### 1. 系统依赖

```bash
# 安装Python依赖
pip install -r requirements/vr-requirements.txt

# 安装OpenVR运行时
# Windows: 下载并安装SteamVR
# Linux: 
sudo apt-get install steam
# 然后在Steam中安装SteamVR
```

### 2. ALVR服务器设置

```bash
# 下载ALVR服务器
# 从 https://github.com/alvr-org/ALVR 下载最新版本

# Windows
# 1. 解压到 C:\ALVR\
# 2. 运行 alvr_server.exe

# Linux
# 1. 解压到 /usr/local/bin/
# 2. 运行 alvr_server
```

### 3. Quest设备配置

```bash
# 1. 在Quest上安装ALVR客户端
# 2. 启用开发者模式
# 3. 连接到同一WiFi网络
# 4. 配置防火墙允许ALVR通信（端口9943-9944）
```

## 🚀 使用方法

### 快速启动

```python
# 在主程序中
world = MyWorld()

# 一键启用VR模式
if world.enableVRMode():
    print("VR模式已启用")
    
    # 检查VR状态
    status = world.getVRStatus()
    print(f"VR设备: {status['vr_info']}")
    print(f"ALVR连接: {status['alvr_connected']}")
    print(f"串流状态: {status['alvr_streaming']}")
```

### 详细控制

```python
# 分步骤启动VR
world = MyWorld()

# 1. 初始化VR系统
if world.initializeVR():
    print("VR系统初始化成功")
    
    # 2. 启动VR输入处理
    world.startVRInput()
    
    # 3. 显示控制器射线
    world.showControllerRays(True)
    
    # 4. 初始化ALVR串流
    if world.initializeALVR():
        print("ALVR初始化成功")
        
        # 5. 设置串流质量
        world.setALVRStreamQuality(
            width=2880,
            height=1700,
            fps=72,
            bitrate=150
        )
        
        # 6. 开始串流
        world.startALVRStreaming()
```

### GUI控制界面

```python
# 创建VR控制面板
from ui.vr_control_panel import VRControlPanel

vr_panel = VRControlPanel(world)
vr_panel.show()

# 面板功能：
# - 一键启用/禁用VR
# - ALVR串流控制
# - 质量参数调整
# - 实时性能监控
# - 控制器状态显示
```

## 🎮 VR交互功能

### 控制器输入处理

```python
# 获取控制器状态
controllers = world.getAllControllers()
for controller_id in controllers:
    state = world.getControllerState(controller_id)
    
    # 检查扳机按下
    if state['trigger'] > 0.5:
        print(f"控制器 {controller_id} 扳机按下")
    
    # 检查触摸板输入
    touchpad_x, touchpad_y = state['touchpad']
    if abs(touchpad_x) > 0.5:
        print(f"触摸板水平滑动: {touchpad_x}")
```

### 对象抓取和操作

```python
# VR输入处理器自动处理对象抓取
# 扳机按下时自动检测和抓取对象
# 扳机释放时自动释放对象

# 监听VR事件
world.event_handler.accept('vr-object-grabbed', onObjectGrabbed)
world.event_handler.accept('vr-object-released', onObjectReleased)

def onObjectGrabbed(object_node, controller_id):
    print(f"抓取对象: {object_node.getName()}")
    
def onObjectReleased(object_node, controller_id):
    print(f"释放对象: {object_node.getName()}")
```

### 触觉反馈

```python
# 发送触觉反馈
world.sendHapticFeedback(
    controller_id=0,
    duration=0.5,      # 持续时间（秒）
    intensity=0.8      # 强度（0-1）
)
```

## 📊 性能优化

### 渲染优化

```python
# 调整VR渲染质量
vr_manager = world.vr_manager
vr_manager.render_scale = 1.0  # 渲染缩放 (0.5-2.0)

# 设置多重采样抗锯齿
fb_props = FrameBufferProperties()
fb_props.setMultisamples(4)  # 4x MSAA
```

### 网络优化

```python
# 优化ALVR串流参数
world.setALVRStreamQuality(
    width=2160,      # 降低分辨率提高性能
    height=1200,
    fps=60,          # 降低帧率减少延迟
    bitrate=100      # 降低比特率适应网络带宽
)
```

### 系统资源监控

```python
# 获取性能状态
streaming_status = world.getALVRStreamingStatus()
print(f"串流FPS: {streaming_status['fps']}")
print(f"延迟: {streaming_status['latency']} ms")
print(f"分辨率: {streaming_status['resolution']}")
```

## 🔍 故障排除

### 常见问题

1. **VR系统初始化失败**
   ```
   错误: OpenVR初始化失败
   解决: 确保SteamVR已安装并运行
   ```

2. **ALVR连接失败**
   ```
   错误: 无法连接到ALVR服务器
   解决: 
   - 检查ALVR服务器是否运行
   - 确认防火墙设置
   - 检查网络连接
   ```

3. **串流质量问题**
   ```
   问题: 画面卡顿或延迟高
   解决:
   - 降低分辨率和帧率
   - 检查WiFi信号强度
   - 调整比特率设置
   ```

### 调试命令

```python
# 启用调试模式
world.vr_manager.debug_mode = True

# 获取详细状态信息
vr_info = world.getVRInfo()
print(f"VR设备信息: {vr_info}")

# 检查网络连接
if world.isALVRConnected():
    print("ALVR连接正常")
else:
    print("ALVR连接失败")
```

## 🎯 高级功能

### 自定义VR交互

```python
# 创建自定义VR交互逻辑
class CustomVRInteraction:
    def __init__(self, world):
        self.world = world
        
    def handleCustomGesture(self, gesture_data):
        # 处理自定义手势
        pass
        
    def createVRMenu(self, controller_id):
        # 在VR中创建3D菜单
        pass
```

### 多用户VR支持

```python
# 支持多个VR用户
class MultiUserVRManager:
    def __init__(self):
        self.vr_users = {}
        
    def addVRUser(self, user_id, vr_manager):
        self.vr_users[user_id] = vr_manager
        
    def syncVRUsers(self):
        # 同步多用户VR状态
        pass
```

## 📋 配置文件

### VR配置 (`config/vr_config.yaml`)

```yaml
vr:
  enabled: true
  render_scale: 1.0
  tracking_space: "standing"
  
alvr:
  server_ip: "127.0.0.1"
  server_port: 9943
  streaming_port: 9944
  
  video:
    width: 2880
    height: 1700
    fps: 72
    bitrate: 150
    codec: "h264"
    
  audio:
    enabled: true
    sample_rate: 48000
    channels: 2
```

## 🚀 部署建议

### 开发环境

```bash
# 创建VR开发环境
python -m venv vr_env
source vr_env/bin/activate
pip install -r requirements/vr-requirements.txt

# 启动开发服务器
python main.py --vr-mode
```

### 生产环境

```bash
# 优化生产部署
# 1. 使用专用VR计算机
# 2. 配置高性能网络
# 3. 启用GPU加速
# 4. 监控系统性能
```

## 📚 参考资料

- [OpenVR API文档](https://github.com/ValveSoftware/openvr/wiki/API-Documentation)
- [ALVR项目主页](https://github.com/alvr-org/ALVR)
- [Panda3D VR指南](https://docs.panda3d.org/1.10/python/programming/render-to-texture/index)
- [Quest开发者文档](https://developer.oculus.com/documentation/quest/)

## 🤝 贡献指南

欢迎贡献代码和改进建议！请遵循以下步骤：

1. Fork此仓库
2. 创建功能分支
3. 提交代码修改
4. 创建Pull Request

## 📄 许可证

本项目采用MIT许可证。详见LICENSE文件。