1# native_vsync.h 2 3## 概述 4 5定义获取和使用NativeVsync的相关函数。 6<!--RP1--> 7**相关示例：** [NDKNativeImage](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Native/NdkNativeImage)<!--RP1End--> 8 9**引用文件：** <native_vsync/native_vsync.h> 10 11**库：** libnative_vsync.so 12 13**起始版本：** 9 14 15**相关模块：** [NativeVsync](capi-nativevsync.md) 16 17## 汇总 18 19### 结构体 20 21| 名称 | typedef关键字 | 描述 | 22| -- | -- | -- | 23| [OH_NativeVSync_ExpectedRateRange](capi-nativevsync-oh-nativevsync-expectedraterange.md) | OH_NativeVSync_ExpectedRateRange | 期望帧率范围结构体。 | 24| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md) | OH_NativeVSync | 提供OH_NativeVSync结构体声明。 | 25 26### 函数 27 28| 名称 | typedef关键字 | 描述 | 29| -- | -- | -- | 30| [typedef void (\*OH_NativeVSync_FrameCallback)(long long timestamp, void *data)](#oh_nativevsync_framecallback) | OH_NativeVSync_FrameCallback | VSync回调函数类型。 | 31| [OH_NativeVSync* OH_NativeVSync_Create(const char* name, unsigned int length)](#oh_nativevsync_create) | - | 创建一个OH_NativeVSync实例，每次调用都会产生一个新的实例。<br>本接口需要与[OH_NativeVSync_Destroy](capi-native-vsync-h.md#oh_nativevsync_destroy)接口配合使用，否则会存在内存泄露。 | 32| [OH_NativeVSync* OH_NativeVSync_Create_ForAssociatedWindow(uint64_t windowID, const char* name, unsigned int length)](#oh_nativevsync_create_forassociatedwindow) | - | 创建一个和窗口绑定的OH_NativeVSync实例，每次调用都会产生一个新的实例。<br>使用本接口创建出来的OH_NativeVSync实例的实际vsync周期与系统vsync周期不完全一致，系统会根据窗口的状态对实际vsync周期进行调整。 | 33| [void OH_NativeVSync_Destroy(OH_NativeVSync* nativeVsync)](#oh_nativevsync_destroy) | - | 销毁OH_NativeVSync实例。<br>销毁后的OH_NativeVSync指针不能再继续使用，否则会有野指针问题，尤其需要注意多线程并发时对于OH_NativeVSync指针的管理。 | 34| [int OH_NativeVSync_RequestFrame(OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data)](#oh_nativevsync_requestframe) | - | 请求下一次vsync信号，当信号到来时，调用回调函数callback。<br>如果在同一帧内中多次调用此接口，则只会触发最后一个回调。<br>如果此接口与[OH_NativeVSync_RequestFrameWithMultiCallback](capi-native-vsync-h.md#oh_nativevsync_requestframewithmulticallback)接口在同一帧内被调用，则此接口的功能不会生效。 | 35| [int OH_NativeVSync_RequestFrameWithMultiCallback(OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data)](#oh_nativevsync_requestframewithmulticallback) | - | 请求下一次vsync信号，当信号到来时，调用回调函数callback。<br>如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。 | 36| [int OH_NativeVSync_GetPeriod(OH_NativeVSync* nativeVsync, long long* period)](#oh_nativevsync_getperiod) | - | 获取vsync周期。<br>vsync周期是在每次使用OH_NativeVSync_RequestFrame接口请求vsync信号后收到OH_NativeVSync_FrameCallback回调的时候才会更新。<br>首次使用该接口获取vsync周期之前，需要先使用OH_NativeVSync_RequestFrame接口请求vsync信号，在收到OH_NativeVSync_FrameCallback回调之后，才可以通过该接口获取到vsync周期。 | 37| [int OH_NativeVSync_DVSyncSwitch(OH_NativeVSync* nativeVsync, bool enable)](#oh_nativevsync_dvsyncswitch) | - | 启用DVSync以提高自绘制动画场景的流畅性。<br>DVSync是Decoupled VSync的缩写，它是一种与硬件VSync解耦的帧时序管理策略。<br>DVSync通过提前发送带有未来时间戳的VSync信号驱动后续动画帧的提前绘制，这些帧会被帧缓冲队列缓存；DVSync通过缓存的帧减少未来可能发生的丢帧，进而提高动画场景的流畅性。<br>因为DVSync需要占用空闲的自绘制帧缓冲用于缓存提前绘制的动画帧，用户需要确保至少有一个空闲的帧缓冲区，否则不建议启用此功能。<br>启用DVSync后，用户需要正确响应提前发送的VSync信号，并在前一个VSync对应的动画帧完成后再请求下一个VSync，且自绘制帧需要携带与VSync一致的时间戳。<br>在动画结束之后，用户需要关闭DVSync。<br>在不支持DVSync的平台或者如果有另一个应用程序已经启用了DVSync，则当前的启用操作将不会生效，应用程序仍将收到正常的VSync信号。 | 38| [int OH_NativeVSync_SetExpectedFrameRateRange(OH_NativeVSync* nativeVsync, OH_NativeVSync_ExpectedRateRange* range)](#oh_nativevsync_setexpectedframeraterange) | - | 设置VSync期望帧率以及期望帧率的范围。 | 39 40## 函数说明 41 42### OH_NativeVSync_FrameCallback() 43 44``` 45typedef void (*OH_NativeVSync_FrameCallback)(long long timestamp, void *data) 46``` 47 48**描述** 49 50VSync回调函数类型。 51 52**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 53 54**起始版本：** 9 55 56 57**参数：** 58 59| 参数项 | 描述 | 60| -- | -- | 61| long long timestamp | VSync使用CLOCK_MONOTONIC获取的系统时间戳, 单位为纳秒。 | 62| void *data | 用户自定义数据。 | 63 64### OH_NativeVSync_Create() 65 66``` 67OH_NativeVSync* OH_NativeVSync_Create(const char* name, unsigned int length) 68``` 69 70**描述** 71 72创建一个OH_NativeVSync实例，每次调用都会产生一个新的实例。<br>本接口需要与[OH_NativeVSync_Destroy](capi-native-vsync-h.md#oh_nativevsync_destroy)接口配合使用，否则会存在内存泄露。 73 74**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 75 76**起始版本：** 9 77 78 79**参数：** 80 81| 参数项 | 描述 | 82| -- | -- | 83| const char* name | 表示一个名字，与创建的OH_NativeVSync实例关联。 | 84| unsigned int length | ame的长度（字符数）。 | 85 86**返回：** 87 88| 类型 | 说明 | 89| -- | -- | 90| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)* | 返回一个指向OH_NativeVSync实例的指针。 | 91 92### OH_NativeVSync_Create_ForAssociatedWindow() 93 94``` 95OH_NativeVSync* OH_NativeVSync_Create_ForAssociatedWindow(uint64_t windowID, const char* name, unsigned int length) 96``` 97 98**描述** 99 100创建一个和窗口绑定的OH_NativeVSync实例，每次调用都会产生一个新的实例。<br>使用本接口创建出来的OH_NativeVSync实例的实际vsync周期与系统vsync周期不完全一致，系统会根据窗口的状态对实际vsync周期进行调整。 101 102**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 103 104**起始版本：** 14 105 106 107**参数：** 108 109| 参数项 | 描述 | 110| -- | -- | 111| uint64_t windowID | 表示窗口ID，窗口子进程索引标识符，可以通过[OH_NativeWindow_GetSurfaceId](capi-external-window-h.md#oh_nativewindow_getsurfaceid)接口获取。 | 112| const char* name | 表示一个名称，与创建的OH_NativeVSync实例关联。 | 113| unsigned int length | ame的长度（字符数）。 | 114 115**返回：** 116 117| 类型 | 说明 | 118| -- | -- | 119| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)* | 返回一个指向OH_NativeVSync实例的指针。 | 120 121### OH_NativeVSync_Destroy() 122 123``` 124void OH_NativeVSync_Destroy(OH_NativeVSync* nativeVsync) 125``` 126 127**描述** 128 129销毁OH_NativeVSync实例。<br>销毁后的OH_NativeVSync指针不能再继续使用，否则会有野指针问题，尤其需要注意多线程并发时对于OH_NativeVSync指针的管理。 130 131**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 132 133**起始版本：** 9 134 135 136**参数：** 137 138| 参数项 | 描述 | 139| -- | -- | 140| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)* nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 141 142### OH_NativeVSync_RequestFrame() 143 144``` 145int OH_NativeVSync_RequestFrame(OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data) 146``` 147 148**描述** 149 150请求下一次vsync信号，当信号到来时，调用回调函数callback。<br>如果在同一帧内中多次调用此接口，则只会触发最后一个回调。<br>如果此接口与[OH_NativeVSync_RequestFrameWithMultiCallback](capi-native-vsync-h.md#oh_nativevsync_requestframewithmulticallback)接口在同一帧内被调用，则此接口的功能不会生效。 151 152**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 153 154**起始版本：** 9 155 156 157**参数：** 158 159| 参数项 | 描述 | 160| -- | -- | 161| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)* nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 162| [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback) callback | 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。 | 163| void* data | 一个指向用户自定义数据结构的指针，类型是void。 | 164 165**返回：** 166 167| 类型 | 说明 | 168| -- | -- | 169| int | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 170 171### OH_NativeVSync_RequestFrameWithMultiCallback() 172 173``` 174int OH_NativeVSync_RequestFrameWithMultiCallback(OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data) 175``` 176 177**描述** 178 179请求下一次vsync信号，当信号到来时，调用回调函数callback。<br>如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。 180 181**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 182 183**起始版本：** 12 184 185 186**参数：** 187 188| 参数项 | 描述 | 189| -- | -- | 190| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)* nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 191| [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback) callback | 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。 | 192| void* data | 一个指向用户自定义数据结构的指针，类型是void。 | 193 194**返回：** 195 196| 类型 | 说明 | 197| -- | -- | 198| int | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 199 200### OH_NativeVSync_GetPeriod() 201 202``` 203int OH_NativeVSync_GetPeriod(OH_NativeVSync* nativeVsync, long long* period) 204``` 205 206**描述** 207 208获取vsync周期。<br>vsync周期是在每次使用OH_NativeVSync_RequestFrame接口请求vsync信号后收到OH_NativeVSync_FrameCallback回调的时候才会更新。<br>首次使用该接口获取vsync周期之前，需要先使用OH_NativeVSync_RequestFrame接口请求vsync信号，在收到OH_NativeVSync_FrameCallback回调之后，才可以通过该接口获取到vsync周期。 209 210**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 211 212**起始版本：** 10 213 214 215**参数：** 216 217| 参数项 | 描述 | 218| -- | -- | 219| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)* nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 220| long long* period | 表示vsync周期，作为出参使用。 | 221 222**返回：** 223 224| 类型 | 说明 | 225| -- | -- | 226| int | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 227 228### OH_NativeVSync_DVSyncSwitch() 229 230``` 231int OH_NativeVSync_DVSyncSwitch(OH_NativeVSync* nativeVsync, bool enable) 232``` 233 234**描述** 235 236启用DVSync以提高自绘制动画场景的流畅性。<br>DVSync是Decoupled VSync的缩写，它是一种与硬件VSync解耦的帧时序管理策略。<br>DVSync通过提前发送带有未来时间戳的VSync信号驱动后续动画帧的提前绘制，这些帧会被帧缓冲队列缓存；DVSync通过缓存的帧减少未来可能发生的丢帧，进而提高动画场景的流畅性。<br>因为DVSync需要占用空闲的自绘制帧缓冲用于缓存提前绘制的动画帧，用户需要确保至少有一个空闲的帧缓冲区，否则不建议启用此功能。<br>启用DVSync后，用户需要正确响应提前发送的VSync信号，并在前一个VSync对应的动画帧完成后再请求下一个VSync，且自绘制帧需要携带与VSync一致的时间戳。<br>在动画结束之后，用户需要关闭DVSync。<br>在不支持DVSync的平台或者如果有另一个应用程序已经启用了DVSync，则当前的启用操作将不会生效，应用程序仍将收到正常的VSync信号。 237 238**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 239 240**起始版本：** 14 241 242 243**参数：** 244 245| 参数项 | 描述 | 246| -- | -- | 247| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)* nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 248| bool enable | 表示打开或者关闭DVSync，true表示打开，false表示关闭。 | 249 250**返回：** 251 252| 类型 | 说明 | 253| -- | -- | 254| int | 返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 255 256### OH_NativeVSync_SetExpectedFrameRateRange() 257 258``` 259int OH_NativeVSync_SetExpectedFrameRateRange(OH_NativeVSync* nativeVsync, OH_NativeVSync_ExpectedRateRange* range) 260``` 261 262**描述** 263 264设置VSync期望帧率及其范围。实际帧率可能因系统功耗、性能和硬件规格等限制而与设置的期望值不一致。 265 266**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync 267 268**起始版本：** 20 269 270 271**参数：** 272 273| 参数项 | 描述 | 274| -- | -- | 275| [OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)* nativeVsync | 指向[OH_NativeVSync](capi-nativevsync-oh-nativevsync.md)实例的指针。 | 276| [OH_NativeVSync_ExpectedRateRange](capi-nativevsync-oh-nativevsync-expectedraterange.md)* range | 指向[OH_NativeVSync_ExpectedRateRange](capi-nativevsync-oh-nativevsync-expectedraterange.md)实例的指针。<br>有效的期望帧率范围为：0 <= 最小值 <= 期望帧率 <= 最大值 <= 144。<br>期望帧率为0时，表示取消设置期望帧率。<br>此指针需开发者自行管理生命周期。 | 277 278**返回：** 279 280| 类型 | 说明 | 281| -- | -- | 282| int | 返回值为0表示成功，其他返回值可参考[OHNativeErrorCode](capi-graphic-error-code-h.md#ohnativeerrorcode)。 | 283 284