1# NativeVsync 2 3 4## 概述 5 6提供获取系统vsync回调的功能，可用于实现应用的绘制帧率与系统帧率同步。 7 8\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 9 10**起始版本:** 11 129 13 14 15## 汇总 16 17 18### 文件 19 20| 名称 | 描述 | 21| -------- | -------- | 22| [native_vsync.h](native__vsync_8h.md) | 定义获取和使用NativeVsync的相关函数。<br/>**引用文件：** <native_vsync/native_vsync.h> <br/>**库：** libnative_vsync.so | 23 24 25### 类型定义 26 27| 名称 | 描述 | 28| -------- | -------- | 29| typedef enum [OHNativeErrorCode](#ohnativeerrorcode) [OHNativeErrorCode](#ohnativeerrorcode) | 接口错误码说明（仅用于查询）。 | 30| typedef struct [OH_NativeVSync](#oh_nativevsync) [OH_NativeVSync](#oh_nativevsync) | 提供OH_NativeVSync结构体声明。 | 31| typedef void(\* [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback)) (long long timestamp, void \*data) | VSync回调函数类型。 | 32 33 34### 枚举 35 36| 名称 | 描述 | 37| -------- | -------- | 38| [OHNativeErrorCode](#ohnativeerrorcode-1) {<br/>NATIVE_ERROR_OK = 0, NATIVE_ERROR_MEM_OPERATION_ERROR = 30001000, NATIVE_ERROR_INVALID_ARGUMENTS = 40001000, NATIVE_ERROR_NO_PERMISSION = 40301000, NATIVE_ERROR_NO_BUFFER = 40601000,<br/>NATIVE_ERROR_NO_CONSUMER = 41202000, NATIVE_ERROR_NOT_INIT = 41203000, NATIVE_ERROR_CONSUMER_CONNECTED = 41206000, NATIVE_ERROR_BUFFER_STATE_INVALID = 41207000,<br/>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,<br/>NATIVE_ERROR_UNKNOWN = 50002000,NATIVE_ERROR_HDI_ERROR = 50007000,NATIVE_ERROR_BINDER_ERROR = 50401000,<br/>NATIVE_ERROR_EGL_STATE_UNKNOWN = 60001000, NATIVE_ERROR_EGL_API_FAILED = 60002000<br/>} | 接口错误码说明（仅用于查询）。 | 39 40 41### 函数 42 43| 名称 | 描述 | 44| -------- | -------- | 45| [OH_NativeVSync_Create](#oh_nativevsync_create) (const char \*name, unsigned int length) | 创建一个OH_NativeVSync实例，每次调用都会产生一个新的实例。 | 46| [OH_NativeVSync](#oh_nativevsync) \* [OH_NativeVSync_Create_ForAssociatedWindow](#oh_nativevsync_create_forassociatedwindow) (uint64_t windowID, const char \*name, unsigned int length) | 创建一个和窗口绑定的OH_NativeVSync实例，每次调用都会产生一个新的实例。 | 47| [OH_NativeVSync_Destroy](#oh_nativevsync_destroy) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync) | 销毁OH_NativeVSync实例。 | 48| int [OH_NativeVSync_RequestFrame](#oh_nativevsync_requestframe) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback) callback, void \*data) | 请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，则只会触发最后一个回调。 | 49| int [OH_NativeVSync_RequestFrameWithMultiCallback](#oh_nativevsync_requestframewithmulticallback) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback) callback, void \*data) | 请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。 | 50| [OH_NativeVSync_GetPeriod](#oh_nativevsync_getperiod) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, long long \*period) |获取vsync周期。| 51| int [OH_NativeVSync_DVSyncSwitch](#oh_nativevsync_dvsyncswitch) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, bool enable) | 启用DVSync以提高自绘制动画场景的流畅性。 DVSync是Decoupled VSync的缩写，它是一种与硬件VSync解耦的帧时序管理策略。<br/>DVSync通过提前发送带有未来时间戳的VSync信号驱动后续动画帧的提前绘制，这些帧会被帧缓冲队列缓存；DVSync通过缓存的帧减少未来可能发生的丢帧，进而提高动画场景的流畅性。<br/>因为DVSync需要占用空闲的自绘制帧缓冲用于缓存提前绘制的动画帧，用户需要确保至少有一个空闲的帧缓冲区，否则不建议启用此功能。<br/>启用DVSync后，用户需要正确响应提前发送的VSync信号，并在前一个VSync对应的动画帧完成后再请求下一个VSync，且自绘制帧需要携带与VSync一致的时间戳。<br/>在动画结束之后，用户需要关闭DVSync。<br/>在不支持DVSync的平台或者如果有另一个应用程序已经启用了DVSync，则当前的启用操作将不会生效，应用程序仍将收到正常的VSync信号。 | 52 53## 类型定义说明 54 55 56### OH_NativeVSync 57 58 59``` 60typedef struct OH_NativeVSync OH_NativeVSync 61``` 62 63**描述:** 64 65提供OH_NativeVSync结构体声明。 66 67 68### OH_NativeVSync_FrameCallback 69 70 71``` 72typedef void(* OH_NativeVSync_FrameCallback) (long long timestamp, void *data) 73``` 74 75**描述:** 76 77VSync回调函数类型。 78 79\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 80 81**参数:** 82 83| 名称 | 描述 | 84| -------- | -------- | 85| timestamp | VSync使用CLOCK_MONOTONIC获取的系统时间戳, 单位为纳秒。 | 86| data | 用户自定义数据。 | 87 88 89### OHNativeErrorCode 90 91``` 92typedef enum OHNativeErrorCode OHNativeErrorCode 93``` 94 95**描述** 96 97接口错误码说明（仅用于查询）。 98 99**起始版本：** 12 100 101 102## 枚举类型说明 103 104 105### OHNativeErrorCode 106 107``` 108enum OHNativeErrorCode 109``` 110 111**描述** 112 113接口错误码说明（仅用于查询）。 114 115**起始版本：** 12 116 117| 枚举值 | 描述 | 118| -------- | -------- | 119| NATIVE_ERROR_OK | 成功。 | 120| NATIVE_ERROR_MEM_OPERATION_ERROR<sup>15+</sup> | 内存操作错误。 | 121| NATIVE_ERROR_INVALID_ARGUMENTS | 入参无效。 | 122| NATIVE_ERROR_NO_PERMISSION | 无权限操作。 | 123| NATIVE_ERROR_NO_BUFFER | 无空闲可用的buffer。 | 124| NATIVE_ERROR_NO_CONSUMER | 消费端不存在。 | 125| NATIVE_ERROR_NOT_INIT | 未初始化。 | 126| NATIVE_ERROR_CONSUMER_CONNECTED | 消费端已经被连接。 | 127| NATIVE_ERROR_BUFFER_STATE_INVALID | buffer状态不符合预期。 | 128| NATIVE_ERROR_BUFFER_IN_CACHE | buffer已在缓存队列中。 | 129| NATIVE_ERROR_BUFFER_QUEUE_FULL | 队列已满。 | 130| NATIVE_ERROR_BUFFER_NOT_IN_CACHE | buffer不在缓存队列中。 | 131| NATIVE_ERROR_CONSUMER_DISCONNECTED | 消费端已经被断开连接。 | 132| NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED | 消费端未注册listener回调函数。 | 133| NATIVE_ERROR_UNSUPPORTED | 当前设备或平台不支持。 | 134| NATIVE_ERROR_UNKNOWN | 未知错误，请查看日志。 | 135| NATIVE_ERROR_HDI_ERROR | HDI接口调用失败。 | 136| NATIVE_ERROR_BINDER_ERROR | 跨进程通信失败。 | 137| NATIVE_ERROR_EGL_STATE_UNKNOWN | egl环境状态异常。 | 138| NATIVE_ERROR_EGL_API_FAILED | egl接口调用失败。 | 139 140## 函数说明 141 142 143### OH_NativeVSync_DVSyncSwitch() 144 145``` 146int OH_NativeVSync_DVSyncSwitch (OH_NativeVSync* nativeVsync, bool enable ) 147``` 148 149**描述** 150 151启用DVSync以提高自绘制动画场景的流畅性。 DVSync是Decoupled VSync的缩写，它是一种与硬件VSync解耦的帧时序管理策略。 152 153DVSync通过提前发送带有未来时间戳的VSync信号驱动后续动画帧的提前绘制，这些帧会被帧缓冲队列缓存；DVSync通过缓存的帧减少未来可能发生的丢帧，进而提高动画场景的流畅性。 154 155因为DVSync需要占用空闲的自绘制帧缓冲用于缓存提前绘制的动画帧，用户需要确保至少有一个空闲的帧缓冲区，否则不建议启用此功能。 156 157启用DVSync后，用户需要正确响应提前发送的VSync信号，并在前一个VSync对应的动画帧完成后再请求下一个VSync，且自绘制帧需要携带与VSync一致的时间戳。 158 159在动画结束之后，用户需要关闭DVSync。 160 161在不支持DVSync的平台或者如果有另一个应用程序已经启用了DVSync，则当前的启用操作将不会生效，应用程序仍将收到正常的VSync信号。 162 163**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 164 165**起始版本：** 14 166 167**参数:** 168 169| 名称 | 描述 | 170| -------- | -------- | 171| nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 172| enable | 表示打开或者关闭DVSync，true表示打开，false表示关闭。 | 173 174**返回：** 175 176返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 177 178 179 180### OH_NativeVSync_GetPeriod() 181 182 183``` 184int OH_NativeVSync_GetPeriod (OH_NativeVSync * nativeVsync, long long * period ) 185``` 186 187**描述:** 188 189获取vsync周期。 190 191vsync周期是在每次使用OH_NativeVSync_RequestFrame接口请求vsync信号后收到OH_NativeVSync_FrameCallback回调的时候才会更新。 192 193首次使用该接口获取vsync周期之前，需要先使用OH_NativeVSync_RequestFrame接口请求vsync信号，在收到OH_NativeVSync_FrameCallback回调之后，才可以通过该接口获取到vsync周期。 194 195\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 196 197**参数:** 198 199| 名称 | 描述 | 200| -------- | -------- | 201| nativeVsync | 一个指向OH_NativeVSync实例的指针。| 202| period | 表示vsync周期，作为出参使用。 | 203 204**返回:** 205 206返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 207 208**起始版本：** 209 21010 211 212 213### OH_NativeVSync_Create() 214 215 216``` 217OH_NativeVSync* OH_NativeVSync_Create (const char * name, unsigned int length ) 218``` 219 220**描述:** 221 222创建一个OH_NativeVSync实例，每次调用都会产生一个新的实例。 223 224\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 225 226**参数:** 227 228| 名称 | 描述 | 229| -------- | -------- | 230| name | 表示一个名字，与创建的OH_NativeVSync实例关联。 | 231| length | name的长度（字符数）。 | 232 233**返回:** 234 235返回一个指向OH_NativeVSync实例的指针。 236 237 238### OH_NativeVSync_Create_ForAssociatedWindow() 239 240``` 241OH_NativeVSync* OH_NativeVSync_Create_ForAssociatedWindow (uint64_t windowID, const char* name, unsigned int length ) 242``` 243 244**描述** 245 246创建一个和窗口绑定的OH_NativeVSync实例，每次调用都会产生一个新的实例。 247 248使用本接口创建出来的OH_NativeVSync实例的实际vsync周期与系统vsync周期不完全一致，系统会根据窗口的状态对实际vsync周期进行调整。 249 250**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 251 252**起始版本：** 14 253 254**参数:** 255 256| 名称 | 描述 | 257| -------- | -------- | 258| windowID | 表示窗口ID，窗口子进程索引标识符，可以通过[OH_NativeWindow_GetSurfaceId](_native_window.md#oh_nativewindow_getsurfaceid)接口获取。 | 259| name | 表示一个名称，与创建的OH_NativeVSync实例关联。 | 260| length | name的长度（字符数）。 | 261 262**返回：** 263 264返回一个指向OH_NativeVSync实例的指针。 265 266 267 268### OH_NativeVSync_Destroy() 269 270 271``` 272void OH_NativeVSync_Destroy (OH_NativeVSync * nativeVsync) 273``` 274 275**描述:** 276 277销毁OH_NativeVSync实例。 278 279销毁后的OH_NativeVSync指针不能再继续使用，否则会有野指针问题，尤其需要注意多线程并发时对于OH_NativeVSync指针的管理。 280 281\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 282 283**参数:** 284 285| 名称 | 描述 | 286| -------- | -------- | 287| nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 288 289 290### OH_NativeVSync_RequestFrame() 291 292 293``` 294int OH_NativeVSync_RequestFrame (OH_NativeVSync * nativeVsync, OH_NativeVSync_FrameCallback callback, void * data ) 295``` 296 297**描述:** 298 299请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，则只会触发最后一个回调。 300 301\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 302 303**参数:** 304 305| 名称 | 描述 | 306| -------- | -------- | 307| nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 308| callback | 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。 | 309| data | 一个指向用户自定义数据结构的指针，类型是void\*。 | 310 311**返回:** 312 313返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。 314 315 316### OH_NativeVSync_RequestFrameWithMultiCallback() 317 318``` 319int OH_NativeVSync_RequestFrameWithMultiCallback (OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data ) 320``` 321 322**描述** 323 324请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。 325 326**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 327 328**起始版本：** 12 329 330**参数:** 331 332| 名称 | 描述 | 333| -------- | -------- | 334| nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 335| callback | 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。 | 336| data | 一个指向用户自定义数据结构的指针，类型是void\*。 | 337 338**返回：** 339 340返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。