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. 系统依赖

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

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

2. ALVR服务器设置

# 下载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设备配置

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

🚀 使用方法

快速启动

# 在主程序中
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']}")

详细控制

# 分步骤启动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控制界面

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

vr_panel = VRControlPanel(world)
vr_panel.show()

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

🎮 VR交互功能

控制器输入处理

# 获取控制器状态
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}")

对象抓取和操作

# 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()}")

触觉反馈

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

📊 性能优化

渲染优化

# 调整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

网络优化

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

系统资源监控

# 获取性能状态
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信号强度
   - 调整比特率设置
   

调试命令

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

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

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

🎯 高级功能

自定义VR交互

# 创建自定义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支持

# 支持多个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)

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

🚀 部署建议

开发环境

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

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

生产环境

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

📚 参考资料

• OpenVR API文档
• ALVR项目主页
• Panda3D VR指南
• Quest开发者文档

🤝 贡献指南

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

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

📄 许可证

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