鸿蒙开发-XEngine的Vulkan通用功能有哪些？基础设置和用法

XEngine Vulkan 通用模块结构体类型和同步机制在使用 XEngine 的 Vulkan 特性比如超分、VRS、光线追踪等时有一些通用的类型定义和工具函数是跨特性共用的。这篇文章就来梳理一下这些基础设施包括结构体类型枚举和同步信号机制。虽然这些内容看起来比较底层但理解它们对你正确使用 XEngine 的各个 Vulkan 特性很有帮助。XEG_StructureType告诉 Vulkan 你传的是什么结构体Vulkan 的设计哲学之一是可扩展性。它用sType字段来标识一个结构体的类型用pNext字段来链接扩展信息。XEngine 也遵循了这个设计定义了XEG_StructureType枚举来标识各种 XEngine 结构体的类型。下面的流程图展示了 XEG_StructureType 枚举与各特性的对应关系XEG_StructureType枚举RT ShadowAO: 0,1RT Reflection: 2,3NNGI神经网络光照: 4,5DDGI动态漫反射光照: 6,7HPS高性能着色器: 1001-1003CREATE_INFO: 创建参数DESCRIPTION: 渲染描述CREATE_INFO: 创建参数DESCRIPTION: 渲染描述CREATE_INFO: 创建参数DESCRIPTION: 渲染描述CREATE_INFO: 创建参数DESCRIPTION: 渲染描述CREATE_INFO: 创建参数RADIX_SORT: 排序结构RADIX_SORT_DESCRIPTION: 排序描述enumXEG_StructureType{// RT ShadowAO 相关XEG_STRUCTURE_TYPE_RT_SHADOWAO_CREATE_INFO0,XEG_STRUCTURE_TYPE_RT_SHADOWAO_DESCRIPTION1,// RT Reflection 相关XEG_STRUCTURE_TYPE_RT_REFLECTION_CREATE_INFO2,XEG_STRUCTURE_TYPE_RT_REFLECTION_DESCRIPTION3,// NNGI神经网络全局光照相关XEG_STRUCTURE_TYPE_NNGI_CREATE_INFO4,XEG_STRUCTURE_TYPE_NNGI_DESCRIPTION5,// DDGI动态漫反射全局光照相关XEG_STRUCTURE_TYPE_DDGI_CREATE_INFO6,XEG_STRUCTURE_TYPE_DDGI_DESCRIPTION7,// HPS高性能着色器相关XEG_STRUCTURE_TYPE_HPS_CREATE_INFO1001,XEG_STRUCTURE_TYPE_HPS_RADIX_SORT1002,XEG_STRUCTURE_TYPE_HPS_RADIX_SORT_DESCRIPTION1003};这些枚举值对应了 XEngine 各个特性的结构体。你在创建对象或者录制命令的时候需要在结构体的sType字段里填上对应的枚举值。举个例子如果你要使用 RT ShadowAO 特性创建信息结构体的sType应该设为XEG_STRUCTURE_TYPE_RT_SHADOWAO_CREATE_INFO如果是 RT 反射特性就用XEG_STRUCTURE_TYPE_RT_REFLECTION_CREATE_INFO。为什么这个很重要因为 XEngine 的很多接口接受的是void*指针比如HMS_XEG_CreateRTGI、HMS_XEG_CreateRTReflection等它需要通过sType来判断你传入的到底是哪种结构体。如果你填错了轻则功能异常重则崩溃。各枚举值对应哪些特性枚举值对应特性用途0, 1RT ShadowAO阴影环境光遮蔽创建信息 / 渲染描述2, 3RT Reflection光线追踪反射创建信息 / 渲染描述4, 5NNGI神经网络全局光照创建信息 / 渲染描述6, 7DDGI动态漫反射全局光照创建信息 / 渲染描述1001-1003HPS高性能着色器创建信息 / 排序结构 / 排序描述注意 HPS 的枚举值是从 1001 开始的和其他特性的编号不连续。这可能是为了预留空间给将来的特性。HMS_XEG_CmdSetSynchronization同步信号机制在使用某些 XEngine 特性特别是 RTGI 全局光照时渲染结果可能不是立即写入目标图像的。这时候你需要一个机制来等待结果写入完成。HMS_XEG_CmdSetSynchronization就是用来做这个的。VkResult resultHMS_XEG_CmdSetSynchronization(commandBuffer,rtgiHandle);这个函数有两个参数commandBuffer当前的VkCommandBuffer必须提交到vkQueueSubmit才会执行。xegHandle已创建的句柄对象。当前这个接口主要用在 RTGI 特性中传入的是XEG_RTGI对象。返回值是VkResultVK_SUCCESS表示成功。为什么需要同步打个比方你在渲染管线里调用了 RTGI 来计算全局光照但 GI 的计算是异步的——它可能在你的其他渲染命令执行的同时也在跑。当你需要使用 GI 结果的时候比如在后续的合成步骤中你需要确保 GI 计算已经完成并且结果已经写入了目标图像。HMS_XEG_CmdSetSynchronization的作用就是在命令缓冲里插入一个等待点。GPU 执行到这里的时候会等待 GI 结果写入完成然后才继续执行后面的命令。典型使用场景下面的流程图展示了同步信号机制在渲染管线中的作用录制RTGI渲染命令RTGI异步计算全局光照录制同步等待命令GPU等待GI结果写入完成GI结果可安全读取录制后续合成命令使用GI结果进行最终渲染提交命令缓冲执行// 录制 RTGI 渲染命令HMS_XEG_CmdRenderRTGI(commandBuffer,rtGI,rtgiDescription);// 设置同步信号等待 GI 结果写入目标图像HMS_XEG_CmdSetSynchronization(commandBuffer,rtGI);// 后续命令使用 GI 结果进行合成// ... 此时 GI 结果已经可以安全读取了这个接口的起始版本是 6.0.0(20)是和 RTGI 特性一起引入的。整体架构理解把XEG_StructureType和HMS_XEG_CmdSetSynchronization放到 XEngine 的整体架构里看结构体类型是元数据——它告诉 XEngine 你传入的数据是什么格式这样 XEngine 才能正确解析。同步机制是协调器——它确保不同的 GPU 任务按照正确的顺序执行避免读写冲突。这两个东西你可能不会直接在业务代码里用到太多但它们是 XEngine 各个特性的地基。理解了它们再去看各个特性的具体接口就会更清晰。使用建议结构体类型别填错这是一条血泪教训。每个 XEngine 特性的创建信息和描述信息都有对应的sType填错了就是未定义行为。建议用宏定义或者枚举来管理不要硬编码数字。同步只在需要时用不是所有特性都需要手动同步。当前文档里明确提到需要同步的场景是 RTGI。如果你用的是超分或者 VRS 这些同步特性一般不需要手动管理同步。注意版本要求HMS_XEG_CmdSetSynchronization和XEG_StructureType都是 6.0.0(20) 版本引入的。如果你的目标设备运行的是更早的系统版本可能没有这些接口。这些通用模块虽然不直接产生画面效果但它们是让 XEngine 各个特性正确运行的幕后英雄。