service_cpp

service_cpp 模块提供图形服务功能，包含图形事件处理与图形服务管理。

Class Summary

OHOS::GraphicEventHandler

图形事件处理器，管理事件队列并按序执行已投递的图形任务

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetInstance	获取 GraphicEventHandler 单例实例
  Run	启动事件循环，按序处理事件队列中的任务
  PostGraphicEvent	向事件队列投递一个图形任务
  ClearGraphicEvent	清空事件队列中的所有待处理任务

• 使用包含头文件：#include "graphic_event_handler.h"

• 声明头文件：middleware/services/gui/uikit/proprietary/include/service/graphic_event_handler.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

GraphicService

图形服务类，提供图形任务的同步/异步触发、Vsync 回调注册、屏幕状态管理及 GPU 重置等能力

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetInstance	获取 GraphicService 单例实例
  RegJSVsyncCallback	注册 JS 应用的 Vsync 回调函数
  SyncTriggerJSGraphicTask	同步触发 JS 图形任务处理
  AsyncTriggerNativeGraphicTask	异步触发 Native 图形任务处理
  UpdateGraphicEvent	更新图形事件，通知 Vsync 事件线程
  SetNativeUIRunning	设置 Native UI 的运行状态
  IsNativeRunning	查询 Native UI 是否正在运行
  IsNativeUITask	判断当前线程是否为 Native UI 任务线程
  IsScreenOn	查询屏幕是否处于亮屏状态
  GetGraphicTaskTriggeredCount	获取已触发的图形任务计数
  PostGraphicEvent	向异步线程投递图形事件任务
  NotifyScreenOn	通知屏幕已亮屏
  NotifyScreenOff	通知屏幕已息屏
  EnableAsyncMode	设置异步渲染模式开关
  InitGraphicService	初始化图形服务
  GpuResetStart	通知 GPU 重置开始
  GpuResetEnd	通知 GPU 重置结束
  ForceRefreshImmediately	强制立即刷新图形画面
  NativeMainThread	Native 主线程入口函数
  VsyncEventThread	Vsync 事件线程入口函数

• 使用包含头文件：#include "graphic_service.h"

• 声明头文件：middleware/services/gui/uikit/proprietary/include/service/graphic_service.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::GraphicEventHandler

GetInstance

static GraphicEventHandler* GetInstance()

功能说明

• 核心用途：获取 GraphicEventHandler 的全局单例实例
• 设计目的：保证全局唯一的事件处理器实例，统一管理图形事件队列
• 使用场景：投递或处理图形事件的入口，其他图形事件接口基于此单例实例进行操作

返回值

• 返回类型：GraphicEventHandler*

返回 GraphicEventHandler 单例指针

返回值	触发场景
非 nullptr	始终返回静态实例地址

Run

void Run()

功能说明

• 核心用途：启动事件循环，按序从事件队列中取出任务并执行
• 设计目的：作为图形事件处理的主循环，保证任务按投递顺序依次执行
• 使用场景：由 Native 主线程入口调用，进入后不再返回

前置条件

• GraphicEventHandler 单例已通过 GetInstance() 获取
• 事件队列互斥锁 queueMutex_ 已初始化成功

PostGraphicEvent

void PostGraphicEvent(const GraphicEvent& event, bool exitLowPower = true)

功能说明

• 核心用途：向事件队列投递一个图形任务
• 设计目的：提供线程安全的任务投递接口，支持投递后唤醒事件循环
• 使用场景：JS 应用或 Native 应用需要异步执行图形操作时调用

入参

名称	参数类型	详细说明	约束取值范围
event	const GraphicEvent&	入参只读引用，待投递的图形任务（std::function 包装）	有效的可调用对象
exitLowPower	bool	入参只读，是否在执行任务前退出低功耗模式	true：退出低功耗后执行（默认）；false：不退出低功耗直接执行

Kconfig 配置

配置项	说明	默认值
ENABLE_DYNAMIC_FRAME_RATE	启用动态帧率控制，exitLowPower 参数在启用时生效	n

ClearGraphicEvent

void ClearGraphicEvent()

功能说明

• 核心用途：清空事件队列中所有待处理的图形任务
• 设计目的：在 GPU 重置等场景下快速丢弃所有未执行任务，避免执行过期操作
• 使用场景：GPU 重置开始时调用，清空残留任务

GraphicService

GetInstance

static GraphicService* GetInstance()

功能说明

• 核心用途：获取 GraphicService 的全局单例实例
• 设计目的：保证全局唯一的图形服务实例，统一管理图形任务调度与屏幕状态
• 使用场景：访问图形服务功能的入口，其他图形服务接口基于此单例实例进行操作

返回值

• 返回类型：GraphicService*

返回 GraphicService 单例指针

返回值	触发场景
非 nullptr	始终返回静态实例地址

RegJSVsyncCallback

void RegJSVsyncCallback(VsyncCallback callback)

功能说明

• 核心用途：注册 JS 应用的 Vsync 回调函数
• 设计目的：为 JS 应用提供每帧 Vsync 信号的通知能力，驱动 JS 图形渲染
• 使用场景：JS 应用初始化时注册 Vsync 回调，在每帧 Vsync 到来时触发回调

入参

名称	参数类型	详细说明	约束取值范围
callback	VsyncCallback	入参只读，Vsync 回调函数（std::function 类型）	有效的可调用对象

SyncTriggerJSGraphicTask

bool SyncTriggerJSGraphicTask()

功能说明

• 核心用途：同步触发 JS 图形任务处理
• 设计目的：在 Native 未运行且屏幕亮屏时，同步执行 JS 应用的 TaskHandler
• 使用场景：Vsync 事件线程检测到当前为 JS 模式时，同步调用 JS 图形任务

返回值

• 返回类型：bool

返回任务触发结果

返回值	触发场景
true(1)	成功触发 JS 图形任务
false(0)	Native UI 正在运行；或图形任务已触发；或屏幕已息屏

AsyncTriggerNativeGraphicTask

static bool AsyncTriggerNativeGraphicTask()

功能说明

• 核心用途：异步触发 Native 图形任务处理
• 设计目的：将 Native 图形任务投递到异步线程执行，避免阻塞调用线程
• 使用场景：Vsync 事件线程检测到当前为 Native 模式时，异步投递图形任务

返回值

• 返回类型：bool

返回任务投递结果

返回值	触发场景
true(1)	成功投递 Native 图形任务到异步线程
false(0)	已触发的图形任务计数超过阈值（>1），拒绝重复投递

UpdateGraphicEvent

void UpdateGraphicEvent()

功能说明

• 核心用途：更新图形事件，发送信号通知 Vsync 事件线程
• 设计目的：在每帧渲染完成或需要刷新时通知 Vsync 事件线程继续处理
• 使用场景：外部模块需要触发图形刷新时调用

前置条件

• Vsync 事件条件变量 vsyncEventCond_ 已初始化
• GPU 未处于重置状态（isGpuReseting 为 false）

SetNativeUIRunning

void SetNativeUIRunning(bool isRunning)

功能说明

• 核心用途：设置 Native UI 的运行状态
• 设计目的：在 JS 与 Native 模式切换时标记 Native UI 是否运行，控制任务调度策略
• 使用场景：Native 应用启动或停止时调用，通知图形服务切换模式

入参

名称	参数类型	详细说明	约束取值范围
isRunning	bool	入参只读，Native UI 是否正在运行	true：Native UI 运行中；false：Native UI 已停止

IsNativeRunning

int IsNativeRunning() const

功能说明

• 核心用途：查询 Native UI 是否正在运行
• 设计目的：通过原子变量读取 Native UI 运行状态，线程安全
• 使用场景：任务调度时判断当前是否为 Native 模式

返回值

• 返回类型：int

返回 Native UI 运行状态

返回值	触发场景
1	Native UI 正在运行
0	Native UI 未运行

IsNativeUITask

static bool IsNativeUITask()

功能说明

• 核心用途：判断当前线程是否为 Native UI 任务线程
• 设计目的：通过线程 ID 比对确定调用上下文，避免跨线程误操作
• 使用场景：需要判断当前代码是否在 GUI 主线程上执行

返回值

• 返回类型：bool

返回当前线程判断结果

返回值	触发场景
true(1)	当前线程为 Native UI 主线程
false(0)	当前线程非 Native UI 主线程

IsScreenOn

int IsScreenOn() const

功能说明

• 核心用途：查询屏幕是否处于亮屏状态
• 设计目的：通过原子变量读取屏幕状态，线程安全
• 使用场景：图形任务调度时判断是否需要执行渲染

返回值

• 返回类型：int

返回屏幕亮灭状态

返回值	触发场景
1	屏幕亮屏
0	屏幕息屏

GetGraphicTaskTriggeredCount

int GetGraphicTaskTriggeredCount() const

功能说明

• 核心用途：获取已触发的图形任务计数
• 设计目的：通过原子变量读取任务触发计数，用于流控判断
• 使用场景：任务调度时判断是否已有足够的待处理任务，避免重复投递

返回值

• 返回类型：int

返回已触发的图形任务数量

返回值	触发场景
>= 0	当前已触发但未完成的图形任务数量

PostGraphicEvent

void PostGraphicEvent(const OHOS::GraphicEvent& event)

功能说明

• 核心用途：向异步线程投递图形事件任务
• 设计目的：封装 GraphicEventHandler 的 PostGraphicEvent 调用，提供统一的任务投递入口
• 使用场景：需要将图形任务投递到异步线程执行

入参

名称	参数类型	详细说明	约束取值范围
event	const OHOS::GraphicEvent&	入参只读引用，待投递的图形事件任务	有效的可调用对象

NotifyScreenOn

void NotifyScreenOn()

功能说明

• 核心用途：通知屏幕已亮屏
• 设计目的：设置屏幕状态为亮屏，并触发全屏刷新
• 使用场景：屏幕点亮时由系统调用

Kconfig 配置

配置项	说明	默认值
SUPPORT_OHOSFWK	支持 OHOS 框架层，启用时触发亮屏事件通知	n

NotifyScreenOff

void NotifyScreenOff()

功能说明

• 核心用途：通知屏幕已息屏
• 设计目的：设置屏幕状态为息屏，并关闭异步渲染模式刷新残留帧
• 使用场景：屏幕熄灭时由系统调用

Kconfig 配置

配置项	说明	默认值
SUPPORT_OHOSFWK	支持 OHOS 框架层，启用时触发息屏事件通知	n

EnableAsyncMode

void EnableAsyncMode(bool enable)

功能说明

• 核心用途：设置异步渲染模式开关
• 设计目的：控制图形渲染引擎的异步模式，默认关闭

前置条件

• 调用上下文约束：需在 uikit 主线程中调用
• 调用时序约束：释放资源前需先关闭异步模式（enable = false）

入参

名称	参数类型	详细说明	约束取值范围
enable	bool	入参只读，是否启用异步渲染模式	true：启用异步模式；false：关闭异步模式（默认）

InitGraphicService

bool InitGraphicService()

功能说明

• 核心用途：初始化图形服务
• 设计目的：完成图形子系统初始化，包括图形引擎、输入设备、根视图、Vsync 事件线程和 GUI 主线程
• 使用场景：系统启动时调用，完成图形服务全部初始化流程

返回值

• 返回类型：bool

返回初始化结果

返回值	触发场景
true(1)	图形服务初始化成功
false(0)	LCD 未连接；或 Vsync 事件线程创建失败；或 GUI 主线程创建失败

GpuResetStart

void GpuResetStart(void)

功能说明

• 核心用途：通知 GPU 重置开始
• 设计目的：标记 GPU 进入重置状态，清空事件队列和任务计数，避免重置期间执行过期操作
• 使用场景：GPU 发生异常需重置时调用

Kconfig 配置

配置项	说明	默认值
SUPPORT_GPU_JPEG	支持 GPU JPEG 解码，启用时调用 JPEG 子系统重置	n

GpuResetEnd

void GpuResetEnd(void)

功能说明

• 核心用途：通知 GPU 重置结束
• 设计目的：清除 GPU 重置状态标记，恢复正常图形任务调度
• 使用场景：GPU 重置完成后调用

ForceRefreshImmediately

void ForceRefreshImmediately()

功能说明

• 核心用途：强制立即刷新图形画面
• 设计目的：在需要立即刷新画面时投递高优先级渲染任务，确保画面及时更新
• 使用场景：需要跳过正常调度直接刷新画面时调用

Kconfig 配置

配置项	说明	默认值
ENABLE_VGU_ENGINE	启用 VGU 硬件图形引擎，启用时在刷新后同步执行硬件绘制	n

NativeMainThread

static void NativeMainThread(void* args)

功能说明

• 核心用途：Native 主线程入口函数
• 设计目的：作为 GUI 主线程的执行入口，启动事件循环处理图形任务
• 使用场景：由线程创建函数调用，作为 GUI 主线程的运行体

入参

名称	参数类型	详细说明	约束取值范围
args	void*	入参指针，线程创建时传入的参数	未使用，可为 nullptr

VsyncEventThread

static void VsyncEventThread(void* args)

功能说明

• 核心用途：Vsync 事件线程入口函数
• 设计目的：在 Vsync 信号到来时根据当前模式（JS/Native）触发对应的图形任务处理
• 使用场景：由线程创建函数调用，作为 Vsync 事件线程的运行体

入参

名称	参数类型	详细说明	约束取值范围
args	void*	入参指针，线程创建时传入的参数	未使用，可为 nullptr

Type definitions

OHOS::GraphicEvent

using GraphicEvent = std::function<void()>;

使用说明：作为 PostGraphicEvent 接口的入参类型，封装图形任务的可调用对象

VsyncCallback

using VsyncCallback = std::function<void()>;

使用说明：作为 RegJSVsyncCallback 接口的入参类型，封装 Vsync 回调的可调用对象