OpenGTX功能开发
===========

#### 概述

OpenGTX是GPU Turbo X的开放式入口，根据游戏开发者主动提供的游戏过程中的关键信息，使能LTPO（动态帧率/刷新率）等游戏加速方案，助力游戏开发者打造高画质、高流畅、低功耗极致体验。LTPO通过动态感知游戏渲染状态、游戏场景、设备状态等关键信息，动态调整游戏的帧率/刷新率以及设备的SOC/DDR频率。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1a/v3/FK36neS3SvaOyXW9roKDTg/zh-cn_image_0000002664208601.png?HW-CC-KV=V1&HW-CC-Date=20260709T132550Z&HW-CC-Expire=86400&HW-CC-Sign=1C4F65496D03E7EE6FE9138DEF499267EA7E6B9917FB6D1BB0B5E06EA6DC8658)

#### 业务流程

LTPO的主要业务流程如下：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/33/v3/uSaNEPlASPqoLMHYBPB_Wg/zh-cn_image_0000002664328661.png?HW-CC-KV=V1&HW-CC-Date=20260709T132550Z&HW-CC-Expire=86400&HW-CC-Sign=20C0CFCE7546E6A8CB125F18BA2E57A5E74C2F55E2CAA8885ACA0DD986A437B9)

1.  用户进入游戏。
    
2.  游戏应用调用[HMS\_OpenGTX\_CreateContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_createcontext)接口创建OpenGTX上下文实例。
    
3.  游戏应用调用[HMS\_OpenGTX\_SetConfiguration](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_setconfiguration)接口初始化配置实例属性，包含LTPO模式、目标帧率、包名、游戏类型、分辨率、游戏关键线程等属性。
    
4.  游戏应用调用[HMS\_OpenGTX\_Activate](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_activate)接口激活OpenGTX上下文实例。
    
5.  游戏切换不同游戏场景后调用[HMS\_OpenGTX\_DispatchGameSceneInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_dispatchgamesceneinfo)接口发送游戏场景信息，包含场景类型、指定帧率、调度帧率范围、当前分辨率等信息。
    
6.  游戏应用在每帧渲染前调用[HMS\_OpenGTX\_DispatchFrameRenderInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_dispatchframerenderinfo)接口发送游戏帧渲染信息，包含游戏主相机的位置和欧拉角。
    
7.  游戏应用在每帧渲染前如遇到网络时延档位变化，调用[HMS\_OpenGTX\_DispatchNetworkInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_dispatchnetworkinfo)接口发送游戏网络信息，包含服务器IP地址、网络时延等信息。
    
8.  游戏应用正常绘制。
    
9.  一帧送显。
    
10.  每帧结束，将帧尾决策帧率、决策设备频率通知到设备。
     
11.  用户退出游戏。
     
12.  游戏应用调用[HMS\_OpenGTX\_DestroyContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_destroycontext)接口销毁OpenGTX上下文实例并释放内存资源。
     

#### 开发步骤

本节介绍OpenGTX的开发接入，从流程上分别阐述每个步骤的实现和调用。详细代码请参考[OpenGTX Sample](https://gitcode.com/harmonyos_samples/open-gtx-samplecode-clientdemo-cpp)。

#### \[h2\]设置项目配置项

在“src/main/module.json5”的module层级中添加以下配置。

"metadata": \[
  {
    "name": "GraphicsAccelerateKit\_LTPO",
    "value": "true"
  }
\]

#### \[h2\]头文件引用

引用Graphics Accelerate Kit OpenGTX头文件：opengtx\_base.h。

// 引用OpenGTX头文件 opengtx\_base.h
#include <graphics\_game\_sdk/opengtx\_base.h>

#### \[h2\]编写CMakeLists.txt

find\_library(
    # Sets the name of the path variable.
    opengtx-lib
    # Specifies the name of the NDK library that you want CMake to locate.
    libopengtx.so
)
find\_library(
    # Sets the name of the path variable.
    GLES-lib
    # Specifies the name of the NDK library that you want CMake to locate.
    GLESv3
)
find\_library(
    # Sets the name of the path variable.
    hilog-lib
    # Specifies the name of the NDK library that you want CMake to locate.
    hilog\_ndk.z
)

target\_link\_libraries(entry PUBLIC
    ${opengtx-lib} ${GLES-lib} ${hilog-lib}
)

#### \[h2\]OpenGTX初始化

在surface创建后，会触发其事件回调函数Core::OnSurfaceCreated()，在该函数中完成OpenGTX上下文实例创建、OpenGTX属性配置和功能激活。其中OpenGTX上下文实例负责管理OpenGTX整个生命周期。

1.  调用[HMS\_OpenGTX\_CreateContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_createcontext)接口创建OpenGTX上下文实例。如果返回nullptr，则说明OpenGTX上下文实例创建失败，或当前硬件设备不支持开启OpenGTX。
    
    // 创建OpenGTX上下文实例
    OpenGTX\_Context \*context\_ = HMS\_OpenGTX\_CreateContext(nullptr);
    if (context\_ == nullptr) {
        return false;
    }
    
2.  调用[HMS\_OpenGTX\_SetConfiguration](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_setconfiguration)接口属性配置，包含LTPO模式、目标帧率、包名、游戏类型、分辨率、游戏关键线程等属性。
    
    // 初始化OpenGTX接口调用错误码
    OpenGTX\_ErrorCode errorCode = OPENGTX\_SUCCESS;
    // OpenGTX属性配置结构体
    OpenGTX\_ConfigDescription config;
    // LTPO调度模式
    config.mode = ADAPTIVE\_MODE;
    // 游戏设置目标帧率
    config.targetFPS = 120;
    // 游戏包名
    config.packageName = (char\*)"OpenGTX";
    // 游戏版本
    config.appVersion = (char\*)"1.1.0";
    // 引擎类型
    config.engineType = UNREAL;
    // 引擎版本
    config.engineVersion = (char\*)"4.26.2";
    // 游戏类别
    config.gameType = RPG;
    // 游戏最高画质等级
    config.pictureQualityMaxLevel = HD;
    // 游戏设置最大分辨率
    config.resolutionMaxValue = OpenGTX\_ResolutionValue { 1280, 720};
    // 游戏逻辑线程
    config.gameMainThreadId = 11;
    // 游戏渲染线程
    config.gameRenderThreadId = 11;
    // 游戏运行其他关键线程
    config.gameKeyThreadIds\[0\] = 0;
    config.gameKeyThreadIds\[1\] = 0;
    config.gameKeyThreadIds\[2\] = 0;
    config.gameKeyThreadIds\[3\] = 0;
    config.gameKeyThreadIds\[4\] = 0;
    // 游戏图形API是否为Vulkan
    config.vulkanSupport = false;
    // 初始化OpenGTX实例，配置OpenGTX属性
    errorCode = HMS\_OpenGTX\_SetConfiguration(context\_, &config);
    if (errorCode != OPENGTX\_SUCCESS) {
        return false;
    }
    
3.  调用[HMS\_OpenGTX\_Activate](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_activate)接口激活OpenGTX上下文实例。
    
    // 激活OpenGTX上下文实例
    errorCode = HMS\_OpenGTX\_Activate(context\_);
    if (errorCode != OPENGTX\_SUCCESS) {
        return false;
    }
    
4.  调用[HMS\_OpenGTX\_Deactivate](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_deactivate)接口去激活OpenGTX上下文实例。（在需要关闭OpenGTX功能时调用此接口。去激活后，调用[HMS\_OpenGTX\_DispatchGameSceneInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_dispatchgamesceneinfo)等接口将不会生效）。
    
    // 去激活OpenGTX上下文实例
    errorCode = HMS\_OpenGTX\_Deactivate(context\_);
    if (errorCode != OPENGTX\_SUCCESS) {
        return false;
    }
    

#### \[h2\]OpenGTX关键信息更新

1.  游戏切换不同游戏场景后调用[HMS\_OpenGTX\_DispatchGameSceneInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_dispatchgamesceneinfo)接口发送游戏场景信息，包含场景类型、指定帧率、调度帧率范围、当前分辨率等信息。
    
    // OpenGTX游戏场景信息结构体
    OpenGTX\_GameSceneInfo gameSceneInfo;
    // 游戏场景类型ID
    gameSceneInfo.sceneID = OTHERS\_SCENE;
    // 游戏场景描述
    gameSceneInfo.description = (char\*)"其他场景";
    // 游戏场景推荐帧率
    gameSceneInfo.recommendFPS = 60;
    // 游戏场景最小帧率
    gameSceneInfo.minFPS = 30;
    // 游戏场景最大帧率
    gameSceneInfo.maxFPS = 90;
    // 屏幕分辨率 高度
    gameSceneInfo.resolutionCurValue.height = 360;
    // 屏幕分辨率 宽度
    gameSceneInfo.resolutionCurValue.width = 1920;
    // OpenGTX接收游戏场景信息
    errorCode = HMS\_OpenGTX\_DispatchGameSceneInfo(context\_, &gameSceneInfo);
    if (errorCode != OPENGTX\_SUCCESS) {
        return false;
    }
    
2.  每帧渲染前调用[HMS\_OpenGTX\_DispatchFrameRenderInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_dispatchframerenderinfo)接口发送游戏帧渲染信息，包含游戏主相机的位置和欧拉角。
    
    // OpenGTX游戏渲染信息结构体
    OpenGTX\_FrameRenderInfo frameRenderInfo;
    // 主相机位置
    frameRenderInfo.mainCameraPosition = { 0.0f, 0.0f, 0.0f };
    // 主相机欧拉角
    frameRenderInfo.mainCameraRotate = { 0.0f, 0.0f, 0.0f };
    // OpenGTX接收游戏渲染信息
    errorCode = HMS\_OpenGTX\_DispatchFrameRenderInfo(context\_, &frameRenderInfo);
    if (errorCode != OPENGTX\_SUCCESS) {
        return false;
    }
    
3.  每帧渲染前如遇到网络时延档位变化，调用[HMS\_OpenGTX\_DispatchNetworkInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_dispatchnetworkinfo)接口发送游戏网络信息。包含服务器IP地址、网络时延等信息。
    
    // OpenGTX游戏网络信息结构体
    OpenGTX\_NetworkInfo networkInfo;
    // OpenGTX游戏网络时延结构体
    OpenGTX\_NetworkLatency networkLatency;
    // 网络总时延
    networkLatency.total = 50;
    // 网络上行时延
    networkLatency.up = 10;
    // 网络下行时延
    networkLatency.down = 40;
    // 游戏网络时延
    networkInfo.networkLatency = networkLatency;
    // 游戏服务器IP地址
    networkInfo.networkServerIP = (char\*)"10.10.10.10";
    // OpenGTX接收游戏网络信息
    errorCode = HMS\_OpenGTX\_DispatchNetworkInfo(context\_, &networkInfo);
    if (errorCode != OPENGTX\_SUCCESS) {
        return false;
    }
    

#### \[h2\]销毁OpenGTX实例

在surface销毁时，会触发其事件回调函数Core::OnSurfaceDestroyed()，在该函数中完成OpenGTX实例的销毁。

调用[HMS\_OpenGTX\_DestroyContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/_graphics_accelerate#hms_opengtx_destroycontext)接口销毁OpenGTX实例，释放内存资源。

// 销毁OpenGTX上下文实例并释放内存资源
errorCode = HMS\_OpenGTX\_DestroyContext(&context\_);
if (errorCode != OPENGTX\_SUCCESS) {
    return false;
}