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. 最终整体测试和文档更新