输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS 5.0.1(13)

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
Created with Pixso.
元服务API集不筛选
您当前浏览的HarmonyOS 5.0.1(API 13)文档归档不再维护，推荐您使用最新版本。详细请参考文档维护策略变更。
API参考图形ArkGraphics 2D（方舟2D图形服务）C API模块NativeVsync

NativeVsync

更新时间: 2025-03-14 09:23
本文导读
展开章节

概述

提供获取系统vsync回调的功能，可用于实现应用的绘制帧率与系统帧率同步。

@syscap SystemCapability.Graphic.Graphic2D.NativeVsync

起始版本:

9

汇总

文件

展开
名称 描述
native_vsync.h

定义获取和使用NativeVsync的相关函数。

引用文件： <native_vsync/native_vsync.h>

库： libnative_vsync.so

类型定义

展开
名称 描述
typedef enum OHNativeErrorCode OHNativeErrorCode 接口错误码说明（仅用于查询）。
typedef struct OH_NativeVSync OH_NativeVSync 提供OH_NativeVSync结构体声明。
typedef void(* OH_NativeVSync_FrameCallback) (long long timestamp, void *data) VSync回调函数类型。

枚举

展开
名称 描述

OHNativeErrorCode {

NATIVE_ERROR_OK = 0, NATIVE_ERROR_INVALID_ARGUMENTS = 40001000, NATIVE_ERROR_NO_PERMISSION = 40301000, NATIVE_ERROR_NO_BUFFER = 40601000,

NATIVE_ERROR_NO_CONSUMER = 41202000, NATIVE_ERROR_NOT_INIT = 41203000, NATIVE_ERROR_CONSUMER_CONNECTED = 41206000, NATIVE_ERROR_BUFFER_STATE_INVALID = 41207000,

NATIVE_ERROR_BUFFER_IN_CACHE = 41208000, NATIVE_ERROR_BUFFER_QUEUE_FULL = 41209000, NATIVE_ERROR_BUFFER_NOT_IN_CACHE = 41210000,NATIVE_ERROR_CONSUMER_DISCONNECTED = 41211000,NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED = 41212000, NATIVE_ERROR_UNSUPPORTED = 50102000,

NATIVE_ERROR_UNKNOWN = 50002000,NATIVE_ERROR_HDI_ERROR = 50007000,NATIVE_ERROR_BINDER_ERROR = 50401000,

NATIVE_ERROR_EGL_STATE_UNKNOWN = 60001000, NATIVE_ERROR_EGL_API_FAILED = 60002000

}

 接口错误码说明（仅用于查询）。

函数

展开
名称 描述
OH_NativeVSync_Create (const char *name, unsigned int length) 创建一个OH_NativeVSync实例，每次调用都会产生一个新的实例。
OH_NativeVSync_Destroy (OH_NativeVSync *nativeVsync) 销毁OH_NativeVSync实例。
int OH_NativeVSync_RequestFrame (OH_NativeVSync *nativeVsync, OH_NativeVSync_FrameCallback callback, void *data) 请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，则只会触发最后一个回调。
int OH_NativeVSync_RequestFrameWithMultiCallback (OH_NativeVSync *nativeVsync, OH_NativeVSync_FrameCallback callback, void *data) 请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。
OH_NativeVSync_GetPeriod (OH_NativeVSync *nativeVsync, long long *period) 获取vsync周期。

类型定义说明

OH_NativeVSync

收起
自动换行
深色代码主题
复制
  1. typedef struct OH_NativeVSync OH_NativeVSync

描述:

提供OH_NativeVSync结构体声明。

OH_NativeVSync_FrameCallback

收起
自动换行
深色代码主题
复制
  1. typedef void(* OH_NativeVSync_FrameCallback) (long long timestamp, void *data)

描述:

VSync回调函数类型。

@syscap SystemCapability.Graphic.Graphic2D.NativeVsync

参数:

展开
名称 描述
timestamp VSync使用CLOCK_MONOTONIC获取的系统时间戳, 单位为纳秒。
data 用户自定义数据。

OHNativeErrorCode

收起
自动换行
深色代码主题
复制
  1. typedef enum OHNativeErrorCode OHNativeErrorCode

描述

接口错误码说明（仅用于查询）。

起始版本： 12

枚举类型说明

OHNativeErrorCode

收起
自动换行
深色代码主题
复制
  1. enum OHNativeErrorCode

描述

接口错误码说明（仅用于查询）。

起始版本： 12

展开
枚举值 描述
NATIVE_ERROR_OK 成功。
NATIVE_ERROR_INVALID_ARGUMENTS 入参无效。
NATIVE_ERROR_NO_PERMISSION 无权限操作。
NATIVE_ERROR_NO_BUFFER 无空闲可用的buffer。
NATIVE_ERROR_NO_CONSUMER 消费端不存在。
NATIVE_ERROR_NOT_INIT 未初始化。
NATIVE_ERROR_CONSUMER_CONNECTED 消费端已经被连接。
NATIVE_ERROR_BUFFER_STATE_INVALID buffer状态不符合预期。
NATIVE_ERROR_BUFFER_IN_CACHE buffer已在缓存队列中。
NATIVE_ERROR_BUFFER_QUEUE_FULL 队列已满。
NATIVE_ERROR_BUFFER_NOT_IN_CACHE buffer不在缓存队列中。
NATIVE_ERROR_CONSUMER_DISCONNECTED 消费端已经被断开连接。
NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED 消费端未注册listener回调函数。
NATIVE_ERROR_UNSUPPORTED 当前设备或平台不支持。
NATIVE_ERROR_UNKNOWN 未知错误，请查看日志。
NATIVE_ERROR_HDI_ERROR HDI接口调用失败。
NATIVE_ERROR_BINDER_ERROR 跨进程通信失败。
NATIVE_ERROR_EGL_STATE_UNKNOWN egl环境状态异常。
NATIVE_ERROR_EGL_API_FAILED egl接口调用失败。

函数说明

OH_NativeVSync_GetPeriod()

收起
自动换行
深色代码主题
复制
  1. int OH_NativeVSync_GetPeriod (OH_NativeVSync * nativeVsync, long long * period )

描述:

获取vsync周期。

vsync周期是在每次使用OH_NativeVSync_RequestFrame接口请求vsync信号后收到OH_NativeVSync_FrameCallback回调的时候才会更新。

首次使用该接口获取vsync周期之前，需要先使用OH_NativeVSync_RequestFrame接口请求vsync信号，在收到OH_NativeVSync_FrameCallback回调之后，才可以通过该接口获取到vsync周期。

@syscap SystemCapability.Graphic.Graphic2D.NativeVsync

参数:

展开
名称 描述
nativeVsync 一个指向OH_NativeVSync实例的指针。
period 表示vsync周期，作为出参使用。

返回:

返回值为0表示执行成功，其他返回值可参考OHNativeErrorCode。

起始版本：

10

OH_NativeVSync_Create()

收起
自动换行
深色代码主题
复制
  1. OH_NativeVSync* OH_NativeVSync_Create (const char * name, unsigned int length )

描述:

创建一个OH_NativeVSync实例，每次调用都会产生一个新的实例。

@syscap SystemCapability.Graphic.Graphic2D.NativeVsync

参数:

展开
名称 描述
name 表示一个名字，与创建的OH_NativeVSync实例关联。
length name的长度（字符数）。

返回:

返回一个指向OH_NativeVSync实例的指针。

OH_NativeVSync_Destroy()

收起
自动换行
深色代码主题
复制
  1. void OH_NativeVSync_Destroy (OH_NativeVSync * nativeVsync)

描述:

销毁OH_NativeVSync实例。

销毁后的OH_NativeVSync指针不能再继续使用，否则会有野指针问题，尤其需要注意多线程并发时对于OH_NativeVSync指针的管理。

@syscap SystemCapability.Graphic.Graphic2D.NativeVsync

参数:

展开
名称 描述
nativeVsync 一个指向OH_NativeVSync实例的指针。

OH_NativeVSync_RequestFrame()

收起
自动换行
深色代码主题
复制
  1. int OH_NativeVSync_RequestFrame (OH_NativeVSync * nativeVsync, OH_NativeVSync_FrameCallback callback, void * data )

描述:

请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，则只会触发最后一个回调。

@syscap SystemCapability.Graphic.Graphic2D.NativeVsync

参数:

展开
名称 描述
nativeVsync 一个指向OH_NativeVSync实例的指针。
callback 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。
data 一个指向用户自定义数据结构的指针，类型是void*。

返回:

返回值为0表示执行成功，其他返回值可参考OHNativeErrorCode。

OH_NativeVSync_RequestFrameWithMultiCallback()

收起
自动换行
深色代码主题
复制
  1. int OH_NativeVSync_RequestFrameWithMultiCallback (OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data )

描述

请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。

系统能力： SystemCapability.Graphic.Graphic2D.NativeVsync

起始版本： 12

参数:

展开
名称 描述
nativeVsync 一个指向OH_NativeVSync实例的指针。
callback 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。
data 一个指向用户自定义数据结构的指针，类型是void*。

返回：

返回值为0表示执行成功，其他返回值可参考OHNativeErrorCode。

NativeDisplaySoloist
NativeWindow
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词