EG/demo/OPENXR_IMPLEMENTATION_GUIDE.md

# OpenXR 实现指南

## 🎯 概述

本指南详细介绍了如何在Panda3D引擎中实现OpenXR支持，并通过有线连接串流到VR设备。

## 🏗️ 系统架构

### 核心组件

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

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

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

## 🔧 安装和配置

### 1. 系统依赖

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

# 安装OpenXR运行时
# Windows: 
# 1. 下载并安装SteamVR或Oculus运行时
# 2. 安装OpenXR运行时

# Linux:
sudo apt-get install openxr-loader
```

### 2. 有线连接设置

```bash
# 配置网络以支持有线连接
# 1. 使用USB网络适配器或以太网连接VR设备
# 2. 确保PC和VR设备在同一子网
# 3. 配置防火墙允许OpenXR通信（端口9943-9945）
```

### 3. VR设备配置

```bash
# 1. 在VR设备上安装OpenXR客户端应用
# 2. 通过有线连接设备到PC
# 3. 启用开发者模式（如需要）
```

## 🚀 使用方法

### 快速启动

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

# 一键启用OpenXR模式
if world.enableOpenXRMode():
    print("OpenXR模式已启用")
    
    # 检查OpenXR状态
    status = world.getOpenXRStatus()
    print(f"OpenXR设备: {status['openxr_info']}")
    print(f"连接状态: {status['openxr_connected']}")
    print(f"串流状态: {status['openxr_streaming']}")
```

### 详细控制

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

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

## 🎮 OpenXR交互功能

### 控制器输入处理

```python
# 获取控制器状态
controllers = world.getAllControllers()
for controller_id in controllers:
    state = world.getControllerState(controller_id)
    
    # 检查触发器按下
    if state['trigger'] > 0.5:
        print(f"控制器 {controller_id} 触发器按下")
    
    # 检查摇杆输入
    thumbstick_x, thumbstick_y = state['thumbstick']['x'], state['thumbstick']['y']
    if abs(thumbstick_x) > 0.5:
        print(f"摇杆水平滑动: {thumbstick_x}")
```

### 对象抓取和操作

```python
# OpenXR输入处理器自动处理对象抓取
# 触发器按下时自动检测和抓取对象
# 触发器释放时自动释放对象

# 监听OpenXR事件
world.event_handler.accept('openxr-object-grabbed', onObjectGrabbed)
world.event_handler.accept('openxr-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
# 调整OpenXR渲染质量
openxr_manager = world.openxr_manager
openxr_manager.render_scale = 1.0  # 渲染缩放 (0.5-2.0)

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

### 网络优化

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

### 系统资源监控

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

## 🔍 故障排除

### 常见问题

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

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

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

### 调试命令

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

# 获取详细状态信息
openxr_info = world.getOpenXRInfo()
print(f"OpenXR设备信息: {openxr_info}")

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

## 🎯 高级功能

### 自定义OpenXR交互

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

### 多用户OpenXR支持

```python
# 支持多个OpenXR用户
class MultiUserOpenXRManager:
    def __init__(self):
        self.openxr_users = {}
        
    def addOpenXRUser(self, user_id, openxr_manager):
        self.openxr_users[user_id] = openxr_manager
        
    def syncOpenXRUsers(self):
        # 同步多用户OpenXR状态
        pass
```

## 📋 配置文件

### OpenXR配置 (`config/openxr_config.yaml`)

```yaml
openxr:
  enabled: true
  render_scale: 1.0
  tracking_space: "stage"
  
streaming:
  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
# 创建OpenXR开发环境
python -m venv openxr_env
source openxr_env/bin/activate
pip install -r requirements/openxr-requirements.txt

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

### 生产环境

```bash
# 优化生产部署
# 1. 使用专用计算机处理OpenXR渲染
# 2. 配置高性能有线网络连接
# 3. 启用GPU加速
# 4. 监控系统性能
```

## 📚 参考资料

- [OpenXR规范](https://www.khronos.org/openxr/)
- [Panda3D文档](https://docs.panda3d.org/)
- [OpenXR Cookbook](https://github.com/KhronosGroup/OpenXR-Docs)

## 🤝 贡献指南

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

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

## 📄 许可证

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