16 KiB
16 KiB
VR Manager 模块化拆分计划
📊 现状分析
当前状态：
- 文件：core/vr_manager.py
- 行数：4736行（严重超标，标准为900行）
- 方法数：138个方法
- 问题：典型的"上帝类"反模式，承担了过多职责
主要职责识别：
1. 性能监控和调试 (~900行)
2. 测试模式系统 (~800行)
3. 对象池和优化 (~300行)
4. 姿态跟踪系统 (~900行)
5. 设备管理 (~300行)
6. 渲染缓冲管理 (~400行)
7. 相机系统 (~350行)
8. 合成器和提交 (~300行)
9. RenderPipeline集成 (~250行)
10. 核心生命周期 (~500行)
---
🎯 拆分策略
核心原则
1. 渐进迭代：每次拆分一个模块，立即验证
2. 组合模式：新模块作为VRManager属性，保持接口不变
3. 依赖顺序：先拆分独立模块，后拆分核心模块
4. 向后兼容：所有公开API通过委托方法保持可用
拆分顺序（按依赖关系）
阶段1：性能监控 → 最独立，零依赖
阶段2：测试调试 → 依赖少，可独立测试
阶段3：对象池优化 → 小而关键，性能核心
阶段4：跟踪系统 → 中等复杂度
阶段5：渲染系统 → 核心功能，最复杂
阶段6：核心管理器 → 整合所有子系统
---
📋 详细拆分计划
🔷 阶段1：拆分性能监控系统 (2-3小时)
创建文件：core/vr/performance/monitoring.py (~900行)
迁移方法 (35个)：
- 性能报告：_print_performance_report, _print_performance_recommendations, _print_brief_performance_report
- 性能监控：_init_performance_monitoring, _update_performance_metrics, _update_gpu_metrics, _track_frame_time
- GPU计时：_get_gpu_frame_timing, enable_gpu_timing_monitoring, disable_gpu_timing_monitoring
- 管线统计：_get_pipeline_stats, test_pipeline_monitoring, _start_timing, _end_timing
- 诊断工具：_print_render_callback_diagnostics, _check_rendering_optimizations, _diagnose_opengl_state
- 调试控制：enable_debug_output, disable_debug_output, set_debug_mode, toggle_debug_output, get_debug_status
- 配置方法：set_performance_check_interval, set_frame_time_history_size, set_performance_report_interval
- 查询方法：get_performance_stats, get_current_performance_summary, get_performance_monitoring_config
- 控制方法：enable_performance_monitoring, disable_performance_monitoring, force_performance_report, reset_performance_counters
- 状态查询：print_performance_monitoring_status, set_prediction_time
迁移属性 (~30个)：
# 性能监控开关
performance_monitoring, debug_output_enabled, debug_mode
enable_pipeline_monitoring, enable_gpu_timing
# 性能数据
cpu_usage, memory_usage, gpu_usage, gpu_memory_usage
frame_times, max_frame_time_history
wait_poses_time, left_render_time, right_render_time, submit_time
total_frame_time, vr_sync_wait_time
# GPU计时
gpu_scene_render_ms, gpu_pre_submit_ms, gpu_post_submit_ms
gpu_total_render_ms, gpu_compositor_render_ms
gpu_timing_history, gpu_timing_failure_count
# 历史记录
wait_poses_times, render_times, submit_times, sync_wait_times
pipeline_history_size
类结构：
class VRPerformanceMonitor:
"""VR性能监控系统"""
def __init__(self, vr_manager):
self.vr_manager = vr_manager
# 初始化所有性能监控属性
VRManager集成：
# __init__ 中
self.performance_monitor = VRPerformanceMonitor(self)
# 委托方法（保持API兼容）
def enable_performance_monitoring(self):
return self.performance_monitor.enable_performance_monitoring()
验证步骤：
1. ✅ 编译检查：python -m py_compile core/vr/performance/monitoring.py
2. ✅ 导入测试：启动应用，确认无导入错误
3. ✅ 功能测试：调用 vr_manager.enable_performance_monitoring()
4. ✅ 输出验证：检查性能报告正常生成
5. ✅ API测试：验证所有委托方法可用
---
🔷 阶段2：拆分测试调试系统 (2-3小时)
创建文件：core/vr/testing/test_mode.py (~800行)
迁移方法 (17个)：
- 测试模式：enable_vr_test_mode, disable_vr_test_mode, switch_test_display_mode
- 纹理管理：_ensure_test_mode_textures, _create_cached_ovr_textures, _batch_submit_textures
- 显示系统：_initialize_test_display, _update_test_display, _create_stereo_display, _cleanup_test_display
- HUD系统：_initialize_test_performance_hud, _update_test_performance_hud, _cleanup_test_performance_hud
- 状态查询：get_test_mode_status, get_test_mode_features, set_test_mode_features
- 性能测试：run_vr_performance_test
迁移属性 (~15个)：
vr_test_mode, test_display_mode
test_display_quad, test_right_quad, stereo_display_created
test_performance_hud, test_performance_text
test_mode_initialized
hud_update_counter, hud_update_interval
test_mode_submit_texture, test_mode_wait_poses
类结构：
class VRTestMode:
"""VR测试模式系统"""
def __init__(self, vr_manager):
self.vr_manager = vr_manager
验证步骤：
1. ✅ 启用测试模式：vr_manager.enable_vr_test_mode('stereo')
2. ✅ 检查显示：验证测试quad显示正确
3. ✅ HUD验证：检查性能HUD显示
4. ✅ 切换模式：测试 left/right/stereo 模式切换
5. ✅ 禁用测试：vr_manager.disable_vr_test_mode()
---
🔷 阶段3：拆分对象池和优化系统 (1-2小时)
创建文件：core/vr/performance/optimization.py (~300行)
迁移方法 (19个)：
- 对象池：_initialize_object_pools, _get_pooled_matrix, _return_pooled_matrix
- GC控制：_manual_gc_control, enable_gc_control, disable_gc_control, set_manual_gc_interval, force_manual_gc
- 分辨率：set_resolution_scale, set_quality_preset, cycle_quality_preset, _apply_resolution_scale
- 查询方法：get_object_pool_status, get_resolution_info, print_resolution_info
- 性能模式：enable_performance_mode, disable_performance_mode, set_performance_mode_trigger_frame, get_performance_mode_status
迁移属性 (~20个)：
# 对象池
_matrix_pool, _matrix_pool_size
_cached_matrices, _controller_poses_cache
_left_ovr_texture, _right_ovr_texture
# GC控制
_gc_control_enabled, _gc_disabled
_manual_gc_interval, _last_manual_gc_frame
# 分辨率
resolution_scale, base_eye_width, base_eye_height
scaled_eye_width, scaled_eye_height
quality_presets, current_quality_preset
# 性能模式
performance_mode_enabled, performance_mode_trigger_frame
验证步骤：
1. ✅ 对象池：检查Mat4对象池正常工作
2. ✅ GC控制：验证手动GC按预期触发
3. ✅ 分辨率：测试质量预设切换
4. ✅ 性能测试：运行30秒性能测试，确认优化生效
---
🔷 阶段4：拆分跟踪系统 (3-4小时)
创建文件1：core/vr/tracking/poses.py (~600行)
迁移方法 (12个)：
- 姿态获取：_wait_get_poses, _wait_get_poses_immediate, _wait_get_poses_with_prediction
- 姿态缓存：_cache_poses_for_next_frame, _reset_waitgetposes_flag
- 姿态更新：_update_tracking_data, update_hmd, _update_camera_poses, _update_camera_poses_with_cache
- 矩阵转换：_convert_openvr_matrix_to_panda, _update_matrix_from_openvr, convert_mat
迁移属性：
hmd_pose, controller_poses, tracked_device_poses
poses, game_poses
tracking_space, hmd_anchor, left_eye_anchor, right_eye_anchor
coord_mat, coord_mat_inv
use_prediction_time, poses_updated_in_task
_waitgetposes_called_this_frame
_cached_render_poses, _first_frame
创建文件2：core/vr/tracking/devices.py (~300行)
迁移方法 (8个)：
- 控制器：_initialize_controllers, _detect_controllers, get_controller_by_role
- 设备管理：_create_tracked_device_anchor, update_tracked_devices
- 状态查询：are_controllers_connected, get_connected_controllers
- 震动：trigger_controller_haptic
迁移属性：
left_controller, right_controller
controllers, tracked_device_anchors
创建文件3：core/vr/tracking/input_wrapper.py (~200行)
迁移方法 (12个)：
- 按钮查询：is_trigger_pressed, is_trigger_just_pressed, is_grip_pressed, is_grip_just_pressed, is_menu_pressed
- 触摸板：is_trackpad_touched, get_trackpad_position
- 交互查询：get_selected_object, get_grabbed_object, is_grabbing_object
- 交互控制：force_release_all_grabs, add_interactable_object
类结构：
class VRPoseTracker:
"""VR姿态跟踪系统"""
class VRDeviceManager:
"""VR设备管理系统"""
class VRInputWrapper:
"""VR输入包装层"""
验证步骤：
1. ✅ 姿态跟踪：启动VR，检查头显跟踪正常
2. ✅ 控制器检测：验证控制器正确识别
3. ✅ 输入测试：测试按钮和触摸板输入
4. ✅ 震动测试：触发控制器震动反馈
---
🔷 阶段5：拆分渲染系统 (4-5小时)
创建文件1：core/vr/rendering/buffers.py (~400行)
迁移方法 (10个)：
- 缓冲区创建：_create_vr_buffers, _create_vr_buffer, _create_vr_buffers_with_pipeline
- 纹理管理：_create_vr_texture, _prepare_and_cache_textures
- Pipeline效果：_apply_pipeline_vr_effects
- 天空盒：_check_skybox_status, _create_vr_skybox
- 诊断：_diagnose_buffer_performance
- 清理：_cleanup_vr_buffers
迁移属性：
vr_left_eye_buffer, vr_right_eye_buffer
vr_left_texture, vr_right_texture
left_texture_id, right_texture_id, textures_prepared
eye_width, eye_height, near_clip, far_clip
scaled_eye_width, scaled_eye_height
创建文件2：core/vr/rendering/cameras.py (~350行)
迁移方法 (6个)：
- 相机设置：_setup_vr_cameras, _get_eye_offset
- 优化：_optimize_vr_rendering, _apply_lightweight_rendering, _disable_vr_buffer_extras
- 主相机：_disable_main_cam, _enable_main_cam
迁移属性：
vr_left_camera, vr_right_camera
创建文件3：core/vr/rendering/compositor.py (~300行)
迁移方法 (9个)：
- 渲染回调：simple_left_cb, simple_right_cb
- 纹理提交：submit_texture
- GPU同步：_sync_gpu_if_needed, _smart_gpu_sync
- ATW控制：_disable_async_reprojection, enable_async_reprojection_disable, disable_async_reprojection_disable
迁移属性：
vr_compositor, submit_together
openvr_frame_id
left_eye_last_render_frame, right_eye_last_render_frame
disable_async_reprojection
创建文件4：core/vr/rendering/pipeline.py (~250行)
迁移方法 (4个)：
- Pipeline集成：_create_vr_buffers_with_pipeline, _apply_pipeline_vr_effects
- 模式切换：set_vr_render_mode, get_vr_render_mode
迁移属性：
vr_render_mode, render_pipeline_enabled
vr_pipeline_left_target, vr_pipeline_right_target
pipeline_resolution_scale, vr_pipeline_controller
pipeline_vr_config
验证步骤：
1. ✅ 缓冲区：检查左右眼缓冲区正确创建
2. ✅ 相机：验证双眼相机位置和视锥
3. ✅ 渲染：测试左右眼渲染回调
4. ✅ 提交：确认纹理正确提交到OpenVR
5. ✅ Pipeline：测试RenderPipeline模式切换
---
🔷 阶段6：重构核心管理器 (2-3小时)
保留在 core/vr_manager.py (~500行)
保留方法 (10个核心方法)：
- 生命周期：__init__, cleanup
- VR初始化：is_vr_available, initialize_vr
- VR控制：enable_vr, disable_vr
- 主循环：_start_vr_task, _update_vr
- 状态查询：get_vr_status
新增子系统属性（组合模式）：
def __init__(self, world):
# ... 基础初始化 ...
# 子系统初始化（按依赖顺序）
self.optimization = VROptimization(self)
self.performance_monitor = VRPerformanceMonitor(self)
self.test_mode = VRTestMode(self)
self.pose_tracker = VRPoseTracker(self)
self.device_manager = VRDeviceManager(self)
self.input_wrapper = VRInputWrapper(self)
self.buffer_manager = VRBufferManager(self)
self.camera_manager = VRCameraManager(self)
self.compositor = VRCompositor(self)
self.pipeline_manager = VRPipelineManager(self)
委托方法（保持API兼容）：
# 性能监控委托
def enable_performance_monitoring(self):
return self.performance_monitor.enable_performance_monitoring()
# 测试模式委托
def enable_vr_test_mode(self, display_mode='stereo'):
return self.test_mode.enable_vr_test_mode(display_mode)
# 优化系统委托
def set_resolution_scale(self, scale):
return self.optimization.set_resolution_scale(scale)
# ... 其他委托方法 ...
验证步骤：
1. ✅ 完整启动：启动应用，测试VR完整流程
2. ✅ API测试：验证所有公开API可用
3. ✅ 性能测试：运行性能测试，确认无回退
4. ✅ 集成测试：测试传送、交互、渲染等所有功能
---
✅ 每阶段验证清单
静态验证
- python -m py_compile 检查语法
- python main.py --help 验证模块导入
- 运行 pylint 检查代码质量
功能验证
- 启动应用：python main.py
- 检查VR可用性：vr_manager.is_vr_available()
- 测试VR启用：切换到VR模式
- 测试头显跟踪：移动头显查看跟踪
- 测试控制器：检测和交互
- 测试传送：使用控制器传送
- 测试性能监控：查看性能报告
- 测试VR禁用：退出VR模式
性能验证
- 运行性能测试：vr_manager.run_vr_performance_test(30)
- 检查帧率稳定在90fps
- 对比拆分前后性能指标
- 确认无性能回退
---
🛡️ 风险控制
备份策略
# 每个阶段开始前
cp core/vr_manager.py core/vr_manager.py.backup.stage{N}
回滚方案
# 恢复备份
cp core/vr_manager.py.backup.stage{N} core/vr_manager.py
循环依赖预防
- ✅ 所有子模块通过 self.vr_manager 访问其他子系统
- ✅ 子模块间不直接引用
- ✅ VRManager 作为中介协调所有子系统
性能保护
- ✅ 热点路径（渲染回调）保持直接调用
- ✅ 非关键路径使用委托模式
- ✅ 对象池和缓存机制保持不变
---
📊 预期成果
代码结构
core/vr_manager.py (500行) ✅
core/vr/
├── performance/
│ ├── monitoring.py (900行) ✅
│ └── optimization.py (300行) ✅
├── testing/
│ └── test_mode.py (800行) ✅
├── tracking/
│ ├── poses.py (600行) ✅
│ ├── devices.py (300行) ✅
│ └── input_wrapper.py (200行) ✅
└── rendering/
├── buffers.py (400行) ✅
├── cameras.py (350行) ✅
├── compositor.py (300行) ✅
└── pipeline.py (250行) ✅
改进指标
- ✅ 文件行数：4736行 → 最大900行（符合规范）
- ✅ 目录文件数：所有目录 ≤ 4个文件（远小于8个限制）
- ✅ 方法数：138个 → 每个类 ≤ 20个方法
- ✅ 职责清晰：每个模块单一职责
- ✅ 可维护性：大幅提升
- ✅ 可测试性：模块化便于单元测试
- ✅ 向后兼容：100%保持现有API
时间估算
- 阶段1: 2-3小时
- 阶段2: 2-3小时
- 阶段3: 1-2小时
- 阶段4: 3-4小时
- 阶段5: 4-5小时
- 阶段6: 2-3小时
总计：15-20小时，分6个阶段逐步完成
---
🚀 开始执行
确认此计划后，将按以下顺序执行：
1. 创建备份
2. 阶段1：拆分性能监控系统
3. 验证通过后，进入阶段2
4. 依次完成所有6个阶段
5. 最终整体测试和文档更新