1# NativeVsync 2 3 4## Overview 5 6The **NativeVsync** module provides the capabilities of native virtual synchronization (VSync). 7 8\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 9 10**Since** 11 129 13 14 15## Summary 16 17 18### Files 19 20| Name| Description| 21| -------- | -------- | 22| [native_vsync.h](native__vsync_8h.md) | Declares the functions for obtaining and using native VSync.<br>**File to include**: <native_vsync/native_vsync.h><br>**Library**: libnative_vsync.so| 23 24 25### Types 26 27| Name| Description| 28| -------- | -------- | 29| typedef enum [OHNativeErrorCode](#ohnativeerrorcode) [OHNativeErrorCode](#ohnativeerrorcode) | Defines an enum for the error codes. | 30| typedef struct [OH_NativeVSync](#oh_nativevsync) [OH_NativeVSync](#oh_nativevsync) | Provides the declaration of an **OH_NativeVSync** struct. | 31| typedef void(\* [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback)) (long long timestamp, void \*data) | Defines the pointer to a VSync callback function. | 32 33 34### Enums 35 36| Name| Description| 37| -------- | -------- | 38| [OHNativeErrorCode](#ohnativeerrorcode-1) {<br>NATIVE_ERROR_OK = 0, 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>} | Enumerates the error codes. | 39 40 41### Functions 42 43| Name| Description| 44| -------- | -------- | 45| [OH_NativeVSync_Create](#oh_nativevsync_create) (const char \*name, unsigned int length) | Creates an **OH_NativeVSync** instance. A new **OH_NativeVSync** instance is created each time this function is called.| 46| [OH_NativeVSync](#oh_nativevsync) \* [OH_NativeVSync_Create_ForAssociatedWindow](#oh_nativevsync_create_forassociatedwindow) (uint64_t windowID, const char \*name, unsigned int length) | Creates an **OH_NativeVSync** instance to bind with a window. A new **OH_NativeVSync** instance is created each time this API is called.| 47| [OH_NativeVSync_Destroy](#oh_nativevsync_destroy) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync) | Destroys an **OH_NativeVSync** instance.| 48| int [OH_NativeVSync_RequestFrame](#oh_nativevsync_requestframe) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback) callback, void \*data) | Requests the next VSync signal. When the signal arrives, a callback function is invoked. If this function is called for multiple times in the same frame, only the last callback function is invoked.| 49| int [OH_NativeVSync_RequestFrameWithMultiCallback](#oh_nativevsync_requestframewithmulticallback) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback) callback, void \*data) | Requests the next VSync signal. When the signal arrives, a callback function is invoked. If this function is called for multiple times in the same frame, every callback function is invoked.| 50| [OH_NativeVSync_GetPeriod](#oh_nativevsync_getperiod) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, long long \*period) |Obtains the VSync period.| 51| int [OH_NativeVSync_DVSyncSwitch](#oh_nativevsync_dvsyncswitch) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, bool enable) | Enables DVSync to improve the smoothness of self-drawing animations. DVSync, short for Decoupled VSync, is a frame timing management policy that is decoupled from the hardware's VSync.<br>DVSync drives the early rendering of upcoming animation frames by sending VSync signals with future timestamps. These frames are stored in a frame buffer queue. This helps DVSync reduce potential frame drops and therefore enhances the smoothness of animations.<br>DVSync requires free self-drawing frame buffers to store these pre-rendered animation frames. Therefore, you must ensure that at least one free frame buffer is available. Otherwise, do not enable DVSync.<br>After DVSync is enabled, you must correctly respond to the early VSync signals and request the subsequent VSync after the animation frame associated with the previous VSync is complete. In addition, the self-drawing frames must carry timestamps that align with VSync.<br>After the animation ends, disable DVSync.<br>On a platform that does not support DVSync or if another application has enabled DVSync, the attempt to enable it will not take effect, and the application still receives normal VSync signals.| 52 53## Type Description 54 55 56### OH_NativeVSync 57 58 59``` 60typedef struct OH_NativeVSync OH_NativeVSync 61``` 62 63**Description** 64 65Provides the declaration of an **OH_NativeVSync** struct. 66 67 68### OH_NativeVSync_FrameCallback 69 70 71``` 72typedef void(* OH_NativeVSync_FrameCallback) (long long timestamp, void *data) 73``` 74 75**Description** 76 77Defines the pointer to a VSync callback function. 78 79\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 80 81**Parameters** 82 83| Name| Description| 84| -------- | -------- | 85| timestamp | System timestamp obtained by VSync using **CLOCK_MONOTONIC**, in nanoseconds.| 86| data | User-defined data.| 87 88 89### OHNativeErrorCode 90 91``` 92typedef enum OHNativeErrorCode OHNativeErrorCode 93``` 94 95**Description** 96 97Defines an enum for the error codes. 98 99**Since**: 12 100 101 102## Enum Description 103 104 105### OHNativeErrorCode 106 107``` 108enum OHNativeErrorCode 109``` 110 111**Description** 112 113Enumerates the error codes. 114 115**Since**: 12 116 117| Value| Description| 118| -------- | -------- | 119| NATIVE_ERROR_OK | The operation is successful. | 120| NATIVE_ERROR_INVALID_ARGUMENTS | An input parameter is invalid. | 121| NATIVE_ERROR_NO_PERMISSION | You do not have the permission to perform the operation. | 122| NATIVE_ERROR_NO_BUFFER | No buffer is available. | 123| NATIVE_ERROR_NO_CONSUMER | The consumer does not exist. | 124| NATIVE_ERROR_NOT_INIT | Not initialized. | 125| NATIVE_ERROR_CONSUMER_CONNECTED | The consumer is connected. | 126| NATIVE_ERROR_BUFFER_STATE_INVALID | The buffer status does not meet the expectation. | 127| NATIVE_ERROR_BUFFER_IN_CACHE | The buffer is already in the buffer queue. | 128| NATIVE_ERROR_BUFFER_QUEUE_FULL | The queue is full. | 129| NATIVE_ERROR_BUFFER_NOT_IN_CACHE | The buffer is not in the buffer queue. | 130| NATIVE_ERROR_CONSUMER_DISCONNECTED | The consumer is disconnected.| 131| NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED | No listener is registered on the consumer side.| 132| NATIVE_ERROR_UNSUPPORTED | The device or platform does not support the operation. | 133| NATIVE_ERROR_UNKNOWN | Unknown error. Check the log. | 134| NATIVE_ERROR_HDI_ERROR | Failed to call the HDI. | 135| NATIVE_ERROR_BINDER_ERROR | Cross-process communication failed. | 136| NATIVE_ERROR_EGL_STATE_UNKNOWN | The EGL environment is abnormal. | 137| NATIVE_ERROR_EGL_API_FAILED | Failed to call the EGL APIs. | 138 139## Function Description 140 141 142### OH_NativeVSync_DVSyncSwitch() 143 144``` 145int OH_NativeVSync_DVSyncSwitch (OH_NativeVSync* nativeVsync, bool enable ) 146``` 147 148**Description** 149 150Enables DVSync to improve the smoothness of self-drawing animations. DVSync, short for Decoupled VSync, is a frame timing management policy that is decoupled from the hardware's VSync. 151 152DVSync drives the early rendering of upcoming animation frames by sending VSync signals with future timestamps. These frames are stored in a frame buffer queue. This helps DVSync reduce potential frame drops and therefore enhances the smoothness of animations. 153 154DVSync requires free self-drawing frame buffers to store these pre-rendered animation frames. Therefore, you must ensure that at least one free frame buffer is available. Otherwise, do not enable DVSync. 155 156After DVSync is enabled, you must correctly respond to the early VSync signals and request the subsequent VSync after the animation frame associated with the previous VSync is complete. In addition, the self-drawing frames must carry timestamps that align with VSync. 157 158After the animation ends, disable DVSync. 159 160On a platform that does not support DVSync or if another application has enabled DVSync, the attempt to enable it will not take effect, and the application still receives normal VSync signals. 161 162**System capability**: SystemCapability.Graphic.Graphic2D.NativeVsync 163 164**Since**: 14 165 166**Parameters** 167 168| Name| Description| 169| -------- | -------- | 170| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 171| enable | Whether to enable DVSync. The value **true** means to enable DVSync, and **false** means the opposite.| 172 173**Returns** 174 175Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 176 177 178 179### OH_NativeVSync_GetPeriod() 180 181 182``` 183int OH_NativeVSync_GetPeriod (OH_NativeVSync * nativeVsync, long long * period ) 184``` 185 186**Description** 187 188Obtains the VSync period. 189 190The VSync period is refreshed only when the **OH_NativeVSync_FrameCallback** callback is received following a request for a VSync signal via **OH_NativeVSync_RequestFrame**. 191 192To obtain the VSync period for the first time using this function, you need to call **OH_NativeVSync_RequestFrame** to request a VSync signal. Once the **OH_NativeVSync_FrameCallback** callback is received, the vsync period can be obtained. 193 194\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 195 196**Parameters** 197 198| Name| Description| 199| -------- | -------- | 200| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 201| period | Pointer to the VSync period.| 202 203**Returns** 204 205Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 206 207**Since** 208 20910 210 211 212### OH_NativeVSync_Create() 213 214 215``` 216OH_NativeVSync* OH_NativeVSync_Create (const char * name, unsigned int length ) 217``` 218 219**Description** 220 221Creates an **OH_NativeVSync** instance. A new **OH_NativeVSync** instance is created each time this function is called. 222 223\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 224 225**Parameters** 226 227| Name| Description| 228| -------- | -------- | 229| name | Pointer to the name that associates with the **OH_NativeVSync** instance.| 230| length | Length of the name.| 231 232**Returns** 233 234Returns the pointer to an **OH_NativeVSync** instance. 235 236 237### OH_NativeVSync_Create_ForAssociatedWindow() 238 239``` 240OH_NativeVSync* OH_NativeVSync_Create_ForAssociatedWindow (uint64_t windowID, const char* name, unsigned int length ) 241``` 242 243**Description** 244 245Creates an **OH_NativeVSync** instance to bind with a window. A new **OH_NativeVSync** instance is created each time this API is called. 246 247**System capability**: SystemCapability.Graphic.Graphic2D.NativeVsync 248 249**Since**: 14 250 251**Parameters** 252 253| Name| Description| 254| -------- | -------- | 255| windowID | Window ID, which is the index identifier of the window child process and can be obtained through [OH_NativeWindow_GetSurfaceId](_native_window.md#oh_nativewindow_getsurfaceid).| 256| name | Pointer to the name that associates with the **OH_NativeVSync** instance.| 257| length | Length of the name.| 258 259**Returns** 260 261Returns the pointer to an **OH_NativeVSync** instance. 262 263 264 265### OH_NativeVSync_Destroy() 266 267 268``` 269void OH_NativeVSync_Destroy (OH_NativeVSync * nativeVsync) 270``` 271 272**Description** 273 274Destroys an **OH_NativeVSync** instance. 275 276Once the **OH_NativeVSync** pointer is destroyed, it must not be used to prevent dangling pointer problems. Pay special attention to the management of the **OH_NativeVSync** pointer in concurrent multithreaded scenarios. 277 278\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 279 280**Parameters** 281 282| Name| Description| 283| -------- | -------- | 284| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 285 286 287### OH_NativeVSync_RequestFrame() 288 289 290``` 291int OH_NativeVSync_RequestFrame (OH_NativeVSync * nativeVsync, OH_NativeVSync_FrameCallback callback, void * data ) 292``` 293 294**Description** 295 296Requests the next VSync signal. When the signal arrives, a callback function is invoked. If this function is called for multiple times in the same frame, only the last callback function is invoked. 297 298\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 299 300**Parameters** 301 302| Name| Description| 303| -------- | -------- | 304| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 305| callback | Function pointer of the **OH_NativeVSync_FrameCallback** type. This function pointer will be called when the next VSync signal arrives.| 306| data | Pointer to the user-defined data struct. The type is void\*.| 307 308**Returns** 309 310Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 311 312 313### OH_NativeVSync_RequestFrameWithMultiCallback() 314 315``` 316int OH_NativeVSync_RequestFrameWithMultiCallback (OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data ) 317``` 318 319**Description** 320 321Requests the next VSync signal. When the signal arrives, a callback function is invoked. If this function is called for multiple times in the same frame, every callback function is invoked. 322 323**System capability**: SystemCapability.Graphic.Graphic2D.NativeVsync 324 325**Since**: 12 326 327**Parameters** 328 329| Name| Description| 330| -------- | -------- | 331| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 332| callback | Function pointer of the **OH_NativeVSync_FrameCallback** type. This function pointer will be called when the next VSync signal arrives.| 333| data | Pointer to the user-defined data struct. The type is void\*.| 334 335**Returns** 336 337Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 338