Ray-Traced Reflections

Since version 6.0.0(20), the Ray-Traced Reflections feature is supported.

XEngine Kit provides the Ray-Traced Reflections rendering capability. Compared with traditional ray tracing implementations of this effect, XEngine Kit leverages hardware-software co-optimization on the Maleoon GPU to support the flexible entry ray tracing (FERT) intersection acceleration technology. This reduces the number of ray-geometry intersection calculations, thereby lowering GPU workload while delivering high-quality ray tracing effects.

Constraints

Supported devices: This capability can be used on devices that support Vulkan ray tracing extensions VK_KHR_acceleration_structure and VK_KHR_ray_query.
You can check whether the relevant extension is supported as follows:

For Vulkan, use the extension query API HMS_XEG_EnumerateDeviceExtensionProperties. If the query result contains XEG_RT_REFLECTION_EXTENSION_NAME, the extension is supported. Otherwise, the extension is not supported.

API Description

The following APIs are required for Ray-Traced Reflections. For details about these APIs, please refer to API Reference.

API	Description
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_EnumerateDeviceExtensionProperties (VkPhysicalDevice physicalDevice, uint32_t * pPropertyCount, XEG_ExtensionProperties * pProperties)	Queries Vulkan extensions of XEngine Kit.
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateRTReflection(VkDevice device, const void* pCreateInfo, XEG_RTReflection* pRtReflection)	Creates an XEG_RTReflection object.
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRenderRTReflection(VkCommandBuffer commandBuffer, XEG_RTReflection rtReflection, const void* pDescription)	Records the command for computing the ray-traced reflection hit information.
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyRTReflection(XEG_RTReflection rtReflection)	Destroys an XEG_RTReflection object.

Service Process

When a user enters the game scene, call the HMS_XEG_EnumerateDeviceExtensionProperties API to query the list of features supported by XEngine Kit.
Check whether the returned list contains XEG_RT_REFLECTION_EXTENSION_NAME. If not, the current device does not support this feature, and the process ends.
Call the HMS_XEG_CreateRTReflection API to create a ray-traced reflection instance.
Call the HMS_XEG_CmdRenderRTReflection API to calculate the ray-traced reflection hit information.
Generate a reflection image based on the reflection hit information computed in step 4.
Blend the reflection image with the rendering result of the main scene of the game.
Continue with the subsequent rendering steps, such as drawing UI elements. Perform the final presentation operation after the frame rendering is completed.
When the game exits, calls the HMS_XEG_DestroyRTReflection API to destroy the ray-traced reflection instance.

Development Procedure

This section uses the Vulkan app as an example to describe the XEngine Kit integration process.

[h2]Configuring Your Project

During HAP compilation, the native layer's .so files must be built with a dependency on libxengine.so from the NDK.

Header file reference

#include "xengine/xeg_vulkan_extension.h"
// ...
#include "xengine/xeg_vulkan_rt_reflection.h"

CMakeLists.txt configuration

The following is part of the sample code of the CMakeLists.txt file:

find_library(
    # Set the name of the path variable.
    xengine-lib
    # Specify the name of the NDK library that you want CMake to locate.
    xengine
)

target_link_libraries(nativerender PUBLIC
    # ...
    ${xengine-lib}
)

[h2]Integrating Ray-Traced Reflections of XEngine Kit (Vulkan)

Vulkan graphics APIs are used to set up the image rendering pipeline and integrate Ray-Traced Reflections at the native layer. The rendering results are displayed on the screen through XComponent.

Before calling XEngine Kit capabilities, you need to use SysCap to check whether your target device supports the SystemCapability.Graphic.XEngine system capability.

Call HMS_XEG_EnumerateDeviceExtensionProperties to obtain the extensions supported by XEngine Kit. The Ray-Traced Reflections APIs can be used only when the XEG_RT_REFLECTION_EXTENSION_NAME extension is supported.

// Query the Vulkan extensions supported by XEngine Kit.
std::vector<std::string> supportedExtensions;
uint32_t propertyCount;
// physicalDevice indicates a Vulkan physical device. You need to initialize it.
HMS_XEG_EnumerateDeviceExtensionProperties(physicalDevice, &propertyCount, nullptr);
if (propertyCount > 0) {
    std::vector<XEG_ExtensionProperties> properties(propertyCount);
    if (HMS_XEG_EnumerateDeviceExtensionProperties(physicalDevice, &propertyCount, &properties.front()) ==
        VK_SUCCESS) {
        for (auto ext : properties) {
            supportedExtensions.push_back(ext.extensionName);
        }
    }
}
// ...
// Query whether the Ray-Traced Reflections extension is supported.
if (std::find(supportedExtensions.begin(), supportedExtensions.end(), XEG_RT_REFLECTION_EXTENSION_NAME) ==
    supportedExtensions.end()) {
    // Handle the error.
    // ...
}

Declare the instance handle.

XEG_RTReflection rtReflection = VK_NULL_HANDLE;

Call the HMS_XEG_CreateRTReflection API to create a ray-traced reflection instance.

// XEG_RTReflectionCreateInfo indicates the information required for creating an rtReflection object.
XEG_RTReflectionCreateInfo xegRTReflectionCreateInfo;
// Set whether to enable the fast intersection mode. The value 1 indicates that the mode is enabled.
xegRTReflectionCreateInfo.enableFastTrace = 1;
xegRTReflectionCreateInfo.pNext = nullptr;
// Set XEG_StructureType. The value must be XEG_STRUCTURE_TYPE_RT_REFLECTION_CREATE_INFO.
xegRTReflectionCreateInfo.sType = XEG_STRUCTURE_TYPE_RT_REFLECTION_CREATE_INFO;
// Specify the dimensions of the input image.
// The width and height information (reflectionWidth and reflectionHeight) required for creating a ray-traced reflection instance are custom parameters.
xegRTReflectionCreateInfo.renderSize = VkExtent2D{ reflectionWidth, reflectionHeight };
// ...
VkResult ret = HMS_XEG_CreateRTReflection(device, &xegRTReflectionCreateInfo, &rtReflection);
if (ret != VK_SUCCESS) {
    // Handle the error.
    // ...
}

Call HMS_XEG_CmdRenderRTReflection for each frame to deliver the rendering command.

// Input information for reflection rendering.
XEG_RTReflectionDescription xegRTReflectionDescription;
xegRTReflectionDescription.pNext = nullptr;
// rayOriginImage.view indicates the VkImageView of the ray origin image you have created.
xegRTReflectionDescription.inputRayOriginImage = rayOriginImage.view;
// rayDirection.view indicates the VkImageView of the ray direction image you have created.
xegRTReflectionDescription.inputRayDirectionImage = rayDirection.view;
// reflectionOutput.view indicates the VkImageView for recording the ray tracing intersection result. You need to create this VkImageView.
xegRTReflectionDescription.outputReflectionInfoImage = reflectionOutput.view;
// accelerationStructureBuilder.getTlas() indicates the top-level ray tracing acceleration structure of the scene.
xegRTReflectionDescription.accelerationStructure = accelerationStructureBuilder.getTlas();
xegRTReflectionDescription.rayMin = 0.01;
xegRTReflectionDescription.rayMax = 1e10;
xegRTReflectionDescription.sType = XEG_STRUCTURE_TYPE_RT_REFLECTION_DESCRIPTION;
xegRTReflectionDescription.reflectionCullMask = 0xff;
// drawCmdBuffers[currentBuffer] indicates the command buffer and needs to be initialized.
VkResult ret = HMS_XEG_CmdRenderRTReflection(
    drawCmdBuffers[currentBuffer], rtReflection, &xegRTReflectionDescription);
if (ret != VK_SUCCESS) {
    // Handle the error.
    // ...
}

Call HMS_XEG_DestroyRTReflection to destroy the instance and release resources when the extension is no longer used or the app exits.
```
HMS_XEG_DestroyRTReflection(rtReflection);
```