XEngine Kit provides an innovative solution for control-display separation on foldable devices. In the unfolded state, this solution divides the screen into two symmetrical independent areas, deeply restoring the interaction logic of retro handheld game consoles. The upper half of the screen displays the core rendering image, while the lower half focuses on touch control.

Restrictions

This feature is supported only on some foldable devices.
You can check whether the relevant extension feature is supported as follows:

Currently, this feature is supported only on games developed based on Vulkan APIs. You can use the HMS_XEG_SetControlDisplaySeparationStatusListener API to check whether the feature is supported. If the return value is true, the current hardware system supports this feature, and the game can explicitly display the feature switch and allow the feature to be enabled. If the return value is false, this feature is not supported, and the game must hide the feature switch and prohibit the feature from being enabled.

API Description

The following APIs are required for the control-display separation feature. For details about these APIs, please refer to API Reference.

API	Description
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.

Service Process

Environment configuration: The game app needs to declare the control-display separation feature in the module.json5 configuration file to enable system-level adaptation.
Setting the callback function for listening to the feature: After the user taps to start the game, the app calls HMS_XEG_SetControlDisplaySeparationStatusListener to set the callback function for listening to the control-display separation feature. If the return value is true, the feature switch is displayed. Otherwise, the feature switch is not displayed.
User configuration identification: Users can choose to enable or disable the feature. When a user enables the feature, the game app sets the user configuration switch (isFeatureOn) to true. When a user disables the feature, the game app sets the user configuration switch to false.
Feature scene identification: The game app identifies the current game scene. Based on the identification result, you can set the scene configuration switch (isActive) to true or false.
Calling the listening callback function: A user can choose to unfold or fold the device. When the user chooses to unfold or fold the device, XEngine Kit calls the listening callback function to notify the game app.
Device status identification: The game app sets the device status (status) based on the input parameters of the callback function.
Game resolution adjustment: When the user configuration switch (isFeatureOn) is set to true, the scene configuration switch (isActive) is set to true, and the device status (status) is AVAILABLE, the control-display separation feature is enabled. In this case, the game app changes the height of the game resolution to half of the original height. Otherwise, the height of the game resolution is the same as that of the unfolded device.
(Optional) Key UI element marking: When the control-display separation feature is enabled, XEngine Kit will place the main view of the game on the upper half of the screen and other UI elements (such as operation buttons) on the lower half by default. To display a specific UI element on the upper half of the screen, you need to mark it as a key UI element. For details, please refer to step 7 in the development procedure.
(Optional) Information sub-screen rendering: If a game app wants to render additional content on the lower half of the screen when the control-display separation feature is enabled, it can directly render the content in the current scene.
Triggering the control-display separation feature: When the user configuration switch (isFeatureOn) is true, the scene configuration switch (isActive) is true, and the device status (status) is AVAILABLE, the game app calls HMS_XEG_SetControlDisplaySeparationActive(true) to enable control-display separation. Otherwise, the game app calls HMS_XEG_SetControlDisplaySeparationActive(false) to disable control-display separation.
Destroying the listening callback function of the feature: When the user exits the app or no longer uses this feature, call HMS_XEG_RemoveControlDisplaySeparationStatusListener to deregister the listener and release related resources.

Development Procedure

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

[h2]Configuring Your Project

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

Header file reference

#include "xengine/xeg_control_display_separation.h"

CMakeLists.txt configuration

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

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

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

[h2]Integrating the Control-Display Separation Feature of XEngine Kit (Vulkan)

Vulkan graphics APIs are used to set up the image rendering pipeline and integrate the control-display separation feature at the native layer. The rendering results are displayed on the screen through XComponent.

Before calling the control-display separation feature of XEngine Kit, declare this feature in the module.json5 configuration file of your game app. For details about the configuration scheme, please refer to configuration of the metadata field in the module.json5 file.
```
"metadata": [
  {
    "name": "XEngineKit_ControlDisplaySeparation",
    "value": "true"
  }
],
```

Initialize the control variables required for control-display separation.

// Whether the current hardware system supports this feature.
static bool isSystemSupport = false;
// Device status, which is used to describe whether the current status allows the feature to be enabled (for example, the feature can be enabled in the unfolded state but cannot in the folded state of a foldable device).
static XEG_ControlDisplaySeparationStatus status = XEG_ControlDisplaySeparationStatus::UNAVAILABLE;
// User configuration switch, which is used to describe whether the user or the game itself enables this feature. (Currently, this feature is enabled by default, and the primary use is determined by the user.)
static bool isFeatureOn = false;
// Feature enabling switch, which is used to describe whether the control-display separation feature is enabled in the current scene (for example, disabled in the game hall scene and enabled in the game battle scene).
static bool isActive = false;

After the game is launched, call HMS_XEG_SetControlDisplaySeparationStatusListener to register a status listener callback. The return value (the status is recorded in isSystemSupport) of the API is used to determine whether the current hardware system supports the control-display separation feature. If this feature is supported, XEngine Kit monitors the physical form of the device screen in real time and returns the current status through the registered callback function to indicate whether the feature can be enabled (for example, the feature can be enabled when the foldable screen is unfolded but cannot be enabled when the screen is folded). The status is recorded in status.
```
// Status callback function.
void ControlDisplaySeparationHandler(XEG_ControlDisplaySeparationStatus controlDisplaySeparationStatus)
{
    status = controlDisplaySeparationStatus;
    // Update the status of the control-display separation feature.
    UpdateControlDisplaySeparation();
}

void setCallBack()
{
    // Register the control-display separation status listener. If the registration is successful, the current device supports the control-display separation feature. Otherwise, the device does not support this feature.
    isSystemSupport = HMS_XEG_SetControlDisplaySeparationStatusListener(ControlDisplaySeparationHandler);
}
```
Set the feature switch. When a user taps the settings screen, the game app can provide the feature switch option if the device supports the feature, and assign the feature switch status to isFeatureOn.
Game scene identification: When the device status allows and the user has enabled the feature, the game app needs to identify whether the current game scene (for example, in a match) requires the feature to be triggered. The status is recorded in isActive.

Update the status of the display separation feature. When the value of any of status, isFeatureOn, and isActive changes, the status update logic needs to be triggered. The app needs to call HMS_XEG_SetControlDisplaySeparationActive to enable the feature only when the value of status is AVAILABLE and both isFeatureOn and isActive are true. In this case, the system separates the main view and other UI elements on the upper and lower half of the screen. After the feature is enabled, the game must set the rendering resolution to half of the full-screen height to ensure normal display. If you need to display specific UI element on the upper half of the screen or render additional information on the lower half of the screen, refer to steps 7 and 8, respectively.

void UpdateControlDisplaySeparation()
{
    // Enable control-display separation.
    if (isFeatureOn == true && status == XEG_ControlDisplaySeparationStatus::AVAILABLE && isActive == true) {
        if (HMS_XEG_SetControlDisplaySeparationActive(true)) {
            // Enabled successfully.
            // Call the resolution setting API of the game engine to set the height of the rendering resolution to half of the original height.
            // (Optional) Mark key UI elements. UI elements marked as key ones can be rendered to the upper half of the screen.
            // (Optional) Render the additional information on the sub-screen using the same render pass as other UI elements.
            updateResolution();
        } else {
            // Enabling failed.
            isActive = false;
        }
    } else {
        // Disable control-display separation.
        if (HMS_XEG_SetControlDisplaySeparationActive(false)) {
            // Call the resolution setting API of the game engine to set the height of the rendering resolution to the height of the full screen.
            updateResolution();
        } else {
            // Disabling failed. Further locate the cause.
        }
    }
}

(Optional) Mark key UI elements. By default, the control-display separation feature renders the main view on the upper half of the screen and other UI elements on the lower half. If you want to retain specific UI elements such as the health bar and character name on the upper half of the screen, you need to mark them when the feature is enabled. You can use the template value marking scheme to set a unified label for the target UI elements in advance. When the feature takes effect, set the template value to be greater than or equal to 128 for these UI elements. In this way, the underlying layer of the system can identify and render these UI elements on the upper half of the screen.
(Optional) Set information sub-screen. In the control-display separation mode, the UI layout designed on both sides of the screen to avoid the central view will result in a large blank area in the central region on the lower half of the screen. You game app can utilize this region to display additional information, such as the game scoreboard and real-time battle reports, to enrich the interaction experience. The implementation of the information content is the same as that of regular UI elements. You can directly render the content in the current scene.
When the user exits the game scene where control-display separation is applicable, call HMS_XEG_RemoveControlDisplaySeparationStatusListener to cancel the registration of the control-display separation listener.
```
HMS_XEG_RemoveControlDisplaySeparationStatusListener();
```