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_Destroy](#oh_nativevsync_destroy) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync) | Destroys an **OH_NativeVSync** instance.| 47| 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.| 48| 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.| 49| [OH_NativeVSync_GetPeriod](#oh_nativevsync_getperiod) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, long long \*period) |Obtains the VSync period.| 50 51## Type Description 52 53 54### OH_NativeVSync 55 56 57``` 58typedef struct OH_NativeVSync OH_NativeVSync 59``` 60 61**Description** 62 63Provides the declaration of an **OH_NativeVSync** struct. 64 65 66### OH_NativeVSync_FrameCallback 67 68 69``` 70typedef void(* OH_NativeVSync_FrameCallback) (long long timestamp, void *data) 71``` 72 73**Description** 74 75Defines the pointer to a VSync callback function. 76 77\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 78 79**Parameters** 80 81| Name| Description| 82| -------- | -------- | 83| timestamp | VSync timestamp.| 84| data | User-defined data.| 85 86 87### OHNativeErrorCode 88 89``` 90typedef enum OHNativeErrorCode OHNativeErrorCode 91``` 92 93**Description** 94 95Defines an enum for the error codes. 96 97**Since**: 12 98 99 100## Enum Description 101 102 103### OHNativeErrorCode 104 105``` 106enum OHNativeErrorCode 107``` 108 109**Description** 110 111Enumerates the error codes. 112 113**Since**: 12 114 115| Value| Description| 116| -------- | -------- | 117| NATIVE_ERROR_OK | The operation is successful. | 118| NATIVE_ERROR_INVALID_ARGUMENTS | An input parameter is invalid. | 119| NATIVE_ERROR_NO_PERMISSION | You do not have the permission to perform the operation. | 120| NATIVE_ERROR_NO_BUFFER | No buffer is available. | 121| NATIVE_ERROR_NO_CONSUMER | The consumer does not exist. | 122| NATIVE_ERROR_NOT_INIT | Not initialized. | 123| NATIVE_ERROR_CONSUMER_CONNECTED | The consumer is connected. | 124| NATIVE_ERROR_BUFFER_STATE_INVALID | The buffer status does not meet the expectation. | 125| NATIVE_ERROR_BUFFER_IN_CACHE | The buffer is already in the buffer queue. | 126| NATIVE_ERROR_BUFFER_QUEUE_FULL | The queue is full. | 127| NATIVE_ERROR_BUFFER_NOT_IN_CACHE | The buffer is not in the buffer queue. | 128| NATIVE_ERROR_CONSUMER_DISCONNECTED | The consumer is disconnected.| 129| NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED | No listener is registered on the consumer side.| 130| NATIVE_ERROR_UNSUPPORTED | The device or platform does not support the operation. | 131| NATIVE_ERROR_UNKNOWN | Unknown error. Check the log. | 132| NATIVE_ERROR_HDI_ERROR | Failed to call the HDI. | 133| NATIVE_ERROR_BINDER_ERROR | Cross-process communication failed. | 134| NATIVE_ERROR_EGL_STATE_UNKNOWN | The EGL environment is abnormal. | 135| NATIVE_ERROR_EGL_API_FAILED | Failed to call the EGL APIs. | 136 137## Function Description 138 139### OH_NativeVSync_GetPeriod() 140 141 142``` 143int OH_NativeVSync_GetPeriod (OH_NativeVSync * nativeVsync, long long * period ) 144``` 145 146**Description** 147 148Obtains the VSync period. 149 150\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 151 152**Parameters** 153 154| Name| Description| 155| -------- | -------- | 156| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 157| period | Pointer to the VSync period.| 158 159**Returns** 160 161Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 162 163**Since** 164 16510 166 167 168### OH_NativeVSync_Create() 169 170 171``` 172OH_NativeVSync* OH_NativeVSync_Create (const char * name, unsigned int length ) 173``` 174 175**Description** 176 177Creates an **OH_NativeVSync** instance. A new **OH_NativeVSync** instance is created each time this function is called. 178 179\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 180 181**Parameters** 182 183| Name| Description| 184| -------- | -------- | 185| name | Pointer to the name that associates with an **OH_NativeVSync** instance.| 186| length | Length of the name.| 187 188**Returns** 189 190Returns the pointer to an **OH_NativeVSync** instance. 191 192 193### OH_NativeVSync_Destroy() 194 195 196``` 197void OH_NativeVSync_Destroy (OH_NativeVSync * nativeVsync) 198``` 199 200**Description** 201 202Destroys an **OH_NativeVSync** instance. 203 204\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 205 206**Parameters** 207 208| Name| Description| 209| -------- | -------- | 210| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 211 212 213### OH_NativeVSync_RequestFrame() 214 215 216``` 217int OH_NativeVSync_RequestFrame (OH_NativeVSync * nativeVsync, OH_NativeVSync_FrameCallback callback, void * data ) 218``` 219 220**Description** 221 222Requests 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. 223 224\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync 225 226**Parameters** 227 228| Name| Description| 229| -------- | -------- | 230| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 231| callback | Function pointer of the **OH_NativeVSync_FrameCallback** type. This function pointer will be called when the next VSync signal arrives.| 232| data | Pointer to the user-defined data struct. The type is void\*.| 233 234**Returns** 235 236Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 237 238 239### OH_NativeVSync_RequestFrameWithMultiCallback() 240 241``` 242int OH_NativeVSync_RequestFrameWithMultiCallback (OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data ) 243``` 244 245**Description** 246 247Requests 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. 248 249**System capability**: SystemCapability.Graphic.Graphic2D.NativeVsync 250 251**Since**: 12 252 253**Parameters** 254 255| Name| Description| 256| -------- | -------- | 257| nativeVsync | Pointer to an **OH_NativeVSync** instance.| 258| callback | Function pointer of the **OH_NativeVSync_FrameCallback** type. This function pointer will be called when the next VSync signal arrives.| 259| data | Pointer to the user-defined data struct. The type is void\*.| 260 261**Returns** 262 263Returns **0** if the operation is successful; returns an error code defined in [OHNativeErrorCode](#ohnativeerrorcode) otherwise. 264