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/>**引用文件：** &lt;native_vsync/native_vsync.h&gt; <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_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_INVALID_ARGUMENTS  | 入参无效   |
121| NATIVE_ERROR_NO_PERMISSION  | 无权限操作   |
122| NATIVE_ERROR_NO_BUFFER  | 无空闲可用的buffer   |
123| NATIVE_ERROR_NO_CONSUMER  | 消费端不存在   |
124| NATIVE_ERROR_NOT_INIT  | 未初始化   |
125| NATIVE_ERROR_CONSUMER_CONNECTED  | 消费端已经被连接   |
126| NATIVE_ERROR_BUFFER_STATE_INVALID  | buffer状态不符合预期   |
127| NATIVE_ERROR_BUFFER_IN_CACHE  | buffer已在缓存队列中   |
128| NATIVE_ERROR_BUFFER_QUEUE_FULL  | 队列已满   |
129| NATIVE_ERROR_BUFFER_NOT_IN_CACHE  | buffer不在缓存队列中   |
130| NATIVE_ERROR_CONSUMER_DISCONNECTED | 消费端已经被断开连接 |
131| NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED | 消费端未注册listener回调函数 |
132| NATIVE_ERROR_UNSUPPORTED  | 当前设备或平台不支持   |
133| NATIVE_ERROR_UNKNOWN  | 未知错误，请查看日志   |
134| NATIVE_ERROR_HDI_ERROR  | HDI接口调用失败   |
135| NATIVE_ERROR_BINDER_ERROR  | 跨进程通信失败   |
136| NATIVE_ERROR_EGL_STATE_UNKNOWN  | egl环境状态异常   |
137| NATIVE_ERROR_EGL_API_FAILED  | egl接口调用失败   |
138
139## 函数说明
140
141
142### OH_NativeVSync_DVSyncSwitch()
143
144```
145int OH_NativeVSync_DVSyncSwitch (OH_NativeVSync* nativeVsync, bool enable )
146```
147
148**描述**
149
150启用DVSync以提高自绘制动画场景的流畅性。 DVSync是Decoupled VSync的缩写，它是一种与硬件VSync解耦的帧时序管理策略。
151
152DVSync通过提前发送带有未来时间戳的VSync信号驱动后续动画帧的提前绘制，这些帧会被帧缓冲队列缓存；DVSync通过缓存的帧减少未来可能发生的丢帧，进而提高动画场景的流畅性。
153
154因为DVSync需要占用空闲的自绘制帧缓冲用于缓存提前绘制的动画帧，用户需要确保至少有一个空闲的帧缓冲区，否则不建议启用此功能。
155
156启用DVSync后，用户需要正确响应提前发送的VSync信号，并在前一个VSync对应的动画帧完成后再请求下一个VSync，且自绘制帧需要携带与VSync一致的时间戳。
157
158在动画结束之后，用户需要关闭DVSync。
159
160在不支持DVSync的平台或者如果有另一个应用程序已经启用了DVSync，则当前的启用操作将不会生效，应用程序仍将收到正常的VSync信号。
161
162**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync
163
164**起始版本：** 14
165
166**参数:**
167
168| 名称 | 描述 |
169| -------- | -------- |
170| nativeVsync | 一个指向OH_NativeVSync实例的指针。 |
171| enable | 表示打开或者关闭DVSync，true表示打开，false表示关闭。 |
172
173**返回：**
174
175返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。
176
177
178
179### OH_NativeVSync_GetPeriod()
180
181
182```
183int OH_NativeVSync_GetPeriod (OH_NativeVSync * nativeVsync, long long * period )
184```
185
186**描述:**
187
188获取vsync周期。
189
190vsync周期是在每次使用OH_NativeVSync_RequestFrame接口请求vsync信号后收到OH_NativeVSync_FrameCallback回调的时候才会更新。
191
192首次使用该接口获取vsync周期之前，需要先使用OH_NativeVSync_RequestFrame接口请求vsync信号，在收到OH_NativeVSync_FrameCallback回调之后，才可以通过该接口获取到vsync周期。
193
194\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
195
196**参数:**
197
198| 名称 | 描述 |
199| -------- | -------- |
200| nativeVsync | 一个指向OH_NativeVSync实例的指针。|
201| period | 表示vsync周期，作为出参使用。 |
202
203**返回:**
204
205返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。
206
207**起始版本：**
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**描述:**
220
221创建一个OH_NativeVSync实例，每次调用都会产生一个新的实例。
222
223\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
224
225**参数:**
226
227| 名称 | 描述 |
228| -------- | -------- |
229| name | 表示一个名字，与创建的OH_NativeVSync实例关联。 |
230| length | name的长度（字符数）。 |
231
232**返回:**
233
234返回一个指向OH_NativeVSync实例的指针。
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**描述**
244
245创建一个和窗口绑定的OH_NativeVSync实例，每次调用都会产生一个新的实例。
246
247使用本接口创建出来的OH_NativeVSync实例的实际vsync周期与系统vsync周期不完全一致，系统会根据窗口的状态对实际vsync周期进行调整。
248
249**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync
250
251**起始版本：** 14
252
253**参数:**
254
255| 名称 | 描述 |
256| -------- | -------- |
257| windowID | 表示窗口ID，窗口子进程索引标识符，可以通过[OH_NativeWindow_GetSurfaceId](_native_window.md#oh_nativewindow_getsurfaceid)接口获取。 |
258| name | 表示一个名称，与创建的OH_NativeVSync实例关联。 |
259| length | name的长度（字符数）。 |
260
261**返回：**
262
263返回一个指向OH_NativeVSync实例的指针。
264
265
266
267### OH_NativeVSync_Destroy()
268
269
270```
271void OH_NativeVSync_Destroy (OH_NativeVSync * nativeVsync)
272```
273
274**描述:**
275
276销毁OH_NativeVSync实例。
277
278销毁后的OH_NativeVSync指针不能再继续使用，否则会有野指针问题，尤其需要注意多线程并发时对于OH_NativeVSync指针的管理。
279
280\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
281
282**参数:**
283
284| 名称 | 描述 |
285| -------- | -------- |
286| nativeVsync | 一个指向OH_NativeVSync实例的指针。 |
287
288
289### OH_NativeVSync_RequestFrame()
290
291
292```
293int OH_NativeVSync_RequestFrame (OH_NativeVSync * nativeVsync, OH_NativeVSync_FrameCallback callback, void * data )
294```
295
296**描述:**
297
298请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，则只会触发最后一个回调。
299
300\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
301
302**参数:**
303
304| 名称 | 描述 |
305| -------- | -------- |
306| nativeVsync | 一个指向OH_NativeVSync实例的指针。 |
307| callback | 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。 |
308| data | 一个指向用户自定义数据结构的指针，类型是void\*。 |
309
310**返回:**
311
312返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。
313
314
315### OH_NativeVSync_RequestFrameWithMultiCallback()
316
317```
318int OH_NativeVSync_RequestFrameWithMultiCallback (OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data )
319```
320
321**描述**
322
323请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。
324
325**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync
326
327**起始版本：** 12
328
329**参数:**
330
331| 名称 | 描述 |
332| -------- | -------- |
333| nativeVsync | 一个指向OH_NativeVSync实例的指针。 |
334| callback | 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。 |
335| data | 一个指向用户自定义数据结构的指针，类型是void\*。 |
336
337**返回：**
338
339返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。