Overview
Provides APIs related to XEngine graphics capabilities.
System capability: SystemCapability.Graphic.XEngine
Since: 5.0.0(12)
[h2]Files
| Name | Description |
|---|---|
| xeg_extension_defs.h | Macro definitions of XEngine extensions. |
| xeg_gles_adaptive_vrs.h | GLES APIs for the XEngine adaptive variable rate shading (VRS) feature. Before using the APIs in this header file, you need to call the HMS_XEG_GetString API to check whether the XEG_ADAPTIVE_VRS_EXTENSION_NAME extension is available. |
| xeg_gles_extension.h | OpenGL ES APIs for querying XEngine extensions. |
| xeg_gles_neural_upscale.h | OpenGL ES APIs for the AI spatial upscaling of XEngine. Before using the APIs in this header file, you need to call the HMS_XEG_GetString API to check whether the XEG_NEURAL_UPSCALE_EXTENSION_NAME or XEG_NEURAL_UPSCALE2_EXTENSION_NAME extension is available. |
| xeg_gles_spatial_upscale.h | OpenGL ES APIs for the GPU spatial upscaling of XEngine. Before using the APIs in this header file, you need to call the HMS_XEG_GetString API to check whether the XEG_SPATIAL_UPSCALE_EXTENSION_NAME extension is available. |
| xeg_gles_temporal_upscale.h | OpenGL ES APIs for the AI temporal upscaling of XEngine. The recommended upscaling factor is [1.25, 2.0]. Before using the APIs in this header file, you need to call the HMS_XEG_GetString API to check whether the XEG_TEMPORAL_UPSCALE_EXTENSION_NAME extension is available. |
| xeg_vulkan_adaptive_vrs.h | Vulkan APIs for the XEngine adaptive VRS feature. Before using the APIs in this header file, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_ADAPTIVE_VRS_EXTENSION_NAME extension is available. |
| xeg_vulkan_common.h | Common type definitions related to Vulkan in XEngine. |
| xeg_vulkan_extension.h | XEngine extension query APIs (Vulkan). |
| xeg_vulkan_hps.h | XEngine high-performance shader APIs. Before using the APIs in this header file, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension is available. |
| xeg_vulkan_rt_reflection.h | XEngine Ray-Traced Reflection feature APIs. Before using the APIs in this header file, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_RT_REFLECTION_EXTENSION_NAME extension is available. |
| xeg_vulkan_rt_visible_mask.h | XEngine Ray-Traced VisibleMask (Ray-Traced Shadow and Ambient Occlusion) feature APIs. Before using the APIs in this header file, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_RT_SHADOW_AO_EXTENSION_NAME extension is available. |
| xeg_vulkan_rtgi.h | Vulkan APIs for the Ray-Traced Global Illumination of XEngine, which provide two features: dynamic diffusion global illumination (DDGI) and neural network global illumination (NNGI). Before using the APIs in this header file, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_RTGI_EXTENSION_NAME extension is available. |
| xeg_vulkan_spatial_upscale.h | Vulkan APIs for the GPU spatial upscaling of XEngine. Before using the APIs in this header file, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_SPATIAL_UPSCALE_EXTENSION_NAME extension is available. |
| xeg_vulkan_temporal_upscale.h | APIs for the AI temporal upscaling of XEngine. The recommended upscaling factor is [1.25, 2.0]. Before using the APIs in this header file, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_TEMPORAL_UPSCALE_EXTENSION_NAME extension is available. |
| xeg_vulkan_neural_upscale.h | Vulkan APIs for the AI spatial upscaling of XEngine. Before using the APIs in this header file, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_NEURAL_UPSCALE_EXTENSION_NAME extension is available. |
| xeg_control_display_separation.h | APIs for the control-display separation feature of XEngine. |
[h2]Structs
| Name | Description |
|---|---|
| struct XEG_AdaptiveVRSCreateInfo | Describes the parameters for creating an XEG_AdaptiveVRS object. When the information in the struct changes, a new XEG_AdaptiveVRS object needs to be created. |
| struct XEG_AdaptiveVRSDescription | Describes the parameter information required for delivering the command for drawing the shading rate texture. The information needs to be updated for each frame. |
| struct XEG_ExtensionProperties | Describes the XEngine extension set obtained through the HMS_XEG_EnumerateDeviceExtensionProperties API. |
| struct XEG_HPSCreateInfo | Describes the information about creating an XEG_HPS object. |
| struct XEG_HPSRadixSort | Describes the HPS radix sort extension structure information. |
| struct XEG_HPSRadixSortDescription | Describes the information required when the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension is used for sorting. |
| struct XEG_RTReflectionCreateInfo | Describes the information about creating an XEG_RTReflection object. When the information in the struct changes, a new XEG_RTReflection object needs to be created. |
| struct XEG_RTReflectionDescription | Describes the input information for sending a ray intersection command. |
| struct XEG_RTShadowAOCreateInfo | Describes the initialization information for creating an XEG_RTVisibleMask instance that supports the Ray-Traced Shadow and Ambient Occlusion effects. When the information in the struct changes, a new XEG_RTVisibleMask object needs to be created. |
| struct XEG_RTShadowParameters | Ray-Traced Shadow (Shadow) algorithm parameters. |
| struct XEG_RTAOParameters | Ray-Traced Ambient Occlusion (AO) algorithm parameters. |
| struct XEG_RTShadowAODenoiserParameters | Denoising parameters for the Ray-Traced Shadow and Ambient Occlusion algorithms. |
| struct XEG_RTShadowAODescription | Describes the input information of the rendering command for the Ray-Traced Shadow and Ambient Occlusion algorithms. |
| struct XEG_DDGIVolumeEntryParameters | Describes the mandatory parameters of each DDGI volume. |
| struct XEG_DDGICreateInfo | Describes the information required for creating an XEG_RTGI object with the DDGI feature. When the information in the struct changes, a new XEG_RTGI object needs to be created. |
| struct XEG_DDGIDescription | Describes the information required for updating the DDGI probe irradiance and rendering the output GI images. |
| struct XEG_NNGICreateInfo | Describes the information required for creating an XEG_RTGI object with the NNGI feature. When the information in the struct changes, a new XEG_RTGI object needs to be created. |
| struct XEG_NNGIDescription | Describes the information required for updating the NNGI to compute the Ray-Traced Global Illumination. |
| struct XEG_SpatialUpscaleCreateInfo | Describes the information required for creating an XEG_SpatialUpscale object. When the information in the struct changes, a new XEG_SpatialUpscale object needs to be created. |
| struct XEG_SpatialUpscaleDescription | Describes the image information required for delivering the GPU spatial upscaling rendering command. |
| struct XEG_TemporalUpscaleCreateInfo | Describes the information about creating an XEG_TemporalUpscale object. When the information in the struct changes, a new XEG_TemporalUpscale object needs to be created. |
| struct XEG_TemporalUpscaleDescription | Describes the input information when the AI temporal upscaling rendering command is delivered. |
| struct XEG_NeuralUpscaleCreateInfo | Describes the information about creating an XEG_NeuralUpscale object. When the information in the struct changes, a new XEG_NeuralUpscale object needs to be created. |
| struct XEG_NeuralUpscaleDescription | Describes the input information when the AI spatial upscaling rendering command is delivered. |
[h2]Macros
| Name | Description |
|---|---|
| XEG_spatial_upscale 1 | Extension macro definition of GPU spatial upscaling of XEngine. |
| XEG_SPATIAL_UPSCALE_VERSION 1 | Extension version number of GPU spatial upscaling of XEngine. |
| XEG_SPATIAL_UPSCALE_EXTENSION_NAME "XEG_spatial_upscale" | Extension name of GPU spatial upscaling of XEngine. |
| XEG_neural_upscale 1 | Extension macro definition of AI spatial upscaling of XEngine. |
| XEG_NEURAL_UPSCALE_VERSION 1 | Extension version number of AI spatial upscaling of XEngine. |
| XEG_NEURAL_UPSCALE_EXTENSION_NAME "XEG_neural_upscale" | Extension name of AI spatial upscaling of XEngine. |
| XEG_NEURAL_UPSCALE2_EXTENSION_NAME "XEG_neural_upscale2" | Extension name of AI spatial upscaling (version 2) of XEngine. |
| XEG_temporal_upscale 1 | Extension macro definition of AI temporal upscaling of XEngine. |
| XEG_TEMPORAL_UPSCALE_VERSION 1 | Extension version number of AI temporal upscaling of XEngine. |
| XEG_TEMPORAL_UPSCALE_EXTENSION_NAME "XEG_temporal_upscale" | Extension name of AI temporal upscaling of XEngine. |
| XEG_adaptive_vrs 1 | Macro definition of the XEngine adaptive VRS extension. |
| XEG_ADAPTIVE_VRS_VERSION 1 | Version number of the XEngine adaptive VRS extension. |
| XEG_ADAPTIVE_VRS_EXTENSION_NAME "XEG_adaptive_vrs" | XEngine adaptive VRS extension name. |
| XEG_RTGI_EXTENSION_NAME "XEG_rtgi" | Extension name of Ray-Traced Global Illumination of XEngine. |
| XEG_RT_SHADOW_AO_EXTENSION_NAME "XEG_rt_shadow_ao" | Extension name of Ray-Traced Shadow and Ambient Occlusion of XEngine. |
| XEG_RT_REFLECTION_EXTENSION_NAME "XEG_rt_reflection" | Extension name of Ray-Traced Reflections of XEngine. |
| XEG_HPS_RADIX_SORT_EXTENSION_NAME "XEG_hps_radix_sort" | Extension name of High-Performance Radix Sort of XEngine. |
| XEG_ADAPTIVE_VRS_INPUT_SIZE 0x1U | Sets the INPUT_SIZE parameter of the HMS_XEG_AdaptiveVRSParameter API, which indicates the image width and height finally rendered by the rendering pipeline of the previous frame. |
| XEG_ADAPTIVE_VRS_INPUT_REGION 0x2U | Sets the INPUT_REGION parameter of the HMS_XEG_AdaptiveVRSParameter API, which indicates the image region finally rendered by the rendering pipeline of the previous frame. |
| XEG_ADAPTIVE_VRS_TEXEL_SIZE 0x3U | Sets the TEXEL_SIZE parameter of the HMS_XEG_AdaptiveVRSParameter API. |
| XEG_ADAPTIVE_VRS_ERROR_SENSITIVITY 0x4U | Sets the ERROR_SENSITIVITY parameter of the HMS_XEG_AdaptiveVRSParameter API, which indicates the threshold for generating the shading rate image. A larger value indicates a smaller average shading rate, that is, the performance is better but the image quality deteriorates. The recommended value range is [0.0, 1.0]. |
| XEG_ADAPTIVE_VRS_FLIP 0x5U | Sets the FLIP parameter of the HMS_XEG_AdaptiveVRSParameter API. This parameter is used to control whether to flip an image up and down. |
| XEG_EXTENSIONS 0x01U | Serves as an input parameter of the HMS_XEG_GetString API to obtain the OpenGL ES extensions supported by XEngine. |
| XEG_NEURAL_UPSCALE_SCISSOR 0x1U | Sets the upscaling cropping window parameters through the HMS_XEG_NeuralUpscaleParameter API. The cropping window is used to determine the area where the input image is sampled. |
| XEG_NEURAL_UPSCALE_SHARPNESS 0x2U | Sets the upscaling sharpening parameters through the HMS_XEG_NeuralUpscaleParameter API. The recommended value range is [0.0, 1.0]. |
| XEG_NEURAL_UPSCALE_INPUT_HANDLE 0x4U | Sets the OH_NativeBuffer handle associated with the upscaling input texture through the HMS_XEG_NeuralUpscaleParameter API. |
| XEG_SPATIAL_UPSCALE_SCISSOR 0x1U | Sets the SCISSOR parameter of the HMS_XEG_SpatialUpscaleParameter API. |
| XEG_SPATIAL_UPSCALE_SHARPNESS 0x2U | Sets the SHARPNESS parameter of the HMS_XEG_SpatialUpscaleParameter API. |
| XEG_TEMPORAL_UPSCALE_INPUT_SIZE 0x1U | Sets the actual width and height of the upscaling input texture through the HMS_XEG_TemporalUpscaleParameter API. |
| XEG_TEMPORAL_UPSCALE_JITTER_NUM 0x2U | Sets the number of camera jitter cycles through the HMS_XEG_TemporalUpscaleParameter API. The value range is [4, 16]. The recommended value is 8. |
| XEG_TEMPORAL_UPSCALE_DEPTH_REVERSED 0x3U | Sets whether depth reversion exists through the HMS_XEG_TemporalUpscaleParameter API. The value true indicates that depth reversion exists, and the value false indicates that depth reversion does not exist. |
| XEG_TEMPORAL_UPSCALE_RESET_HISTORY 0x4U | Sets whether to reset historical frame data through the HMS_XEG_TemporalUpscaleParameter API. The value true indicates that the data is reset, and the value false indicates that the data is not reset. The value true is recommended if upscaling is not used for historical frames but is used for the current frame. |
| XEG_TEMPORAL_UPSCALE_STEADY_LEVEL 0x5U | Sets whether the picture is biased towards the current frame (less ghosting but more flickering) or historical frames (more ghosting but more stable) through the HMS_XEG_TemporalUpscaleParameter API. The value range is [0.0, 1.0]. If the value is not within this range, undefined behavior may occur, such as incorrect rendering effect or program crash. A larger value indicates a stronger bias towards historical frames. You are advised to select a proper value based on actual requirements. For example, you can set this parameter to a smaller value to reduce ghosting, or set it to a larger value to reduce flickering. The recommended value is 0.5. |
| XEG_MAX_EXTENSION_NAME_SIZE 256 | Maximum length of the XEngine extension name. |
[h2]Types
| Name | Description |
|---|---|
| typedef void(GL_APIENTRYP PFN_HMS_XEG_ADAPTIVEVRSPARAMETER) (GLenum pname, GLvoid *param) | Defines the function pointer for setting the input parameters of adaptive VRS. |
| typedef void(GL_APIENTRYP PFN_HMS_XEG_DISPATCHADAPTIVEVRS) (GLfloat *reprojectionMatrix, GLuint inputColorImage, GLuint inputDepthImage, GLuint shadingRateImage) | Defines the function pointer for computing the shading rate image. |
| typedef void(GL_APIENTRYP PFN_HMS_XEG_APPLYADAPTIVEVRS) (GLuint shadingRateImage) | Defines the function pointer for applying the shading rate image to the render target. |
| typedef const GLubyte *(GL_APIENTRYP PFN_HMS_XEG_GETSTRING) (GLenum name) | Defines the function pointer for querying the XEngine OpenGL ES extensions. |
| typedef void(GL_APIENTRYP PFN_HMS_XEG_NEURALUPSCALEPARAMETER) (GLenum pname, GLvoid *param) | Defines the function pointer for setting the input parameters of AI spatial upscaling. |
| typedef void(GL_APIENTRYP PFN_HMS_XEG_RENDERNEURALUPSCALE) (GLuint inputTexture) | Defines the function pointer for executing the rendering command for AI spatial upscaling. |
| typedef void(GL_APIENTRYP PFN_HMS_XEG_SPATIALUPSCALEPARAMETER) (GLenum pname, GLvoid *param) | Defines the function pointer for setting the input parameters of GPU spatial upscaling. |
| typedef void(GL_APIENTRYP PFN_HMS_XEG_RENDERSPATIALUPSCALE) (GLuint inputTexture) | Defines the function pointer for executing the rendering command for GPU spatial upscaling. |
| typedef void(GL_APIENTRYP PFN_HMS_XEG_TemporalUpscaleParameter) (GLenum pname, GLvoid *param) | Defines the function pointer for setting the input parameters of AI temporal upscaling. |
| typedef void(GL_APIENTRYP PFN_HMS_XEG_RenderTemporalUpscale) (GLuint inputTexture, GLuint depthTexture, GLuint motionVectorTexture, GLuint dynamicMaskTexture, GLfloat jitterX, GLfloat jitterY) | Defines the function pointer for executing the rendering command for AI temporal upscaling. |
| VK_DEFINE_HANDLE(XEG_AdaptiveVRS) | Handle to XEG_AdaptiveVRS. |
| typedef struct XEG_AdaptiveVRSCreateInfo XEG_AdaptiveVRSCreateInfo | Describes the parameters for creating an XEG_AdaptiveVRS object. When the information in the struct changes, a new XEG_AdaptiveVRS object needs to be created. |
| typedef struct XEG_AdaptiveVRSDescription XEG_AdaptiveVRSDescription | Describes the parameter information required for delivering the command for drawing the shading rate texture. The information needs to be updated for each frame. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CreateAdaptiveVRS) (VkDevice device, const XEG_AdaptiveVRSCreateInfo *pXegAdaptiveVRSCreateInfo, XEG_AdaptiveVRS *pXegAdaptiveVRS) | Defines the function pointer for creating an XEG_AdaptiveVRS object. |
| typedef void(VKAPI_PTR * PFN_HMS_XEG_CmdDispatchAdaptiveVRS) (VkCommandBuffer commandBuffer, XEG_AdaptiveVRS xegAdaptiveVRS, XEG_AdaptiveVRSDescription *pXegAdaptiveVRSDescription) | Defines the function pointer for executing a command for computing the adaptive VRS. |
| typedef void(VKAPI_PTR * PFN_HMS_XEG_DestroyAdaptiveVRS) (XEG_AdaptiveVRS xegAdaptiveVRS) | Defines the function pointer for destroying an XEG_AdaptiveVRS object. |
| typedef enum XEG_StructureType XEG_StructureType | Enumerates XEngine struct types. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CmdSetSynchronization) (VkCommandBuffer commandBuffer, const void *xegHandle) | Defines the function pointer for setting synchronization signals and waiting for the rendering result to be written to a specified image. When the RTGI feature is used, it is the GI rendering result that needs to be waited for before being written to a specified image. |
| typedef struct XEG_ExtensionProperties XEG_ExtensionProperties | Describes the XEngine extension set obtained through the HMS_XEG_EnumerateDeviceExtensionProperties API. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_EnumerateDeviceExtensionProperties) (VkPhysicalDevice physicalDevice, uint32_t *pPropertyCount, XEG_ExtensionProperties *pProperties) | Defines the function pointer for querying the XEngine Vulkan extensions. |
| VK_DEFINE_HANDLE(XEG_HPS) | Handle to XEG_HPS. |
| typedef struct XEG_HPSCreateInfo XEG_HPSCreateInfo | Describes the information about creating an XEG_HPS object. |
| typedef struct XEG_HPSRadixSort XEG_HPSRadixSort | Describes the HPS radix sort extension structure information. |
| typedef struct XEG_HPSRadixSortDescription XEG_HPSRadixSortDescription | Describes the information required when the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension is used for sorting. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CreateHPS) (VkDevice device, const XEG_HPSCreateInfo *pCreateInfo, XEG_HPS *pHps) | Defines the function pointer for creating an XEG_HPS object. |
| typedef void(VKAPI_PTR * PFN_HMS_XEG_DestroyHPS) (XEG_HPS hps) | Defines the function pointer for destroying an XEG_HPS object. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CmdRadixSortHPS) (VkCommandBuffer commandBuffer, XEG_HPS hps, const XEG_HPSRadixSortDescription *pDescription) | Defines the function pointer for recording the HPS sorting command. Before using this API, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension is supported. |
| VK_DEFINE_HANDLE(XEG_RTReflection) | Handle to XEG_RTReflection. |
| typedef struct XEG_RTReflectionCreateInfo XEG_RTReflectionCreateInfo | Describes the information about creating an XEG_RTReflection object. When the information in the struct changes, a new XEG_RTReflection object needs to be created. |
| typedef struct XEG_RTReflectionDescription XEG_RTReflectionDescription | Describes the input information for sending a ray intersection command. |
| typedef VkResult(VKAPI_ATTR * PFN_HMS_XEG_CreateRTReflection) (VkDevice device, const void *pCreateInfo, XEG_RTReflection *pRtReflection) | Defines the function pointer for creating an XEG_RTReflection object. |
| typedef VkResult(VKAPI_ATTR * PFN_HMS_XEG_CmdRenderRTReflection) (VkCommandBuffer commandBuffer, XEG_RTReflection rtReflection, const void *pDescription) | Defines the function pointer for recording the command for computing the RT reflection hit information. |
| typedef void(VKAPI_ATTR * PFN_HMS_XEG_DestroyRTReflection) (XEG_RTReflection rtReflection) | Defines the function pointer for destroying an XEG_RTReflection object. |
| VK_DEFINE_HANDLE(XEG_RTVisibleMask) | Handle to XEG_RTVisibleMask, which indicates the ray-traced VisibleMask feature instance. The Shadow and Ambient Occlusion effects are supported. |
| typedef enum XEG_DenoiseQualityMode XEG_DenoiseQualityMode | Enumerates denoising quality modes. |
| typedef enum XEG_TraversalMode XEG_TraversalMode | Enumerates traversal modes. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CreateRTVisibleMask) (VkDevice device, const void *pCreateInfo, XEG_RTVisibleMask *pRTVisibleMask) | Defines the function pointer for creating an XEG_RTVisibleMask object. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CmdRenderRTVisibleMask) (VkCommandBuffer commandBuffer, XEG_RTVisibleMask rtVisibleMask, const void *pDescription) | Defines the function pointer for recording the ray-traced VisibleMask rendering command. |
| typedef void(VKAPI_PTR * PFN_HMS_XEG_DestroyRTVisibleMask) (XEG_RTVisibleMask rtVisibleMask) | Defines the function pointer for destroying an XEG_RTVisibleMask object. |
| VK_DEFINE_HANDLE(XEG_RTGI) | Handle to XEG_RTGI. |
| typedef enum XEG_RTGIQualityMode XEG_RTGIQualityMode | Enumerates output image quality modes. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CreateRTGI) (VkDevice device, const void *pCreateInfo, XEG_RTGI *pRtGI) | Defines the function pointer for creating an XEG_RTGI object. |
| typedef void(VKAPI_PTR * PFN_HMS_XEG_DestroyRTGI) (XEG_RTGI rtGI) | Defines the function pointer for destroying an XEG_RTGI object. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CmdRenderRTGI) (VkCommandBuffer commandBuffer, XEG_RTGI rtGI, const void *pDescription) | Defines the function pointer for executing a rendering command. |
| VK_DEFINE_HANDLE(XEG_SpatialUpscale) | Handle to XEG_SpatialUpscale. |
| typedef struct XEG_SpatialUpscaleCreateInfo XEG_SpatialUpscaleCreateInfo | Describes the information required for creating an XEG_SpatialUpscale object. When the information in the struct changes, a new XEG_SpatialUpscale object needs to be created. |
| typedef struct XEG_SpatialUpscaleDescription XEG_SpatialUpscaleDescription | Describes the image information required for delivering the GPU spatial upscaling rendering command. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CreateSpatialUpscale) (VkDevice device, const XEG_SpatialUpscaleCreateInfo *pXegSpatialUpscaleCreateInfo, XEG_SpatialUpscale *pXegSpatialUpscale) | Defines the function pointer for creating an XEG_SpatialUpscale object. |
| typedef void(VKAPI_PTR * PFN_HMS_XEG_CmdRenderSpatialUpscale) (VkCommandBuffer commandBuffer, XEG_SpatialUpscale xegSpatialUpscale, XEG_SpatialUpscaleDescription *pXegSpatialUpscaleDescription) | Defines the function pointer for executing the rendering command for GPU spatial upscaling. |
| typedef void(VKAPI_PTR * PFN_HMS_XEG_DestroySpatialUpscale) (XEG_SpatialUpscale xegSpatialUpscale) | Defines the function pointer for destroying the XEG_SpatialUpscale object. |
| VK_DEFINE_HANDLE(XEG_TemporalUpscale) | Handle to XEG_TemporalUpscale. |
| typedef struct XEG_TemporalUpscaleCreateInfo XEG_TemporalUpscaleCreateInfo | Describes the information about creating an XEG_TemporalUpscale object. When the information in the struct changes, a new XEG_TemporalUpscale object needs to be created. |
| typedef struct XEG_TemporalUpscaleDescription XEG_TemporalUpscaleDescription | Describes the input information when the AI temporal upscaling rendering command is delivered. |
| typedef VkResult(VKAPI_ATTR * PFN_HMS_XEG_CreateTemporalUpscale) (VkDevice device, XEG_TemporalUpscaleCreateInfo *pTemporalUpscaleInfo, XEG_TemporalUpscale *pTemporalUpscale) | Defines the function pointer for creating an XEG_TemporalUpscale object. |
| typedef void(VKAPI_ATTR * PFN_HMS_XEG_CmdRenderTemporalUpscale) (VkCommandBuffer commandBuffer, XEG_TemporalUpscale temporalUpscale, XEG_TemporalUpscaleDescription *pDescription) | Defines the function pointer for recording the rendering command for AI temporal scaling. |
| typedef void(VKAPI_ATTR * PFN_HMS_XEG_DestroyTemporalUpscale) (XEG_TemporalUpscale temporalUpscale) | Defines the function pointer for destroying an XEG_TemporalUpscale object. |
| VK_DEFINE_HANDLE(XEG_NeuralUpscale) | Handle to XEG_NeuralUpscale. |
| typedef struct XEG_NeuralUpscaleCreateInfo XEG_NeuralUpscaleCreateInfo | Describes the information about creating an XEG_NeuralUpscale object. When the information in the struct changes, a new XEG_NeuralUpscale object needs to be created. |
| typedef struct XEG_NeuralUpscaleDescription XEG_NeuralUpscaleDescription | Describes the input information when the AI spatial upscaling rendering command is delivered. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CreateNeuralUpscale) (VkDevice device, const XEG_NeuralUpscaleCreateInfo *pCreateInfo, XEG_NeuralUpscale *pNeuralUpscale) | Defines the function pointer for creating an XEG_NeuralUpscale object. |
| typedef VkResult(VKAPI_PTR * PFN_HMS_XEG_CmdRenderNeuralUpscale) (VkCommandBuffer commandBuffer, XEG_NeuralUpscale neuralUpscale, const XEG_NeuralUpscaleDescription *pDescription) | Defines the function pointer for recording the rendering command for AI spatial scaling. |
| typedef void(VKAPI_PTR * PFN_HMS_XEG_DestroyNeuralUpscale) (XEG_NeuralUpscale neuralUpscale) | Defines the function pointer for destroying an XEG_NeuralUpscale object. |
| typedef enum XEG_ControlDisplaySeparationStatus XEG_ControlDisplaySeparationStatus | Describes the current status information of the control-display separation feature. |
| typedef void(*PFN_HMS_XEG_ControlDisplaySeparationStatusCallback) (XEG_ControlDisplaySeparationStatus status) | Defines the function pointer for the listener for the control-display separation feature. |
| typedef bool(*PFN_HMS_XEG_SetControlDisplaySeparationStatusListener) (PFN_HMS_XEG_ControlDisplaySeparationStatusCallback callback) | Defines the function pointer for setting the globally unique listener for the control-display separation feature. |
| typedef void(*PFN_HMS_XEG_RemoveControlDisplaySeparationStatusListener) () | Defines the function pointer for removing the globally unique listener for the control-display separation feature. |
| typedef bool(*PFN_HMS_XEG_SetControlDisplaySeparationActive) (bool flag) | Defines the function pointer for setting whether to enable the control-display separation feature. |
[h2]Enums
| Name | Description |
|---|---|
| XEG_STRUCTURE_TYPE_RT_SHADOWAO_CREATE_INFO = 0, XEG_STRUCTURE_TYPE_RT_SHADOWAO_DESCRIPTION = 1, XEG_STRUCTURE_TYPE_RT_REFLECTION_CREATE_INFO = 2, XEG_STRUCTURE_TYPE_RT_REFLECTION_DESCRIPTION = 3, XEG_STRUCTURE_TYPE_NNGI_CREATE_INFO = 4, XEG_STRUCTURE_TYPE_NNGI_DESCRIPTION = 5, XEG_STRUCTURE_TYPE_DDGI_CREATE_INFO = 6, XEG_STRUCTURE_TYPE_DDGI_DESCRIPTION = 7, XEG_STRUCTURE_TYPE_NEURAL_UPSCALE_CREATE_INFO = 8, XEG_STRUCTURE_TYPE_NEURAL_UPSCALE_DESCRIPTION = 9, XEG_STRUCTURE_TYPE_HPS_CREATE_INFO = 1001, XEG_STRUCTURE_TYPE_HPS_RADIX_SORT = 1002, XEG_STRUCTURE_TYPE_HPS_RADIX_SORT_DESCRIPTION = 1003 } | Enumerates XEngine struct types. |
| XEG_DenoiseQualityMode { XEG_DENOISE_QUALITY_MODE_NONE = 0, XEG_DENOISE_QUALITY_MODE_QUALITY = 1, XEG_DENOISE_QUALITY_MODE_BALANCED = 2, XEG_DENOISE_QUALITY_MODE_PERFORMANCES = 3 } | Enumerates denoising quality modes. |
| XEG_TraversalMode { XEG_TRAVERSAL_MODE_DEFAULT = 0, XEG_TRAVERSAL_MODE_PERFORMANCES = 1 } | Enumerates traversal modes. |
| XEG_RTGIQualityMode { XEG_RTGI_QUALITY_MODE_QUALITY = 0, XEG_RTGI_QUALITY_MODE_BALANCED = 1, XEG_RTGI_QUALITY_MODE_PERFORMANCE = 2 } | Enumerates output image quality modes. |
| XEG_ControlDisplaySeparationStatus { UNAVAILABLE = 0, AVAILABLE = 1} | Enumerates the current status information of the control-display separation feature. |
[h2]Functions
| Name | Description |
|---|---|
| GL_APICALL void GL_APIENTRY HMS_XEG_AdaptiveVRSParameter (GLenum pname, GLvoid *param) | Sets the parameters of adaptive VRS. |
| GL_APICALL void GL_APIENTRY HMS_XEG_DispatchAdaptiveVRS (GLfloat *reprojectionMatrix, GLuint inputColorImage, GLuint inputDepthImage, GLuint shadingRateImage) | Computes the shading rate image. |
| GL_APICALL void GL_APIENTRY HMS_XEG_ApplyAdaptiveVRS (GLuint shadingRateImage) | Applies the shading rate image to the render target. |
| const GLubyte * HMS_XEG_GetString (GLenum name) | Queries XEngine OpenGL ES extensions. |
| GL_APICALL void GL_APIENTRY HMS_XEG_NeuralUpscaleParameter (GLenum pname, GLvoid *param) | Sets the input parameters for AI spatial upscaling. |
| GL_APICALL void GL_APIENTRY HMS_XEG_RenderNeuralUpscale (GLuint inputTexture) | Executes the rendering command for AI spatial upscaling. |
| GL_APICALL void GL_APIENTRY HMS_XEG_SpatialUpscaleParameter (GLenum pname, GLvoid *param) | Sets the input parameters for GPU spatial upscaling. |
| GL_APICALL void GL_APIENTRY HMS_XEG_RenderSpatialUpscale (GLuint inputTexture) | Executes the rendering command for GPU spatial upscaling. |
| GL_APICALL void GL_APIENTRY HMS_XEG_TemporalUpscaleParameter (GLenum pname, const GLvoid *param) | Sets the input parameters for AI temporal upscaling. |
| GL_APICALL void GL_APIENTRY HMS_XEG_RenderTemporalUpscale (GLuint inputTexture, GLuint depthTexture, GLuint motionVectorTexture, GLuint dynamicMaskTexture, GLfloat jitterX, GLfloat jitterY) | Executes the rendering command for AI temporal upscaling. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateAdaptiveVRS (VkDevice device, XEG_AdaptiveVRSCreateInfo *pXegAdaptiveVRSCreateInfo, XEG_AdaptiveVRS *pXegAdaptiveVRS) | Creates an XEG_AdaptiveVRS object. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_CmdDispatchAdaptiveVRS (VkCommandBuffer commandBuffer, XEG_AdaptiveVRS xegAdaptiveVRS, XEG_AdaptiveVRSDescription *pXegAdaptiveVRSDescription) | Executes the command for computing the adaptive VRS. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyAdaptiveVRS (XEG_AdaptiveVRS xegAdaptiveVRS) | Destroys an XEG_AdaptiveVRS object. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdSetSynchronization (VkCommandBuffer commandBuffer, const void *xegHandle) | Sets the synchronization signal and waits for the rendering result to be written to a specified image. When the RTGI feature is used, it is the GI rendering result that needs to be waited for before being written to a specified image. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_EnumerateDeviceExtensionProperties (VkPhysicalDevice physicalDevice, uint32_t *pPropertyCount, XEG_ExtensionProperties *pProperties) | Queries XEngine Vulkan extensions. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateHPS (VkDevice device, const XEG_HPSCreateInfo *pCreateInfo, XEG_HPS *pHps) | Creates an XEG_HPS object. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyHPS (XEG_HPS hps) | Destroys an XEG_HPS object. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRadixSortHPS (VkCommandBuffer commandBuffer, XEG_HPS hps, const XEG_HPSRadixSortDescription *pDescription) | Records the HPS sorting command. Before using this API, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension is supported. |
| 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. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateRTVisibleMask (VkDevice device, const void *pCreateInfo, XEG_RTVisibleMask *pRTVisibleMask) | Creates an XEG_RTVisibleMask object. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRenderRTVisibleMask (VkCommandBuffer commandBuffer, XEG_RTVisibleMask rtVisibleMask, const void *pDescription) | Records the ray-traced VisibleMask rendering command. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyRTVisibleMask (XEG_RTVisibleMask rtVisibleMask) | Destroys an XEG_RTVisibleMask object. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateRTGI (VkDevice device, const void *pCreateInfo, XEG_RTGI *pRtGI) | Creates an XEG_RTGI object. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyRTGI (XEG_RTGI rtGI) | Destroys an XEG_RTGI object. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRenderRTGI (VkCommandBuffer commandBuffer, XEG_RTGI rtGI, const void *pDescription) | Executes the rendering command. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateSpatialUpscale (VkDevice device, const XEG_SpatialUpscaleCreateInfo *pXegSpatialUpscaleCreateInfo, XEG_SpatialUpscale *pXegSpatialUpscale) | Creates an XEG_SpatialUpscale object. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_CmdRenderSpatialUpscale (VkCommandBuffer commandBuffer, XEG_SpatialUpscale xegSpatialUpscale, XEG_SpatialUpscaleDescription *pXegSpatialUpscaleDescription) | Executes the rendering command for GPU spatial upscaling. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroySpatialUpscale (XEG_SpatialUpscale xegSpatialUpscale) | Destroys an XEG_SpatialUpscale object. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateTemporalUpscale (VkDevice device, XEG_TemporalUpscaleCreateInfo *pTemporalUpscaleInfo, XEG_TemporalUpscale *pTemporalUpscale) | Creates an XEG_TemporalUpscale object. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_CmdRenderTemporalUpscale (VkCommandBuffer commandBuffer, XEG_TemporalUpscale temporalUpscale, XEG_TemporalUpscaleDescription *pDescription) | Records the rendering command for AI temporal scaling. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyTemporalUpscale (XEG_TemporalUpscale temporalUpscale) | Destroys an XEG_TemporalUpscale object. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateNeuralUpscale (VkDevice device, const XEG_NeuralUpscaleCreateInfo *pCreateInfo, XEG_NeuralUpscale *pNeuralUpscale) | Creates an XEG_NeuralUpscale object. |
| VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRenderNeuralUpscale (VkCommandBuffer commandBuffer, XEG_NeuralUpscale neuralUpscale, const XEG_NeuralUpscaleDescription *pDescription) | Records the rendering command for AI spatial scaling. |
| VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyNeuralUpscale (XEG_NeuralUpscale neuralUpscale) | Destroys an XEG_NeuralUpscale object. |
| bool HMS_XEG_SetControlDisplaySeparationStatusListener (PFN_HMS_XEG_ControlDisplaySeparationStatusCallback callback) | Sets the globally unique listener for the control-display separation feature. |
| void HMS_XEG_RemoveControlDisplaySeparationStatusListener () | Removes the globally unique listener for the control-display separation feature. |
| bool HMS_XEG_SetControlDisplaySeparationActive (bool flag) | Sets whether to enable the control-display separation feature. |
[h2]XEG_adaptive_vrs
#define XEG_adaptive_vrs 1
Description
Macro definition of the XEngine adaptive VRS extension.
Since: 5.0.0(12)
[h2]XEG_ADAPTIVE_VRS_ERROR_SENSITIVITY
#define XEG_ADAPTIVE_VRS_ERROR_SENSITIVITY 0x4U
Description
Sets the ERROR_SENSITIVITY parameter of the HMS_XEG_AdaptiveVRSParameter API, which indicates the threshold for generating the shading rate image. A larger value indicates a smaller average shading rate, that is, the performance is better but the image quality deteriorates. The recommended value range is [0.0, 1.0].
When this macro is used, the ERROR_SENSITIVITY parameter is set through the HMS_XEG_AdaptiveVRSParameter API. The param value passed to the API must be a GLfloat pointer. Otherwise, undefined behavior may occur, for example, the rendering effect is incorrect or the program crashes. This parameter is optional. The default value is 0.5.
Since: 5.0.0(12)
[h2]XEG_ADAPTIVE_VRS_EXTENSION_NAME
#define XEG_ADAPTIVE_VRS_EXTENSION_NAME "XEG_adaptive_vrs"
Description
XEngine adaptive VRS extension name.
Since: 5.0.0(12)
[h2]XEG_ADAPTIVE_VRS_FLIP
#define XEG_ADAPTIVE_VRS_FLIP 0x5U
Description
Sets the FLIP parameter of the HMS_XEG_AdaptiveVRSParameter API. This parameter is used to control whether to flip an image up and down.
When this macro is used, the FLIP parameter is set through the HMS_XEG_AdaptiveVRSParameter API. The param value passed to the API must be a GLboolean pointer. Otherwise, undefined behavior may occur, for example, the rendering effect is incorrect or the program crashes. This parameter is optional. The default value is false. The value true indicates that the flip is performed, and the value false indicates that the flip is not performed.
Since: 5.0.0(12)
[h2]XEG_ADAPTIVE_VRS_INPUT_REGION
#define XEG_ADAPTIVE_VRS_INPUT_REGION 0x2U
Description
Sets the INPUT_REGION parameter of the HMS_XEG_AdaptiveVRSParameter API, which indicates the image region finally rendered by the rendering pipeline of the previous frame.
When this macro is used, the INPUT_REGION parameter is set through the HMS_XEG_AdaptiveVRSParameter API. The param value passed to the API must be an array of four elements of the GLuint type, which indicates the coordinates of the lower left corner of the rendered image region and the width and height of the rendered image region in sequence. Otherwise, undefined behavior may occur, for example, the rendering effect is incorrect or the program crashes. This parameter is optional. The default value is [0, 0, INPUT_SIZE[0], INPUT_SIZE[1]].
Since: 5.0.0(12)
[h2]XEG_ADAPTIVE_VRS_INPUT_SIZE
#define XEG_ADAPTIVE_VRS_INPUT_SIZE 0x1U
Description
Sets the INPUT_SIZE parameter of the HMS_XEG_AdaptiveVRSParameter API, which indicates the image width and height finally rendered by the rendering pipeline of the previous frame.
When this macro is used, the INPUT_SIZE parameter is set through the HMS_XEG_AdaptiveVRSParameter API. The param value passed to the API must be an array of two elements of the GLsizei type. Otherwise, undefined behavior may occur, for example, the rendering effect is incorrect or the program crashes. This parameter is mandatory. Ensure that the width and height of this parameter are the same as those of inputColorImage in HMS_XEG_DispatchAdaptiveVRS.
Since: 5.0.0(12)
[h2]XEG_ADAPTIVE_VRS_TEXEL_SIZE
#define XEG_ADAPTIVE_VRS_TEXEL_SIZE 0x3U
Description
Sets the TEXEL_SIZE parameter of the HMS_XEG_AdaptiveVRSParameter API.
When this macro is used, the TEXEL_SIZE parameter is set through the HMS_XEG_AdaptiveVRSParameter API. The param value passed to the API must be an array of two elements of the GLsizei type, which are TEXEL_WIDTH and TEXEL_HEIGHT in sequence. Otherwise, undefined behavior may occur, for example, the rendering effect is incorrect or the program crashes. This parameter is optional. The default value is [8, 8]. The value can be [8, 8] or [16, 16].
Since: 5.0.0(12)
[h2]XEG_ADAPTIVE_VRS_VERSION
#define XEG_ADAPTIVE_VRS_VERSION 1
Description
Extension version number of the XEngine adaptive VRS.
Since: 5.0.0(12)
[h2]XEG_EXTENSIONS
#define XEG_EXTENSIONS 0x01U
Description
Serves as an input parameter of the HMS_XEG_GetString API to obtain the OpenGL ES extensions supported by XEngine.
Since: 5.0.0(12)
[h2]XEG_HPS_RADIX_SORT_EXTENSION_NAME
#define XEG_HPS_RADIX_SORT_EXTENSION_NAME "XEG_hps_radix_sort"
Description
Extension name of High-Performance Radix Sort of XEngine.
Since: 6.0.0(20)
[h2]XEG_MAX_EXTENSION_NAME_SIZE
#define XEG_MAX_EXTENSION_NAME_SIZE 256
Description
Maximum length of the XEngine extension name.
Since: 5.0.0(12)
[h2]XEG_neural_upscale
#define XEG_neural_upscale 1
Description
Extension macro definition of AI spatial upscaling of XEngine.
Since: 5.0.0(12)
[h2]XEG_NEURAL_UPSCALE_EXTENSION_NAME
#define XEG_NEURAL_UPSCALE_EXTENSION_NAME "XEG_neural_upscale"
Description
Extension name of AI spatial upscaling of XEngine.
Since: 5.0.0(12)
[h2]XEG_NEURAL_UPSCALE2_EXTENSION_NAME
#define XEG_NEURAL_UPSCALE2_EXTENSION_NAME "XEG_neural_upscale2"
Description
Extension name of AI spatial upscaling (version 2) of XEngine.
Since: 26.0.0
[h2]XEG_NEURAL_UPSCALE_SCISSOR
#define XEG_NEURAL_UPSCALE_SCISSOR 0x1U
Description
Sets the upscaling cropping window parameters through the HMS_XEG_NeuralUpscaleParameter API. The cropping window is used to determine the area where the input image is sampled.
When this macro is used to set the cropping window parameters, the param value passed to the API must be an unsigned integer array of four elements. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes. The values in the array are x, y, width, and height in sequence, where x and y determine the lower left corner of the cropping window, and width and height determine the width and height of the cropping window, respectively.
This parameter is optional. If the cropping window parameters are not set, the default value is (0, 0, width of the input texture, height of the input texture).
Since: 5.0.0(12)
[h2]XEG_NEURAL_UPSCALE_SHARPNESS
#define XEG_NEURAL_UPSCALE_SHARPNESS 0x2U
Description
Sets the upscaling sharpening parameters through the HMS_XEG_NeuralUpscaleParameter API. The recommended value range is [0.0, 1.0].
When this macro is used to set the upscaling sharpening parameters, the param value passed to the API must be a valid pointer to a float value. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes.
This parameter is optional. If the parameter is not set, the default value is 0.2.
Since: 5.0.0(12)
[h2]XEG_NEURAL_UPSCALE_INPUT_HANDLE
#define XEG_NEURAL_UPSCALE_INPUT_HANDLE 0x4U
Description
Sets the OH_NativeBuffer handle associated with the scaling input texture through the HMS_XEG_NeuralUpscaleParameter API.
When this macro is used to set the scaling input parameters, the param value passed to the API must be a valid OH_NativeBuffer handle corresponding to the inputTexture parameter passed to the HMS_XEG_RenderNeuralUpscale API. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes.
This parameter is mandatory when the XEG_NEURAL_UPSCALE_EXTENSION_NAME extension is available.
This parameter does not need to be set when the XEG_NEURAL_UPSCALE2_EXTENSION_NAME extension is available.
Since: 5.0.0(12)
[h2]XEG_NEURAL_UPSCALE_VERSION
#define XEG_NEURAL_UPSCALE_VERSION 1
Description
Extension version number of AI spatial upscaling of XEngine.
Since: 5.0.0(12)
[h2]XEG_RT_REFLECTION_EXTENSION_NAME
#define XEG_RT_REFLECTION_EXTENSION_NAME "XEG_rt_reflection"
Description
Extension name of Ray-Traced Reflections of XEngine.
Since: 6.0.0(20)
[h2]XEG_RT_SHADOW_AO_EXTENSION_NAME
#define XEG_RT_SHADOW_AO_EXTENSION_NAME "XEG_rt_shadow_ao"
Description
Extension name of Ray-Traced Shadow and Ambient Occlusion of XEngine.
Since: 6.0.0(20)
[h2]XEG_RTGI_EXTENSION_NAME
#define XEG_RTGI_EXTENSION_NAME "XEG_rtgi"
Description
Extension name of Ray-Traced Global Illumination of XEngine.
Since: 6.0.0(20)
[h2]XEG_spatial_upscale
#define XEG_spatial_upscale 1
Description
Extension macro definition of GPU spatial upscaling of XEngine.
Since: 5.0.0(12)
[h2]XEG_SPATIAL_UPSCALE_EXTENSION_NAME
#define XEG_SPATIAL_UPSCALE_EXTENSION_NAME "XEG_spatial_upscale"
Description
Extension name of GPU spatial upscaling of XEngine.
Since: 5.0.0(12)
[h2]XEG_SPATIAL_UPSCALE_SCISSOR
#define XEG_SPATIAL_UPSCALE_SCISSOR 0x1U
Description
Sets the SCISSOR parameter of the HMS_XEG_SpatialUpscaleParameter API.
When this macro is used to set the SCISSOR parameter through the HMS_XEG_SpatialUpscaleParameter API, the param value passed to the API must be a pointer to an unsigned integer array of four elements. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes. The four values of SCISSOR are the X and Y coordinates of the lower left corner of the cropping window and the width and height of the cropping window in sequence.
Since: 5.0.0(12)
[h2]XEG_SPATIAL_UPSCALE_SHARPNESS
#define XEG_SPATIAL_UPSCALE_SHARPNESS 0x2U
Description
Sets the SHARPNESS parameter of the HMS_XEG_SpatialUpscaleParameter API.
When this macro is used, the SHARPNESS parameter is set through the HMS_XEG_SpatialUpscaleParameter API. The param value passed to the API must be a pointer to the float type. The recommended value range of the SHARPNESS parameter is [0.0, 1.0]. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes. A larger value of the SHARPNESS parameter indicates a stronger sharpening effect. The sharpness needs to be adjusted for images of different styles. Otherwise, over-sharpening will occur, for example, the image has a lot of noises.
Since: 5.0.0(12)
[h2]XEG_SPATIAL_UPSCALE_VERSION
#define XEG_SPATIAL_UPSCALE_VERSION 1
Description
Extension version number of GPU spatial upscaling of XEngine.
Since: 5.0.0(12)
[h2]XEG_temporal_upscale
#define XEG_temporal_upscale 1
Description
Extension macro definition of AI temporal upscaling of XEngine.
Since: 5.0.0(12)
[h2]XEG_TEMPORAL_UPSCALE_DEPTH_REVERSED
#define XEG_TEMPORAL_UPSCALE_DEPTH_REVERSED 0x3U
Description
Sets whether depth reversion exists through the HMS_XEG_TemporalUpscaleParameter API. The value true indicates that depth reversion exists, and the value false indicates that depth reversion does not exist.
When this macro is used to define whether depth inversion exists, the param value passed to the API must be a valid pointer to a GLboolean value. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes. This parameter is mandatory.
Since: 6.0.0(20)
[h2]XEG_TEMPORAL_UPSCALE_EXTENSION_NAME
#define XEG_TEMPORAL_UPSCALE_EXTENSION_NAME "XEG_temporal_upscale"
Description
Extension name of AI temporal upscaling of XEngine.
Since: 5.0.0(12)
[h2]XEG_TEMPORAL_UPSCALE_INPUT_SIZE
#define XEG_TEMPORAL_UPSCALE_INPUT_SIZE 0x1U
Description
Sets the actual width and height of the upscaling input texture through the HMS_XEG_TemporalUpscaleParameter API.
When this macro is used to set the input width and height, the param value passed to the API must be an unsigned integer array of two elements. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes. The values in the array are width and height in sequence. width and height respectively determine the width and height of the input texture. This parameter is mandatory.
Since: 6.0.0(20)
[h2]XEG_TEMPORAL_UPSCALE_JITTER_NUM
#define XEG_TEMPORAL_UPSCALE_JITTER_NUM 0x2U
Description
Sets the number of camera jitter cycles through the HMS_XEG_TemporalUpscaleParameter API. The value range is [4, 16]. The recommended value is 8.
When this macro is used to set the number of camera jitter cycles, the param value passed to the API must be a valid pointer to a GLuint value. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes. This parameter is mandatory.
Since: 6.0.0(20)
[h2]XEG_TEMPORAL_UPSCALE_RESET_HISTORY
#define XEG_TEMPORAL_UPSCALE_RESET_HISTORY 0x4U
Description
Sets whether to reset historical frame data through the HMS_XEG_TemporalUpscaleParameter API. The value true indicates that the data is reset, and the value false indicates that the data is not reset. The value true is recommended if upscaling is not used for historical frames but is used for the current frame.
When this macro is used to define whether to reset historical frame data, the param value passed to the API must be a valid pointer to a GLboolean value. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes. This parameter is mandatory.
Since: 6.0.0(20)
[h2]XEG_TEMPORAL_UPSCALE_STEADY_LEVEL
#define XEG_TEMPORAL_UPSCALE_STEADY_LEVEL 0x5U
Description
Sets whether the picture is biased towards the current frame (less ghosting but more flickering) or historical frames (more ghosting but more stable) through the HMS_XEG_TemporalUpscaleParameter API. The value range is [0.0, 1.0]. If the value is not within this range, undefined behavior may occur, such as incorrect rendering effect or program crash. A larger value indicates a stronger bias towards historical frames. You are advised to select a proper value based on actual requirements. For example, you can set this parameter to a smaller value to reduce ghosting, or set it to a larger value to reduce flickering. The recommended value is 0.5.
When this macro is used to set the degree of bias, the param value passed to the API must be a valid pointer to a GLfloat value. Otherwise, undefined behavior will occur, for example, the rendering effect is incorrect or the program crashes. This parameter is optional. The default value is 0.5.
Since: 6.0.0(20)
[h2]XEG_TEMPORAL_UPSCALE_VERSION
#define XEG_TEMPORAL_UPSCALE_VERSION 1
Description
Extension version number of AI temporal upscaling of XEngine.
Since: 5.0.0(12)
[h2]PFN_HMS_XEG_ADAPTIVEVRSPARAMETER
typedef void(GL_APIENTRYP PFN_HMS_XEG_ADAPTIVEVRSPARAMETER) (GLenum pname, GLvoid *param)
Description
Defines the function pointer for setting the input parameters of adaptive VRS.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| pname | Enumerated name of the input parameter. The value can be XEG_ADAPTIVE_VRS_INPUT_SIZE, XEG_ADAPTIVE_VRS_INPUT_REGION, XEG_ADAPTIVE_VRS_TEXEL_SIZE, XEG_ADAPTIVE_VRS_ERROR_SENSITIVITY, or XEG_ADAPTIVE_VRS_FLIP. |
| param | Input parameter value. For details, please refer to the description of the enumerated names of the input parameters. |
[h2]PFN_HMS_XEG_APPLYADAPTIVEVRS
typedef void(GL_APIENTRYP PFN_HMS_XEG_APPLYADAPTIVEVRS) (GLuint shadingRateImage)
Description
Defines the function pointer for applying the shading rate image to the render target.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| shadingRateImage | Shading rate image obtained through computation. The value 0 indicates that adaptive VRS is disabled. |
[h2]PFN_HMS_XEG_CmdDispatchAdaptiveVRS
typedef void(VKAPI_PTR *PFN_HMS_XEG_CmdDispatchAdaptiveVRS) (VkCommandBuffer commandBuffer, XEG_AdaptiveVRS xegAdaptiveVRS, XEG_AdaptiveVRSDescription *pXegAdaptiveVRSDescription)
Description
Defines the function pointer for executing a command for computing the adaptive VRS.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | VkCommandBuffer that records the current command, which must be submitted to vkQueueSubmit. Otherwise, the command cannot be executed. |
| xegAdaptiveVRS | Created XEG_AdaptiveVRS object. |
| pXegAdaptiveVRSDescription | Pointer to the parameter struct XEG_AdaptiveVRSDescription for delivering command. The parameter cannot be empty. |
[h2]PFN_HMS_XEG_CmdRadixSortHPS
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CmdRadixSortHPS) (VkCommandBuffer commandBuffer, XEG_HPS hps, const XEG_HPSRadixSortDescription *pDescription)
Description
Defines the function pointer for recording the HPS sorting command. Before using this API, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension is supported.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object. |
| hps | Created XEG_HPS object. |
| pDescription | Pointer to the input information struct XEG_HPSRadixSortDescription of the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension. The parameter cannot be empty. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CmdRenderRTGI
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CmdRenderRTGI) (VkCommandBuffer commandBuffer, XEG_RTGI rtGI, const void *pDescription)
Description
Defines the function pointer for executing a rendering command.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | VkCommandBuffer that records the current command, which must be submitted to vkQueueSubmit. Otherwise, the command cannot be executed. |
| rtGI | Created XEG_RTGI object. |
| pDescription | Pointer to the information struct for executing the rendering command. If the DDGI rendering is used, the pointer is the pointer to the XEG_DDGIDescription struct. If the NNGI rendering is used, the pointer is the pointer to the XEG_NNGIDescription struct. The parameter cannot be empty. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CmdRenderRTReflection
typedef VkResult (VKAPI_ATTR *PFN_HMS_XEG_CmdRenderRTReflection)(VkCommandBuffer commandBuffer, XEG_RTReflection rtReflection, const void *pDescription)
Description
Defines the function pointer for recording the command for computing the RT reflection hit information.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object, which must be of the primary type. |
| rtReflection | Created XEG_RTReflection object. |
| pDescription | Pointer to the input information struct XEG_RTReflectionDescription for reflection rendering. The parameter cannot be empty. |
[h2]PFN_HMS_XEG_CmdRenderRTVisibleMask
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CmdRenderRTVisibleMask) (VkCommandBuffer commandBuffer, XEG_RTVisibleMask rtVisibleMask, const void *pDescription)
Description
Defines the function pointer for recording the ray-traced VisibleMask rendering command.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object. |
| rtVisibleMask | Created XEG_RTVisibleMask object. |
| pDescription | Pointer to the input parameter struct for executing the rendering command. Currently, only the pointer of the XEG_RTShadowAODescription type is supported. The parameter cannot be empty. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CmdRenderSpatialUpscale
typedef void(VKAPI_PTR *PFN_HMS_XEG_CmdRenderSpatialUpscale) (VkCommandBuffer commandBuffer, XEG_SpatialUpscale xegSpatialUpscale, XEG_SpatialUpscaleDescription *pXegSpatialUpscaleDescription)
Description
Defines the function pointer for executing the rendering command for GPU spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | VkCommandBuffer that records the current command, which must be submitted to vkQueueSubmit. Otherwise, the command cannot be executed. |
| xegSpatialUpscale | Created XEG_SpatialUpscale object. |
| pXegSpatialUpscaleDescription | Pointer to the parameter struct XEG_SpatialUpscaleDescription of the rendering command. The parameter cannot be empty. |
[h2]PFN_HMS_XEG_CmdRenderTemporalUpscale
typedef void(VKAPI_ATTR *PFN_HMS_XEG_CmdRenderTemporalUpscale) (VkCommandBuffer commandBuffer, XEG_TemporalUpscale temporalUpscale, XEG_TemporalUpscaleDescription *pDescription)
Description
Defines the function pointer for recording the rendering command for AI temporal scaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object, which must be of the primary type. |
| temporalUpscale | Created XEG_TemporalUpscale object. |
| pDescription | Pointer to the upscaling rendering input information struct XEG_TemporalUpscaleDescription. The parameter cannot be empty. |
[h2]PFN_HMS_XEG_CmdRenderNeuralUpscale
typedef VkResult (VKAPI_PTR *PFN_HMS_XEG_CmdRenderNeuralUpscale) (VkCommandBuffer commandBuffer, XEG_NeuralUpscale neuralUpscale, const XEG_NeuralUpscaleDescription *pDescription)
Description
Defines the function pointer for recording the rendering command for AI spatial scaling.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object, which must be of the primary type. |
| neuralUpscale | Created XEG_NeuralUpscale object. |
| pDescription | Pointer to the upscaling rendering input information struct XEG_NeuralUpscaleDescription. The parameter cannot be empty. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CmdSetSynchronization
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CmdSetSynchronization) (VkCommandBuffer commandBuffer, const void *xegHandle)
Description
Defines the function pointer for setting synchronization signals and waiting for the rendering result to be written to a specified image. When the RTGI feature is used, it is the GI rendering result that needs to be waited for before being written to a specified image.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | VkCommandBuffer that records the current command, which must be submitted to vkQueueSubmit. Otherwise, the command cannot be executed. |
| xegHandle | Created handle object. When the RTGI feature is used, the object is the created XEG_RTGI object. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CreateAdaptiveVRS
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CreateAdaptiveVRS) (VkDevice device, const XEG_AdaptiveVRSCreateInfo *pXegAdaptiveVRSCreateInfo, XEG_AdaptiveVRS *pXegAdaptiveVRS)
Description
Defines the function pointer for creating an XEG_AdaptiveVRS object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pXegAdaptiveVRSCreateInfo | Pointer to the XEG_AdaptiveVRSCreateInfo struct. The parameter cannot be empty. |
| pXegAdaptiveVRS | Pointer to the handle in which the created XEG_AdaptiveVRS is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CreateHPS
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CreateHPS) (VkDevice device, const XEG_HPSCreateInfo *pCreateInfo, XEG_HPS *pHps)
Description
Defines the function pointer for creating an XEG_HPS object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the information struct for creating an XEG_HPS instance handle. The parameter cannot be empty. |
| pHps | Pointer to the HPS instance handle in which the created XEG_HPS is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CreateRTGI
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CreateRTGI) (VkDevice device, const void *pCreateInfo, XEG_RTGI *pRtGI)
Description
Defines the function pointer for creating an XEG_RTGI object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the information struct for creating an XEG_RTGI object. If a DDGI handle is created, the pointer is the pointer to the XEG_DDGICreateInfo struct. If an NNGI handle is created, the pointer to the XEG_NNGICreateInfo struct. The parameter cannot be empty. |
| pRtGI | Pointer to the handle in which the created XEG_RTGI object is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CreateRTReflection
typedef VkResult(VKAPI_ATTR *PFN_HMS_XEG_CreateRTReflection) (VkDevice device, const void *pCreateInfo, XEG_RTReflection *pRtReflection)
Description
Defines the function pointer for creating an XEG_RTReflection object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the information struct for creating a reflection instance handle. Currently, only the pointer of the XEG_RTReflectionCreateInfo type is supported. The parameter cannot be empty. |
| pRtReflection | Pointer to the reflection instance handle in which the created XEG_RTReflection is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CreateRTVisibleMask
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CreateRTVisibleMask) (VkDevice device, const void *pCreateInfo, XEG_RTVisibleMask *pRTVisibleMask)
Description
Defines the function pointer for creating an XEG_RTVisibleMask object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the struct of the description information required for creating a VisibleMask instance handle. Currently, only the pointer of the XEG_RTShadowAOCreateInfo type is supported. The parameter cannot be empty. |
| pRTVisibleMask | Pointer to the VisibleMask instance handle in which the created XEG_RTVisibleMask is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CreateSpatialUpscale
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CreateSpatialUpscale) (VkDevice device, const XEG_SpatialUpscaleCreateInfo *pXegSpatialUpscaleCreateInfo, XEG_SpatialUpscale *pXegSpatialUpscale)
Description
Defines the function pointer for creating an XEG_SpatialUpscale object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pXegSpatialUpscaleCreateInfo | Pointer to the XEG_SpatialUpscaleCreateInfo struct. The parameter cannot be empty. |
| pXegSpatialUpscale | Pointer to the handle in which the created XEG_SpatialUpscale is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CreateTemporalUpscale
typedef VkResult(VKAPI_ATTR *PFN_HMS_XEG_CreateTemporalUpscale) (VkDevice device, XEG_TemporalUpscaleCreateInfo *pTemporalUpscaleInfo, XEG_TemporalUpscale *pTemporalUpscale)
Description
Defines the function pointer for creating an XEG_TemporalUpscale object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pTemporalUpscaleInfo | Pointer to the information struct XEG_TemporalUpscaleCreateInfo for creating a scaling instance handle. The parameter cannot be empty. |
| pTemporalUpscale | Pointer to the handle in which the created XEG_TemporalUpscale is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_CreateNeuralUpscale
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_CreateNeuralUpscale) (VkDevice device, const XEG_NeuralUpscaleCreateInfo *pCreateInfo, XEG_NeuralUpscale *pNeuralUpscale)
Description
Defines the function pointer for creating an XEG_NeuralUpscale object.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the information struct XEG_NeuralUpscaleCreateInfo for creating a scaling instance handle. The parameter cannot be empty. |
| pNeuralUpscale | Pointer to the handle in which the created XEG_NeuralUpscale is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]PFN_HMS_XEG_DestroyAdaptiveVRS
typedef void(VKAPI_PTR *PFN_HMS_XEG_DestroyAdaptiveVRS) (XEG_AdaptiveVRS xegAdaptiveVRS)
Description
Defines the function pointer for destroying an XEG_AdaptiveVRS object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| xegAdaptiveVRS | Created XEG_AdaptiveVRS object. |
[h2]PFN_HMS_XEG_DestroyHPS
typedef void(VKAPI_PTR *PFN_HMS_XEG_DestroyHPS) (XEG_HPS hps)
Description
Defines the function pointer for destroying an XEG_HPS object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| hps | XEG_HPS object to be destroyed. |
[h2]PFN_HMS_XEG_DestroyRTGI
typedef void(VKAPI_PTR *PFN_HMS_XEG_DestroyRTGI) (XEG_RTGI rtGI)
Description
Defines the function pointer for destroying an XEG_RTGI object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| rtGI | Created XEG_RTGI object. |
[h2]PFN_HMS_XEG_DestroyRTReflection
typedef void(VKAPI_ATTR *PFN_HMS_XEG_DestroyRTReflection) (XEG_RTReflection rtReflection)
Description
Defines the function pointer for destroying an XEG_RTReflection object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| rtReflection | XEG_RTReflection object to be destroyed. |
[h2]PFN_HMS_XEG_DestroyRTVisibleMask
typedef void(VKAPI_PTR *PFN_HMS_XEG_DestroyRTVisibleMask) (XEG_RTVisibleMask rtVisibleMask)
Description
Defines the function pointer for destroying an XEG_RTVisibleMask object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| rtVisibleMask | XEG_RTVisibleMask object to be destroyed. |
[h2]PFN_HMS_XEG_DestroySpatialUpscale
typedef void(VKAPI_PTR *PFN_HMS_XEG_DestroySpatialUpscale) (XEG_SpatialUpscale xegSpatialUpscale)
Description
Defines the function pointer for destroying an XEG_SpatialUpscale object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| xegSpatialUpscale | Created XEG_SpatialUpscale object. |
[h2]PFN_HMS_XEG_DestroyTemporalUpscale
typedef void(VKAPI_ATTR *PFN_HMS_XEG_DestroyTemporalUpscale) (XEG_TemporalUpscale temporalUpscale)
Description
Defines the function pointer for destroying an XEG_TemporalUpscale object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| temporalUpscale | XEG_TemporalUpscale object to be destroyed. |
[h2]PFN_HMS_XEG_DestroyNeuralUpscale
typedef void(VKAPI_PTR *PFN_HMS_XEG_DestroyNeuralUpscale)(XEG_NeuralUpscale neuralUpscale)
Description
Defines the function pointer for destroying an XEG_NeuralUpscale object.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| neuralUpscale | XEG_NeuralUpscale object to be destroyed. |
[h2]PFN_HMS_XEG_DISPATCHADAPTIVEVRS
typedef void(GL_APIENTRYP PFN_HMS_XEG_DISPATCHADAPTIVEVRS) (GLfloat *reprojectionMatrix, GLuint inputColorImage, GLuint inputDepthImage, GLuint shadingRateImage)
Description
Defines the function pointer for computing the shading rate image.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| reprojectionMatrix | Pointer to the result matrix of the computation between the current frame and the previous frame. The computation formula is as follows: (Projection matrix of the previous frame × Observation matrix of the previous frame) x (Inverse matrix of (Projection matrix of the current frame × Observation matrix of the current frame)). The matrix must be a 4 × 4 column major-order matrix. This parameter is optional. When it is not empty, the image quality is better. |
| inputColorImage | Texture ID of the color attachment containing the final rendering result of the rendering pipeline of the previous frame. |
| inputDepthImage | Texture ID of the depth attachment containing the final rendering result of the rendering pipeline of the current frame. |
| shadingRateImage | Texture ID used to generate the shading rate image information, which needs to be created and entered by the user. |
The texture type must be GL_TEXTURE_2D and mipLevels is set to 1.
[h2]PFN_HMS_XEG_EnumerateDeviceExtensionProperties
typedef VkResult(VKAPI_PTR *PFN_HMS_XEG_EnumerateDeviceExtensionProperties) (VkPhysicalDevice physicalDevice, uint32_t *pPropertyCount, XEG_ExtensionProperties *pProperties)
Description
Defines the function pointer for querying the XEngine Vulkan extensions.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| physicalDevice | Vulkan physical device in use. |
| pPropertyCount | Number of queried or passed extensions. If pProperties is set to nullptr, the number of supported XEngine extensions is returned. If the passed value of propertyCount is greater than or equal to the number of supported XEngine extensions, the query result is returned through pProperties, and the return value is VK_SUCCESS. If the passed value of propertyCount is less than the number of supported XEngine extensions, the query result is returned through pProperties, but the return value is VK_INCOMPLETE. |
| pProperties | Queried XEngine extensions, which are returned through the pointer to the XEG_ExtensionProperties struct. |
Returns:
Error code of the VkResult type. If the query is successful, VK_SUCCESS is returned. If pProperties is not set to nullptr and the input value of propertyCount is less than the actual number of supported XEngine extensions, VK_INCOMPLETE is returned, indicating that the queried features are incomplete.
[h2]PFN_HMS_XEG_GETSTRING
typedef const GLubyte *(GL_APIENTRYP PFN_HMS_XEG_GETSTRING) (GLenum name)
Description
Defines the function pointer for querying the XEngine OpenGL ES extensions.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| name | Enumerated name of the input parameter. The value range is XEG_EXTENSIONS. |
Returns:
When the parameter is XEG_EXTENSIONS, a space-separated list of extensions supported by XEngine is returned. Note that the extension names do not contain spaces. If the query result is abnormal, an empty value is returned.
[h2]PFN_HMS_XEG_NEURALUPSCALEPARAMETER
typedef void(GL_APIENTRYP PFN_HMS_XEG_NEURALUPSCALEPARAMETER) (GLenum pname, GLvoid *param)
Description
Defines the function pointer for setting the input parameters of AI spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| pname | Enumerated name of the input parameter. The value can be XEG_NEURAL_UPSCALE_SCISSOR, XEG_NEURAL_UPSCALE_SHARPNESS, or XEG_NEURAL_UPSCALE_INPUT_HANDLE. |
| param | Input parameter value. For details, please refer to the description of the enumerated names of the input parameters. |
[h2]PFN_HMS_XEG_RENDERNEURALUPSCALE
typedef void(GL_APIENTRYP PFN_HMS_XEG_RENDERNEURALUPSCALE) (GLuint inputTexture)
Description
Defines the function pointer for executing the rendering command for AI spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| inputTexture | Scaling input texture. The input texture type is GL_TEXTURE_2D and mipLevels is set to 1. When the XEG_NEURAL_UPSCALE_EXTENSION_NAME extension is available, the texture width must be within the range [448, 1728]. Otherwise, the AI inference results may be incorrect. The input texture must be created by OH_NativeBuffer. Before calling this API, you need to set the handle corresponding to OH_NativeBuffer to the scaling input parameter. For details, please refer to the HMS_XEG_NeuralUpscaleParameter API. When the XEG_NEURAL_UPSCALE2_EXTENSION_NAME extension is available, the recommended texture width range is [448, 1792]. The input texture does not need to be created by OH_NativeBuffer. |
[h2]PFN_HMS_XEG_RENDERSPATIALUPSCALE
typedef void(GL_APIENTRYP PFN_HMS_XEG_RENDERSPATIALUPSCALE) (GLuint inputTexture)
Description
Defines the function pointer for executing the rendering command for GPU spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| inputTexture | Scaling input texture. The input texture type is GL_TEXTURE_2D and mipLevels is set to 1. The texture must be created before this API is called. Otherwise, rendering will fail, for example, a black screen will be displayed. |
[h2]PFN_HMS_XEG_RenderTemporalUpscale
typedef void(GL_APIENTRYP PFN_HMS_XEG_RenderTemporalUpscale) (GLuint inputTexture, GLuint depthTexture, GLuint motionVectorTexture, GLuint dynamicMaskTexture, GLfloat jitterX, GLfloat jitterY)
Description
Defines the function pointer for executing the rendering command for AI temporal upscaling.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| inputTexture | Scaling input texture. The input texture type is GL_TEXTURE_2D and mipLevels is set to 1. The maximum dimensions supported are 2048 × 1024. |
| depthTexture | Depth texture. |
| motionVectorTexture | Motion vector image. The motion vector is computed by subtracting the X and Y values of the NDC coordinates of the previous frame from those of the current rendered pixel. |
| dynamicMaskTexture | Dynamic mask image of an object. The format must be GL_RED or its compatible format. The valid value of the R channel is 0.0, 0.2, or 1.0, where 0.0 indicates static objects, 0.2 indicates moving objects such as people, and 1.0 indicates special effects or translucent objects. |
| jitterX | Jitter of the camera in the X direction. It is usually the sub-pixel jitter applied in the pre-rendering process on which upscaling depends and is included in the projection matrix of the camera. In the NDC coordinate system, the value range is [–1/width, 1/width], where width is the width (number of pixels) of inputTexture. |
| jitterY | Jitter of the camera in the Y direction. It is usually the sub-pixel jitter applied in the pre-rendering process on which upscaling depends and is included in the projection matrix of the camera. In the NDC coordinate system, the value range is [–1/height, 1/height], where height is the height (number of pixels) of inputTexture. |
[h2]PFN_HMS_XEG_SPATIALUPSCALEPARAMETER
typedef void(GL_APIENTRYP PFN_HMS_XEG_SPATIALUPSCALEPARAMETER) (GLenum pname, GLvoid *param)
Description
Defines the function pointer for setting the input parameters of GPU spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| pname | Enumerated name of the input parameter. The value can be XEG_SPATIAL_UPSCALE_SCISSOR or XEG_SPATIAL_UPSCALE_SHARPNESS. |
| param | Input parameter value. For details, please refer to the description of the enumerated names of the input parameters. |
[h2]PFN_HMS_XEG_TemporalUpscaleParameter
typedef void(GL_APIENTRYP PFN_HMS_XEG_TemporalUpscaleParameter) (GLenum pname, GLvoid *param)
Description
Defines the function pointer for setting the input parameters of AI temporal upscaling.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| pname | Enumerated name of the input parameter. The value can be XEG_TEMPORAL_UPSCALE_INPUT_SIZE, XEG_TEMPORAL_UPSCALE_JITTER_NUM, XEG_TEMPORAL_UPSCALE_DEPTH_REVERSED, XEG_TEMPORAL_UPSCALE_RESET_HISTORY, or XEG_TEMPORAL_UPSCALE_STEADY_LEVEL. |
| param | Input parameter value. For details, please refer to the description of the enumerated names of the input parameters. |
[h2]PFN_HMS_XEG_ControlDisplaySeparationStatusCallback
typedef void(*PFN_HMS_XEG_ControlDisplaySeparationStatusCallback) (XEG_ControlDisplaySeparationStatus status);
Description
Defines the function pointer for the listener for the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| status | Enumerated values of the control-display separation status information |
[h2]PFN_HMS_XEG_SetControlDisplaySeparationStatusListener
typedef bool(*PFN_HMS_XEG_SetControlDisplaySeparationStatusListener) (PFN_HMS_XEG_ControlDisplaySeparationStatusCallback callback);
Description
Defines the function pointer for setting the globally unique listener for the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| callback | Callback function to be set, which cannot be empty. |
Returns:
Returns true if the setting is successful and false if the setting fails. true will be returned only when the current device supports the control-display separation feature and the app has registered this feature in module.json.
[h2]PFN_HMS_XEG_RemoveControlDisplaySeparationStatusListener
typedef void(*PFN_HMS_XEG_RemoveControlDisplaySeparationStatusListener) ();
Description
Defines the function pointer for removing the globally unique listener for the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
[h2]PFN_HMS_XEG_SetControlDisplaySeparationActive
typedef bool(*PFN_HMS_XEG_SetControlDisplaySeparationActive) (bool flag);
Description
Defines the function pointer for setting whether to enable the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| flag | Status of the feature to be set. The value true indicates that the feature is enabled, and the value false indicates that the feature is disabled. |
Returns:
Returns true if the setting is successful and false if the setting fails. true will be returned only when the listener for the control-display separation feature is set and the callback of the listener is available.
[h2]XEG_AdaptiveVRS
VK_DEFINE_HANDLE(XEG_AdaptiveVRS)
Description
Handle to XEG_AdaptiveVRS.
Since: 5.0.0(12)
[h2]XEG_AdaptiveVRSCreateInfo
typedef struct XEG_AdaptiveVRSCreateInfo XEG_AdaptiveVRSCreateInfo
Description
Describes the parameters for creating an XEG_AdaptiveVRS object. When the information in the struct changes, a new XEG_AdaptiveVRS object needs to be created.
Since: 5.0.0(12)
[h2]XEG_AdaptiveVRSDescription
typedef struct XEG_AdaptiveVRSDescription XEG_AdaptiveVRSDescription
Description
Describes the parameter information required for delivering the command for drawing the shading rate texture. The information needs to be updated for each frame.
Since: 5.0.0(12)
[h2]XEG_DenoiseQualityMode
typedef enum XEG_DenoiseQualityMode XEG_DenoiseQualityMode
Description
Enumerates denoising quality modes.
Since: 6.0.0(20)
[h2]XEG_ExtensionProperties
typedef struct XEG_ExtensionProperties XEG_ExtensionProperties
Description
Describes the XEngine extension set obtained through the HMS_XEG_EnumerateDeviceExtensionProperties API.
Since: 5.0.0(12)
[h2]XEG_HPSCreateInfo
typedef struct XEG_HPSCreateInfo XEG_HPSCreateInfo
Description
Describes the information about creating an XEG_HPS object.
Since: 6.0.0(20)
[h2]XEG_HPSRadixSort
typedef struct XEG_HPSRadixSort XEG_HPSRadixSort
Description
Describes the HPS radix sort extension structure information.
Since: 6.0.0(20)
[h2]XEG_HPSRadixSortDescription
typedef struct XEG_HPSRadixSortDescription XEG_HPSRadixSortDescription
Description
Describes the information required when the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension is used for sorting.
Since: 6.0.0(20)
[h2]XEG_RTGIQualityMode
typedef enum XEG_RTGIQualityMode XEG_RTGIQualityMode
Description
Enumerates output image quality modes.
Since: 6.0.0(20)
[h2]XEG_RTReflection
VK_DEFINE_HANDLE(XEG_RTReflection)
Description
Handle to XEG_RTReflection.
Since: 6.0.0(20)
[h2]XEG_RTReflectionCreateInfo
typedef struct XEG_RTReflectionCreateInfo XEG_RTReflectionCreateInfo
Description
Describes the information about creating an XEG_RTReflection object. When the information in the struct changes, a new XEG_RTReflection object needs to be created.
Since: 6.0.0(20)
[h2]XEG_RTReflectionDescription
typedef struct XEG_RTReflectionDescription XEG_RTReflectionDescription
Description
Describes the input information for sending a ray intersection command.
Since: 6.0.0(20)
[h2]XEG_RTVisibleMask
VK_DEFINE_HANDLE(XEG_RTVisibleMask)
Description
Handle to XEG_RTVisibleMask, which indicates the ray-traced VisibleMask feature instance. The Shadow and Ambient Occlusion effects are supported.
Since: 6.0.0(20)
[h2]XEG_SpatialUpscale
VK_DEFINE_HANDLE(XEG_SpatialUpscale)
Description
Handle to XEG_SpatialUpscale.
Since: 5.0.0(12)
[h2]XEG_SpatialUpscaleCreateInfo
typedef struct XEG_SpatialUpscaleCreateInfo XEG_SpatialUpscaleCreateInfo
Description
Describes the information required for creating an XEG_SpatialUpscale object. When the information in the struct changes, a new XEG_SpatialUpscale object needs to be created.
Since: 5.0.0(12)
[h2]XEG_SpatialUpscaleDescription
typedef struct XEG_SpatialUpscaleDescription XEG_SpatialUpscaleDescription
Description
Describes the image information required for delivering the GPU spatial upscaling rendering command.
Since: 5.0.0(12)
[h2]XEG_StructureType
typedef enum XEG_StructureType XEG_StructureType
Description
Enumerates XEngine struct types.
Since: 6.0.0(20)
[h2]XEG_TemporalUpscale
VK_DEFINE_HANDLE(XEG_TemporalUpscale)
Description
Handle to XEG_TemporalUpscale.
Since: 5.0.0(12)
[h2]XEG_TemporalUpscaleCreateInfo
typedef struct XEG_TemporalUpscaleCreateInfo XEG_TemporalUpscaleCreateInfo
Description
Describes the information about creating an XEG_TemporalUpscale object. When the information in the struct changes, a new XEG_TemporalUpscale object needs to be created.
Since: 5.0.0(12)
[h2]XEG_TemporalUpscaleDescription
typedef struct XEG_TemporalUpscaleDescription XEG_TemporalUpscaleDescription
Description
Describes the input information when the AI temporal upscaling rendering command is delivered.
Since: 5.0.0(12)
[h2]XEG_TraversalMode
typedef enum XEG_TraversalMode XEG_TraversalMode
Description
Enumerates traversal modes.
Since: 6.0.0(20)
[h2]XEG_NeuralUpscale
VK_DEFINE_HANDLE(XEG_NeuralUpscale)
Description
Handle to XEG_NeuralUpscale.
Since: 26.0.0
[h2]XEG_NeuralUpscaleCreateInfo
typedef struct XEG_NeuralUpscaleCreateInfo XEG_NeuralUpscaleCreateInfo
Description
Describes the information about creating an XEG_NeuralUpscale object. When the information in the struct changes, a new XEG_NeuralUpscale object needs to be created.
Since: 26.0.0
[h2]XEG_NeuralUpscaleDescription
typedef struct XEG_NeuralUpscaleDescription XEG_NeuralUpscaleDescription
Description
Describes the input information when the AI spatial upscaling rendering command is delivered.
Since: 26.0.0
[h2]XEG_ControlDisplaySeparationStatus
typedef enum XEG_ControlDisplaySeparationStatus XEG_ControlDisplaySeparationStatus
Description
Enumerates the current status information of the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
[h2]XEG_DenoiseQualityMode
enum XEG_DenoiseQualityMode
Description
Enumerates denoising quality modes.
Since: 6.0.0(20)
| Enumerated Value | Description |
|---|---|
| XEG_DENOISE_QUALITY_MODE_NONE | No denoising is performed. |
| XEG_DENOISE_QUALITY_MODE_QUALITY | Generates high-quality noise-free results. The speed may be slow. |
| XEG_DENOISE_QUALITY_MODE_BALANCED | Generates high-quality noise-free results at a moderate speed. |
| XEG_DENOISE_QUALITY_MODE_PERFORMANCES | Generates noise-free results with high performance. |
[h2]XEG_RTGIQualityMode
enum XEG_RTGIQualityMode
Description
Enumerates output image quality modes.
Since: 6.0.0(20)
| Enumerated Value | Description |
|---|---|
| XEG_RTGI_QUALITY_MODE_QUALITY | Quality mode. |
| XEG_RTGI_QUALITY_MODE_BALANCED | Balance mode. |
| XEG_RTGI_QUALITY_MODE_PERFORMANCE | Performance mode. |
[h2]XEG_StructureType
enum XEG_StructureType
Description
Enumerates XEngine struct types.
Since: 6.0.0(20)
| Enumerated Value | Description |
|---|---|
| XEG_STRUCTURE_TYPE_RT_SHADOWAO_CREATE_INFO | XEG_RTShadowAOCreateInfo struct. |
| XEG_STRUCTURE_TYPE_RT_SHADOWAO_DESCRIPTION | XEG_RTShadowAODescription struct. |
| XEG_STRUCTURE_TYPE_RT_REFLECTION_CREATE_INFO | XEG_RTReflectionCreateInfo struct. |
| XEG_STRUCTURE_TYPE_RT_REFLECTION_DESCRIPTION | XEG_RTReflectionDescription struct. |
| XEG_STRUCTURE_TYPE_NNGI_CREATE_INFO | XEG_NNGICreateInfo struct. |
| XEG_STRUCTURE_TYPE_NNGI_DESCRIPTION | XEG_NNGIDescription struct. |
| XEG_STRUCTURE_TYPE_DDGI_CREATE_INFO | XEG_DDGICreateInfo struct. |
| XEG_STRUCTURE_TYPE_DDGI_DESCRIPTION | XEG_DDGIDescription struct. |
| XEG_STRUCTURE_TYPE_NEURAL_UPSCALE_CREATE_INFO | XEG_NeuralUpscaleCreateInfo struct. |
| XEG_STRUCTURE_TYPE_NEURAL_UPSCALE_DESCRIPTION | XEG_NeuralUpscaleDescription struct. |
| XEG_STRUCTURE_TYPE_HPS_CREATE_INFO | XEG_HPSCreateInfo struct. |
| XEG_STRUCTURE_TYPE_HPS_RADIX_SORT | XEG_HPSRadixSort struct. |
| XEG_STRUCTURE_TYPE_HPS_RADIX_SORT_DESCRIPTION | XEG_HPSRadixSortDescription struct. |
[h2]XEG_TraversalMode
enum XEG_TraversalMode
Description
Enumerates traversal modes.
Since: 6.0.0(20)
| Enumerated Value | Description |
|---|---|
| XEG_TRAVERSAL_MODE_DEFAULT | Traverses ray tracing scenarios pixel by pixel. |
| XEG_TRAVERSAL_MODE_PERFORMANCES | Traverses scenarios using algorithms, which provides better performance but may have slight differences in image quality. |
[h2]XEG_ControlDisplaySeparationStatus
enum XEG_ControlDisplaySeparationStatus
Description
Enumerates the current status information of the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
| Enumerated Value | Description |
|---|---|
| UNAVAILABLE | The control-display separation feature is unavailable. |
| AVAILABLE | The control-display separation feature is available. |
[h2]HMS_XEG_AdaptiveVRSParameter()
GL_APICALL void GL_APIENTRY HMS_XEG_AdaptiveVRSParameter (GLenum pname, GLvoid * param)
Description
Sets the parameters of adaptive VRS.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| pname | Enumerated name of the input parameter. The value can be XEG_ADAPTIVE_VRS_INPUT_SIZE, XEG_ADAPTIVE_VRS_INPUT_REGION, XEG_ADAPTIVE_VRS_TEXEL_SIZE, XEG_ADAPTIVE_VRS_ERROR_SENSITIVITY, or XEG_ADAPTIVE_VRS_FLIP. |
| param | Input parameter value. For details, please refer to the description of the enumerated names of the input parameters. |
[h2]HMS_XEG_ApplyAdaptiveVRS()
GL_APICALL void GL_APIENTRY HMS_XEG_ApplyAdaptiveVRS (GLuint shadingRateImage)
Description
Applies the shading rate image to the render target.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| shadingRateImage | Shading rate image obtained through computation. The value 0 indicates that adaptive VRS is disabled. |
[h2]HMS_XEG_CmdDispatchAdaptiveVRS()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_CmdDispatchAdaptiveVRS (VkCommandBuffer commandBuffer, XEG_AdaptiveVRS xegAdaptiveVRS, XEG_AdaptiveVRSDescription * pXegAdaptiveVRSDescription)
Description
Executes the command for computing the adaptive VRS.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | VkCommandBuffer that records the current command, which must be submitted to vkQueueSubmit. Otherwise, the command cannot be executed. |
| xegAdaptiveVRS | Created XEG_AdaptiveVRS object. |
| pXegAdaptiveVRSDescription | Pointer to the parameter struct XEG_AdaptiveVRSDescription for delivering command. The parameter cannot be empty. |
[h2]HMS_XEG_CmdRadixSortHPS()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRadixSortHPS (VkCommandBuffer commandBuffer, XEG_HPS hps, const XEG_HPSRadixSortDescription * pDescription)
Description
Records the HPS sorting command. Before using this API, you need to call the HMS_XEG_EnumerateDeviceExtensionProperties API to check whether the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension is supported.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object. |
| hps | Created XEG_HPS object. |
| pDescription | Pointer to the input information struct XEG_HPSRadixSortDescription of the XEG_HPS_RADIX_SORT_EXTENSION_NAME extension. The parameter cannot be empty. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CmdRenderRTGI()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRenderRTGI (VkCommandBuffer commandBuffer, XEG_RTGI rtGI, const void * pDescription)
Description
Executes the rendering command.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | VkCommandBuffer that records the current command, which must be submitted to vkQueueSubmit. Otherwise, the command cannot be executed. |
| rtGI | Created XEG_RTGI object. |
| pDescription | Pointer to the information struct for executing the rendering command. If the DDGI rendering is used, the pointer is the pointer to the XEG_DDGIDescription struct. If the NNGI rendering is used, the pointer is the pointer to the XEG_NNGIDescription struct. The parameter cannot be empty. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CmdRenderRTReflection()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRenderRTReflection (VkCommandBuffer commandBuffer, XEG_RTReflection rtReflection, const void * pDescription)
Description
Records the command for computing the ray-traced reflection hit information.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object, which must be of the primary type. |
| rtReflection | Created XEG_RTReflection object. |
| pDescription | Pointer to the input information struct XEG_RTReflectionDescription for reflection rendering. The parameter cannot be empty. |
[h2]HMS_XEG_CmdRenderRTVisibleMask()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRenderRTVisibleMask (VkCommandBuffer commandBuffer, XEG_RTVisibleMask rtVisibleMask, const void * pDescription)
Description
Records the ray-traced VisibleMask rendering command.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object. |
| rtVisibleMask | Created XEG_RTVisibleMask object. |
| pDescription | Pointer to the input parameter struct for executing the rendering command. Currently, only the pointer of the XEG_RTShadowAODescription type is supported. The parameter cannot be empty. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CmdRenderSpatialUpscale()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_CmdRenderSpatialUpscale (VkCommandBuffer commandBuffer, XEG_SpatialUpscale xegSpatialUpscale, XEG_SpatialUpscaleDescription * pXegSpatialUpscaleDescription)
Description
Executes the rendering command for GPU spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | VkCommandBuffer that records the current command, which must be submitted to vkQueueSubmit. Otherwise, the command cannot be executed. |
| xegSpatialUpscale | Created XEG_SpatialUpscale object. |
| pXegSpatialUpscaleDescription | Pointer to the parameter struct XEG_SpatialUpscaleDescription of the rendering command. The parameter cannot be empty. |
[h2]HMS_XEG_CmdRenderTemporalUpscale()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_CmdRenderTemporalUpscale (VkCommandBuffer commandBuffer, XEG_TemporalUpscale temporalUpscale, XEG_TemporalUpscaleDescription * pDescription)
Description
Records the rendering command for AI temporal scaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object, which must be of the primary type. |
| temporalUpscale | Created XEG_TemporalUpscale object. |
| pDescription | Pointer to the upscaling rendering input information struct XEG_TemporalUpscaleDescription. The parameter cannot be empty. |
[h2]HMS_XEG_CmdRenderNeuralUpscale()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdRenderNeuralUpscale (VkCommandBuffer commandBuffer, XEG_NeuralUpscale neuralUpscale, const XEG_NeuralUpscaleDescription *pDescription)
Description
Records the rendering command for AI spatial scaling.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| commandBuffer | Vulkan command buffer object, which must be of the primary type. |
| neuralUpscale | Created XEG_NeuralUpscale object. |
| pDescription | Pointer to the upscaling rendering input information struct XEG_NeuralUpscaleDescription. The parameter cannot be empty. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CmdSetSynchronization()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CmdSetSynchronization (VkCommandBuffer commandBuffer, const void * xegHandle )
Description
Sets the synchronization signal and waits for the rendering result to be written to a specified image. When the RTGI feature is used, it is the GI rendering result that needs to be waited for before being written to a specified image.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| commandBuffer | VkCommandBuffer that records the current command, which must be submitted to vkQueueSubmit. Otherwise, the command cannot be executed. |
| xegHandle | Created handle object. When the RTGI feature is used, the object is the created XEG_RTGI object. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CreateAdaptiveVRS()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateAdaptiveVRS (VkDevice device, XEG_AdaptiveVRSCreateInfo * pXegAdaptiveVRSCreateInfo, XEG_AdaptiveVRS * pXegAdaptiveVRS)
Description
Creates an XEG_AdaptiveVRS object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pXegAdaptiveVRSCreateInfo | Pointer to the XEG_AdaptiveVRSCreateInfo struct. The parameter cannot be empty. |
| pXegAdaptiveVRS | Pointer to the handle in which the created XEG_AdaptiveVRS is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CreateHPS()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateHPS (VkDevice device, const XEG_HPSCreateInfo * pCreateInfo, XEG_HPS * pHps )
Description
Creates an XEG_HPS object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the information struct for creating an XEG_HPS instance handle. The parameter cannot be empty. |
| pHps | Pointer to the HPS instance handle in which the created XEG_HPS is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CreateRTGI()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateRTGI (VkDevice device, const void * pCreateInfo, XEG_RTGI * pRtGI )
Description
Creates an XEG_RTGI object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the information struct for creating an XEG_RTGI object. If a DDGI handle is created, the pointer is the pointer to the XEG_DDGICreateInfo struct. If an NNGI handle is created, the pointer to the XEG_NNGICreateInfo struct. The parameter cannot be empty. |
| pRtGI | Pointer to the handle in which the created XEG_RTGI object is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CreateRTReflection()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateRTReflection (VkDevice device, const void * pCreateInfo, XEG_RTReflection * pRtReflection )
Description
Creates an XEG_RTReflection object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the information struct for creating a reflection instance handle. Currently, only the pointer of the XEG_RTReflectionCreateInfo type is supported. The parameter cannot be empty. |
| pRtReflection | Pointer to the reflection instance handle in which the created XEG_RTReflection is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CreateRTVisibleMask()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateRTVisibleMask (VkDevice device, const void * pCreateInfo, XEG_RTVisibleMask * pRTVisibleMask )
Description
Creates an XEG_RTVisibleMask object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the struct of the description information required for creating a VisibleMask instance handle. Currently, only the pointer of the XEG_RTShadowAOCreateInfo type is supported. The parameter cannot be empty. |
| pRTVisibleMask | Pointer to the VisibleMask instance handle in which the created XEG_RTVisibleMask is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CreateSpatialUpscale()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateSpatialUpscale (VkDevice device, const XEG_SpatialUpscaleCreateInfo * pXegSpatialUpscaleCreateInfo, XEG_SpatialUpscale * pXegSpatialUpscale)
Description
Creates an XEG_SpatialUpscale object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pXegSpatialUpscaleCreateInfo | Pointer to the XEG_SpatialUpscaleCreateInfo struct. The parameter cannot be empty. |
| pXegSpatialUpscale | Pointer to the handle in which the created XEG_SpatialUpscale is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CreateTemporalUpscale()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateTemporalUpscale (VkDevice device, XEG_TemporalUpscaleCreateInfo * pTemporalUpscaleInfo, XEG_TemporalUpscale * pTemporalUpscale)
Description
Creates an XEG_TemporalUpscale object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pTemporalUpscaleInfo | Pointer to the information struct XEG_TemporalUpscaleCreateInfo for creating a scaling instance handle. The parameter cannot be empty. |
| pTemporalUpscale | Pointer to the handle in which the created XEG_TemporalUpscale is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_CreateNeuralUpscale()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_CreateNeuralUpscale (VkDevice device, const XEG_NeuralUpscaleCreateInfo * pCreateInfo, XEG_NeuralUpscale * pNeuralUpscale)
Description
Creates an XEG_NeuralUpscale object.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| device | Currently used VkDevice. |
| pCreateInfo | Pointer to the information struct XEG_NeuralUpscaleCreateInfo for creating a scaling instance handle. The parameter cannot be empty. |
| pNeuralUpscale | Pointer to the handle in which the created XEG_NeuralUpscale is returned. |
Returns:
Returns VK_SUCCESS if the execution is successful; returns an error code of the VkResult type otherwise.
[h2]HMS_XEG_DestroyAdaptiveVRS()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyAdaptiveVRS (XEG_AdaptiveVRS xegAdaptiveVRS)
Description
Destroys an XEG_AdaptiveVRS object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| xegAdaptiveVRS | Created XEG_AdaptiveVRS object. |
[h2]HMS_XEG_DestroyHPS()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyHPS (XEG_HPS hps)
Description
Destroys an XEG_HPS object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| hps | XEG_HPS object to be destroyed. |
[h2]HMS_XEG_DestroyRTGI()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyRTGI (XEG_RTGI rtGI)
Description
Destroys an XEG_RTGI object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| rtGI | Created XEG_RTGI object. |
[h2]HMS_XEG_DestroyRTReflection()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyRTReflection (XEG_RTReflection rtReflection)
Description
Destroys an XEG_RTReflection object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| rtReflection | XEG_RTReflection object to be destroyed. |
[h2]HMS_XEG_DestroyRTVisibleMask()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyRTVisibleMask (XEG_RTVisibleMask rtVisibleMask)
Description
Destroys an XEG_RTVisibleMask object.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| rtVisibleMask | XEG_RTVisibleMask object to be destroyed. |
[h2]HMS_XEG_DestroySpatialUpscale()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroySpatialUpscale (XEG_SpatialUpscale xegSpatialUpscale)
Description
Destroys an XEG_SpatialUpscale object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| xegSpatialUpscale | Created XEG_SpatialUpscale object. |
[h2]HMS_XEG_DestroyTemporalUpscale()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyTemporalUpscale (XEG_TemporalUpscale temporalUpscale)
Description
Destroys an XEG_TemporalUpscale object.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| temporalUpscale | XEG_TemporalUpscale object to be destroyed. |
[h2]HMS_XEG_DestroyNeuralUpscale()
VKAPI_ATTR void VKAPI_CALL HMS_XEG_DestroyNeuralUpscale (XEG_NeuralUpscale neuralUpscale)
Description
Destroys an XEG_NeuralUpscale object.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| neuralUpscale | XEG_NeuralUpscale object to be destroyed. |
[h2]HMS_XEG_DispatchAdaptiveVRS()
GL_APICALL void GL_APIENTRY HMS_XEG_DispatchAdaptiveVRS (GLfloat * reprojectionMatrix, GLuint inputColorImage, GLuint inputDepthImage, GLuint shadingRateImage)
Description
Computes the shading rate image.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| reprojectionMatrix | Pointer to the result matrix of the computation between the current frame and the previous frame. The computation formula is as follows: (Projection matrix of the previous frame × Observation matrix of the previous frame) x (Inverse matrix of (Projection matrix of the current frame × Observation matrix of the current frame)). The matrix must be a 4 × 4 column major-order matrix. This parameter is optional. When it is not empty, the image quality is better. |
| inputColorImage | Texture ID of the color attachment containing the final rendering result of the rendering pipeline of the previous frame. |
| inputDepthImage | Texture ID of the depth attachment containing the final rendering result of the rendering pipeline of the current frame. |
| shadingRateImage | Texture ID used to generate the shading rate image information, which needs to be created and entered by the user. |
The texture type must be GL_TEXTURE_2D and mipLevels is set to 1.
[h2]HMS_XEG_EnumerateDeviceExtensionProperties()
VKAPI_ATTR VkResult VKAPI_CALL HMS_XEG_EnumerateDeviceExtensionProperties (VkPhysicalDevice physicalDevice, uint32_t * pPropertyCount, XEG_ExtensionProperties * pProperties)
Description
Queries XEngine Vulkan extensions.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| physicalDevice | Vulkan physical device in use. |
| pPropertyCount | Number of queried or passed extensions. If pProperties is set to nullptr, the number of supported XEngine extensions is returned. If the passed value of propertyCount is greater than or equal to the number of supported XEngine extensions, the query result is returned through pProperties, and the return value is VK_SUCCESS. If the passed value of propertyCount is less than the number of supported XEngine extensions, the query result is returned through pProperties, but the return value is VK_INCOMPLETE. |
| pProperties | Queried XEngine extensions, which are returned through the pointer to the XEG_ExtensionProperties struct. |
Returns:
Error code of the VkResult type. If the query is successful, VK_SUCCESS is returned. If pProperties is not set to nullptr and the input value of propertyCount is less than the actual number of supported XEngine extensions, VK_INCOMPLETE is returned, indicating that the queried features are incomplete.
[h2]HMS_XEG_GetString()
const GLubyte* HMS_XEG_GetString (GLenum name)
Description
Queries XEngine OpenGL ES extensions.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| name | Enumerated name of the input parameter. The value range is XEG_EXTENSIONS. |
Returns:
When the parameter is XEG_EXTENSIONS, a space-separated list of extensions supported by XEngine is returned. Note that the extension names do not contain spaces. If the query result is abnormal, an empty value is returned.
[h2]HMS_XEG_NeuralUpscaleParameter()
GL_APICALL void GL_APIENTRY HMS_XEG_NeuralUpscaleParameter (GLenum pname, GLvoid * param)
Description
Sets the input parameters for AI spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| pname | Enumerated name of the input parameter. The value can be XEG_NEURAL_UPSCALE_SCISSOR, XEG_NEURAL_UPSCALE_SHARPNESS, or XEG_NEURAL_UPSCALE_INPUT_HANDLE. |
| param | Input parameter value. For details, please refer to the description of the enumerated names of the input parameters. |
[h2]HMS_XEG_RenderNeuralUpscale()
GL_APICALL void GL_APIENTRY HMS_XEG_RenderNeuralUpscale (GLuint inputTexture)
Description
Executes the rendering command for AI spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| inputTexture | Scaling input texture. The input texture type is GL_TEXTURE_2D and mipLevels is set to 1. When the XEG_NEURAL_UPSCALE_EXTENSION_NAME extension is available, the texture width must be within the range [448, 1728]. Otherwise, the AI inference results may be incorrect. The input texture must be created by OH_NativeBuffer. Before calling this API, you need to set the handle corresponding to OH_NativeBuffer to the scaling input parameter. For details, please refer to the HMS_XEG_NeuralUpscaleParameter API. When the XEG_NEURAL_UPSCALE2_EXTENSION_NAME extension is available, the recommended texture width range is [448, 1792]. The input texture does not need to be created by OH_NativeBuffer. |
[h2]HMS_XEG_RenderSpatialUpscale()
GL_APICALL void GL_APIENTRY HMS_XEG_RenderSpatialUpscale (GLuint inputTexture)
Description
Executes the rendering command for GPU spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| inputTexture | Scaling input texture. The input texture type is GL_TEXTURE_2D and mipLevels is set to 1. The texture must be created before this API is called. Otherwise, rendering will fail, for example, a black screen will be displayed. |
[h2]HMS_XEG_RenderTemporalUpscale()
GL_APICALL void GL_APIENTRY HMS_XEG_RenderTemporalUpscale (GLuint inputTexture, GLuint depthTexture, GLuint motionVectorTexture, GLuint dynamicMaskTexture, GLfloat jitterX, GLfloat jitterY )
Description
Executes the rendering command for AI temporal upscaling.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| inputTexture | Scaling input texture. The input texture type is GL_TEXTURE_2D and mipLevels is set to 1. The maximum dimensions supported are 2048 × 1024. |
| depthTexture | Depth texture. |
| motionVectorTexture | Motion vector image. The motion vector is computed by subtracting the X and Y values of the NDC coordinates of the previous frame from those of the current rendered pixel. |
| dynamicMaskTexture | Dynamic mask image of an object. The format must be GL_RED or its compatible format. The valid value of the R channel is 0.0, 0.2, or 1.0, where 0.0 indicates static objects, 0.2 indicates moving objects such as people, and 1.0 indicates special effects or translucent objects. |
| jitterX | Jitter of the camera in the X direction. It is usually the sub-pixel jitter applied in the pre-rendering process on which upscaling depends and is included in the projection matrix of the camera. In the NDC coordinate system, the value range is [–1/width, 1/width], where width is the width (number of pixels) of inputTexture. |
| jitterY | Jitter of the camera in the Y direction. It is usually the sub-pixel jitter applied in the pre-rendering process on which upscaling depends and is included in the projection matrix of the camera. In the NDC coordinate system, the value range is [–1/height, 1/height], where height is the height (number of pixels) of inputTexture. |
[h2]HMS_XEG_SpatialUpscaleParameter()
GL_APICALL void GL_APIENTRY HMS_XEG_SpatialUpscaleParameter (GLenum pname, GLvoid * param)
Description
Sets the input parameters for GPU spatial upscaling.
Since: 5.0.0(12)
Parameters:
| Name | Description |
|---|---|
| pname | Enumerated name of the input parameter. The value can be XEG_SPATIAL_UPSCALE_SCISSOR or XEG_SPATIAL_UPSCALE_SHARPNESS. |
| param | Input parameter value. For details, please refer to the description of the enumerated names of the input parameters. |
[h2]HMS_XEG_TemporalUpscaleParameter()
GL_APICALL void GL_APIENTRY HMS_XEG_TemporalUpscaleParameter (GLenum pname, const GLvoid * param)
Description
Sets the input parameters for AI temporal upscaling.
Since: 6.0.0(20)
Parameters:
| Name | Description |
|---|---|
| pname | Enumerated name of the input parameter. The value can be XEG_TEMPORAL_UPSCALE_INPUT_SIZE, XEG_TEMPORAL_UPSCALE_JITTER_NUM, XEG_TEMPORAL_UPSCALE_DEPTH_REVERSED, XEG_TEMPORAL_UPSCALE_RESET_HISTORY, or XEG_TEMPORAL_UPSCALE_STEADY_LEVEL. |
| param | Input parameter value. For details, please refer to the description of the enumerated names of the input parameters. |
[h2]HMS_XEG_SetControlDisplaySeparationStatusListener()
bool HMS_XEG_SetControlDisplaySeparationStatusListener(PFN_HMS_XEG_ControlDisplaySeparationStatusCallback callback);
Description
Sets the globally unique listener for the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| callback | Callback function to be set, which cannot be empty. |
Returns:
Returns true if the setting is successful and false if the setting fails. true will be returned only when the current device supports the control-display separation feature and the app has registered this feature in module.json.
[h2]HMS_XEG_RemoveControlDisplaySeparationStatusListener()
void HMS_XEG_RemoveControlDisplaySeparationStatusListener();
Description
Removes the globally unique listener for the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
[h2]HMS_XEG_SetControlDisplaySeparationActive()
bool HMS_XEG_SetControlDisplaySeparationActive(bool flag);
Description
Sets whether to enable the control-display separation feature.
Device behavior differences: This API is supported only on some foldable phones and does not respond on other device types.
Since: 26.0.0
Parameters:
| Name | Description |
|---|---|
| flag | Status of the feature to be set. The value true indicates that the feature is enabled, and the value false indicates that the feature is disabled. |
Returns:
Returns true if the setting is successful and false if the setting fails. true will be returned only when the listener for the control-display separation feature is set and the callback of the listener is available.