1# NativeVsync 2 3 4## Overview 5 6The NativeVsync module provides the capabilities for obtaining the system virtual synchronization (VSync) callback, allowing you to synchronize your application's drawing frame rate with the system's frame rate. 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_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>} | 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_MEM_OPERATION_ERROR<sup>15+</sup> | An error occurs during memory manipulation.| 121| NATIVE_ERROR_INVALID_ARGUMENTS | An input parameter is invalid. | 122| NATIVE_ERROR_NO_PERMISSION | You do not have the permission to perform the operation. | 123| NATIVE_ERROR_NO_BUFFER | No buffer is available. | 124| NATIVE_ERROR_NO_CONSUMER | The consumer does not exist. | 125| NATIVE_ERROR_NOT_INIT | Not initialized. | 126| NATIVE_ERROR_CONSUMER_CONNECTED | The consumer is connected. | 127| NATIVE_ERROR_BUFFER_STATE_INVALID | The buffer status does not meet the expectation. | 128| NATIVE_ERROR_BUFFER_IN_CACHE | The buffer is already in the buffer queue. | 129| NATIVE_ERROR_BUFFER_QUEUE_FULL | The queue is full. | 130| NATIVE_ERROR_BUFFER_NOT_IN_CACHE | The buffer is not in the buffer queue. | 131| NATIVE_ERROR_CONSUMER_DISCONNECTED | The consumer is disconnected.| 132| NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED | No listener is registered on the consumer side.| 133| NATIVE_ERROR_UNSUPPORTED | The device or platform does not support the operation. | 134| NATIVE_ERROR_UNKNOWN | Unknown error. Check the log. | 135| NATIVE_ERROR_HDI_ERROR | Failed to call the HDI. | 136| NATIVE_ERROR_BINDER_ERROR | Cross-process communication failed. | 137| NATIVE_ERROR_EGL_STATE_UNKNOWN | The EGL environment is abnormal. | 138| NATIVE_ERROR_EGL_API_FAILED | Failed to call the EGL APIs. | 139 140## Function Description 141 142 143### OH_NativeVSync_DVSyncSwitch() 144 145``` 146int OH_NativeVSync_DVSyncSwitch (OH_NativeVSync* nativeVsync, bool enable ) 147``` 148 149**Description** 150 151Enables 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. 152 153DVSync 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. 154 155DVSync 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. 156 157After 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. 158 159After the animation ends, disable DVSync. 160 161On 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. 162 163**System capability**: SystemCapability.Graphic.Graphic2D.NativeVsync 164 165**Since**: 14 166 167**Parameters** 168 169| Name| Description| 170| -------- | -------- | 171| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 172| enable | Whether to enable DVSync. The value **true** means to enable DVSync, and **false** means the opposite.| 173 174**Returns** 175 176Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 177 178 179 180### OH_NativeVSync_GetPeriod() 181 182 183``` 184int OH_NativeVSync_GetPeriod (OH_NativeVSync * nativeVsync, long long * period ) 185``` 186 187**Description** 188 189Obtains the VSync period. 190 191The VSync period is refreshed only when the **OH_NativeVSync_FrameCallback** callback is received following a request for a VSync signal via **OH_NativeVSync_RequestFrame**. 192 193To 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. 194 195\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 196 197**Parameters** 198 199| Name| Description| 200| -------- | -------- | 201| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 202| period | Pointer to the VSync period.| 203 204**Returns** 205 206Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 207 208**Since** 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**Description** 221 222Creates an **OH_NativeVSync** instance. A new **OH_NativeVSync** instance is created each time this function is called. 223 224\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 225 226**Parameters** 227 228| Name| Description| 229| -------- | -------- | 230| name | Pointer to the name that associates with the **OH_NativeVSync** instance.| 231| length | Length of the name (number of characters).| 232 233**Returns** 234 235Returns the pointer to an **OH_NativeVSync** instance. 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**Description** 245 246Creates an **OH_NativeVSync** instance to bind with a window. A new **OH_NativeVSync** instance is created each time this API is called. 247 248The actual VSync period of the **OH_NativeVSync** instance created by calling this function may be different from the system's VSync period. The system adjusts the actual VSync period based on the window status. 249 250**System capability**: SystemCapability.Graphic.Graphic2D.NativeVsync 251 252**Since**: 14 253 254**Parameters** 255 256| Name| Description| 257| -------- | -------- | 258| 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).| 259| name | Pointer to the name that associates with the **OH_NativeVSync** instance.| 260| length | Length of the name (number of characters).| 261 262**Returns** 263 264Returns the pointer to an **OH_NativeVSync** instance. 265 266 267 268### OH_NativeVSync_Destroy() 269 270 271``` 272void OH_NativeVSync_Destroy (OH_NativeVSync * nativeVsync) 273``` 274 275**Description** 276 277Destroys an **OH_NativeVSync** instance. 278 279Once the **OH_NativeVSync** pointer is destroyed, it should not be used, as this can result in dangling pointer problems. Pay special attention to the management of the **OH_NativeVSync** pointer in multithreaded scenarios. 280 281\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 282 283**Parameters** 284 285| Name| Description| 286| -------- | -------- | 287| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 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**Description** 298 299Requests 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. 300 301\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 302 303**Parameters** 304 305| Name| Description| 306| -------- | -------- | 307| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 308| callback | Function pointer of the **OH_NativeVSync_FrameCallback** type. This function pointer will be called when the next VSync signal arrives.| 309| data | Pointer to the user-defined data struct. The type is void\*.| 310 311**Returns** 312 313Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 314 315 316### OH_NativeVSync_RequestFrameWithMultiCallback() 317 318``` 319int OH_NativeVSync_RequestFrameWithMultiCallback (OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data ) 320``` 321 322**Description** 323 324Requests 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. 325 326**System capability**: SystemCapability.Graphic.Graphic2D.NativeVsync 327 328**Since**: 12 329 330**Parameters** 331 332| Name| Description| 333| -------- | -------- | 334| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 335| callback | Function pointer of the **OH_NativeVSync_FrameCallback** type. This function pointer will be called when the next VSync signal arrives.| 336| data | Pointer to the user-defined data struct. The type is void\*.| 337 338**Returns** 339 340Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 341