Bevy 相机渲染迁移指南：`SortedCamera::hdr` 移除，`sorted_camera_index_for_target` 改为按渲染目标独立计数

Bevy 相机渲染迁移指南SortedCamera::hdr移除sorted_camera_index_for_target改为按渲染目标独立计数【免费下载链接】bevyA refreshingly simple>项目地址: https://gitcode.com/GitHub_Trending/be/bevy本篇迁移指南基于当前仓库的官方迁移说明 sorted_camera_indices_per_target.md对应上游 Pull Request 25479针对同一渲染目标上混合使用 HDR 与非 HDR 相机栈的行为变更展开。读完本文你将掌握新的相机 blit 为何会自动开启 alpha 混合、如何通过显式blend_state恢复旧的覆盖行为以及渲染世界中原本依赖SortedCamera::hdr的代码应如何改写为读取ExtractedCamera::hdr。变更一览发生了什么变更点旧行为新行为同目标混合 HDR 相机栈的上层输出上层相机把下层相机输出覆盖掉blit 阶段自动检测 alpha 混合将上层结果合成composite到底层之上SortedCamera::hdr字段存在渲染世界系统可读取已移除sorted_camera_index_for_target计数维度与 HDR 等相机设置相关混合栈会出现两个底层相机仅按渲染目标render target单独计数渲染世界系统读取 HDR 状态从SortedCameras资源中的SortedCamera.hdr读取改为读取视图实体上的ExtractedCamera::hdr单相机场景、以及同一渲染目标上所有相机 HDR 设置一致uniform-Hdr的相机栈不受影响无需改动。为什么改混合 HDR 相机栈曾经上层覆盖下层Bevy 允许多个相机按order叠加渲染到同一个渲染目标order小的相机先渲染作为底层/baseorder大的相机后渲染作为上层。渲染完成后每个相机的中间纹理main texture会通过一次 blit 写入最终渲染目标。当两个相机共享目标时底层相机应写入/清空上层相机则应把自身结果半透明合成到底层之上而不是整块覆盖。在旧实现中相机在目标内的序号计数混入了Hdr这样的相机设置维度。于是当栈内混合了 HDR开启与非 HDR关闭相机时上下两层相机可能各自都被当成该层级的第一个index 0相机blit 因而按replace/覆盖语义执行导致上层相机最终把下层相机已经渲染好的输出整体覆盖掉。当前仓库源码中sort_cameras的注释恰好印证了这一历史问题crates/bevy_render/src/camera.rs#L757-L772The map has to be keyed by only the target, and not by anything else. Splitting the count by a camera setting such asHdrwould leave a mixed stack with two bottom cameras, and the top one would overwrite the base instead of blending over it. So we dont do that.即计数的 key只能是渲染目标本身。如果再按Hdr之类的相机设置拆分计数混合栈中就会出现两个底层相机顶层会把底层覆盖而非在其上混合。新实现正是针对这一点做了修正。新行为一blit 自动检测 alpha 混合合成而非覆盖sort_cameras系统现在为每个共享同一渲染目标的相机依次分配自底向上的序号写入ExtractedCamera::sorted_camera_index_for_target目标上的第一个相机得到0第二个得到1以此类推见 crates/bevy_render/src/camera.rs#L730-L774。随后在 upscaling写回阶段blit 管线的混合状态按此序号自动决定。核心逻辑位于 crates/bevy_core_pipeline/src/upscaling/mod.rs#L64-L86 的prepare_view_upscaling_pipelineslet blend_state if let Some(extracted_camera) camera { match extracted_camera.output_mode { CameraOutputMode::Skip None, CameraOutputMode::Write { blend_state, .. } match blend_state { None { // Auto-detect: the first camera to render to this output // (sorted_camera_index_for_target 0) uses replace mode; // subsequent cameras default to alpha blending so they dont // accidentally overwrite earlier cameras output. if extracted_camera.sorted_camera_index_for_target 0 { Some(BlendState::ALPHA_BLENDING) } else { None } } _ blend_state, }, } } else { None };据此可以总结出新规则output_mode为CameraOutputMode::Skip时不写回CameraOutputMode::Write中未显式设置blend_state即None时启用自动检测sorted_camera_index_for_target 0该目标上的第一个/底层相机→None即按原样 replace 写入sorted_camera_index_for_target 0叠在上面的相机→Some(BlendState::ALPHA_BLENDING)即 alpha 合成到底层之上CameraOutputMode::Write中已显式设置blend_state时一律以显式值为准不再自动检测。这就是混合 HDR 相机栈中上层相机不再覆盖下层输出的原因sorted_camera_index_for_target现在只按目标计数上层相机必然拿到 0的序号从而默认走 alpha 混合。恢复旧行为显式设置blend_state如果你依赖旧的上层相机覆盖replace下层输出语义——例如需要 HDR 相机把整帧结果整体替换到目标上——请在CameraOutputMode::Write中显式给出混合状态绕过自动检测。CameraOutputMode的定义位于 crates/bevy_camera/src/camera.rs#L860-L887pub enum CameraOutputMode { /// Writes the camera output to configured render target. Write { /// The blend state that will be used by the pipeline that writes the /// intermediate render textures to the final render target texture. blend_state: OptionBlendState, /// The clear color operation to perform on the final render target texture. clear_color: ClearColorConfig, }, /// Skips writing the camera output to the configured render target... Skip, }对应迁移示例以叠加在底层之上的相机为例// 迁移前blend_state 为 None旧版本下该上层相机可能按 replace 覆盖底层输出 CameraOutputMode::Write { blend_state: None, clear_color: ClearColorConfig::Default, } // 迁移后显式指定 REPLACE等价于保留旧的整块覆盖行为 CameraOutputMode::Write { blend_state: Some(BlendState::REPLACE), clear_color: ClearColorConfig::Default, }把blend_state设为Some(BlendState::REPLACE)或其他自定义BlendState后blit 将严格按照你指定的混合方式写回不再受自动检测影响。若你接受并希望保留新的合成语义则保持blend_state: None即可无需任何修改。新行为二SortedCamera::hdr已移除序号只按目标计数旧的SortedCameras资源中的相机条目曾暴露hdr字段。如今SortedCamera结构体只保留四个字段见 crates/bevy_render/src/camera.rs#L719-L728pub struct SortedCamera { pub entity: Entity, pub order: isize, pub target: OptionNormalizedRenderTarget, pub output_mode: CameraOutputMode, }对应地渲染世界中的提取组件ExtractedCamera仍同时携带 HDR 状态与每目标序号见 crates/bevy_render/src/camera.rs#L456-L471pub struct ExtractedCamera { // ... pub sorted_camera_index_for_target: usize, // ... pub hdr: bool, }因此任何在渲染世界render world中通过SortedCameras资源读取SortedCamera::hdr以判断某视图是否 HDR 的自定义系统都必须改写为直接查询对应视图实体上的ExtractedCamera组件并读取其hdr字段// 迁移前编译错误字段已移除 fn my_render_system(sorted: ResSortedCameras) { for cam in sorted.0 { if cam.hdr { // ... } } } // 迁移后从视图实体上读取 ExtractedCamera::hdr fn my_render_system(views: QueryExtractedCamera) { for camera in views { if camera.hdr { // ... } } }hdr字段本身没有消失只是迁移到了更合适的位置跟随视图实体的提取组件上。仓库内 Bloom、TAA、Tonemapping、Sprite/Mesh 2D/3D 等渲染路径例如 crates/bevy_post_process/src/bloom/mod.rs、crates/bevy_anti_alias/src/taa/mod.rs、crates/bevy_core_pipeline/src/tonemapping/node.rs均为从ExtractedCamera/视图查询中读取camera.hdr的既有范式可作为迁移参照。源码佐证测试确保混合 HDR 共享目标按序编号新语义由单元测试锁定位于 crates/bevy_render/src/camera.rs#L1201-L1225#[test] fn sort_cameras_assigns_sequential_indices_for_mixed_hdr_shared_target() { let shared NormalizedRenderTarget::TextureView(ManualTextureViewHandle(0)); let other NormalizedRenderTarget::TextureView(ManualTextureViewHandle(1)); // Spawn the upper camera first, so the indices prove camera order beats spawn order. let upper world.spawn(extracted_camera(1, true, shared.clone())).id(); let lower world.spawn(extracted_camera(0, false, shared)).id(); let solo world.spawn(extracted_camera(0, true, other)).id(); world.run_system_once(sort_cameras).unwrap(); // ... assert_eq!(index(lower), 0); // 底层非 HDR assert_eq!(index(upper), 1); // 上层HDR获得 0 序号 → blit 自动 alpha 混合 assert_eq!(index(solo), 0); // 独立目标上的相机仍是 0 }该测试明确了三点混合 HDR/非 HDR 的共享目标上序号从 0 连续分配序号由相机 order而非生成顺序决定独立目标上的相机始终为 0。此外sorted_camera_index_for_target还被每目标独立计数的下游解析器使用resolve_composition_spaces见 crates/bevy_render/src/view/composition.rs在把同一主纹理MainTextureKey下的视图分组解析合成色彩空间CompositingSpace时用该字段作为分组内排序键sorted_index见 crates/bevy_render/src/view/composition.rs#L89。其单测sorted_index_orders_the_group_not_insertion_ordercrates/bevy_render/src/view/composition.rs#L573-L584同样验证了按序号排序而非输入顺序说明序号已成为后续渲染阶段判定谁是底层相机的统一依据。迁移检查清单渲染世界自定义系统全文搜索对SortedCameras资源中SortedCamera条目的.hdr读取凡是编译报错处一律改为查询视图实体上的ExtractedCamera并读取其hdr。依赖覆盖语义的多相机 UI/HUD若上层相机需要整体替换目标上的既有内容为它的CameraOutputMode::Write显式设置blend_state: Some(BlendState::REPLACE)或其他目标混合状态避免自动 alpha 混合改变观感。单相机渲染无需改动其sorted_camera_index_for_target恒为0blit 仍按 replace 写入。统一 HDR 的相机栈栈内所有相机 HDR 设置一致时行为与迁移前一致无需改动只有同目标上 HDR 与非 HDR 相机混叠才会触发上述行为变化请按前两条核对代码。确认目标多样性如果同一应用把多组相机分别渲染到不同Image/TextureView/窗口注意序号是每个目标各自从 0 重新开始的不要跨目标比较或复用该序号。【免费下载链接】bevyA refreshingly simple>项目地址: https://gitcode.com/GitHub_Trending/be/bevy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考