1# NativeVsync
2
3
4## 概述
5
6提供NativeVsync功能。
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_Destroy](#oh_nativevsync_destroy) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync) | 销毁OH_NativeVSync实例。 |
47| int [OH_NativeVSync_RequestFrame](#oh_nativevsync_requestframe) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback) callback, void \*data) | 请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，则只会触发最后一个回调。 | 
48| int [OH_NativeVSync_RequestFrameWithMultiCallback](#oh_nativevsync_requestframewithmulticallback) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, [OH_NativeVSync_FrameCallback](#oh_nativevsync_framecallback) callback, void \*data) | 请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。 | 
49| [OH_NativeVSync_GetPeriod](#oh_nativevsync_getperiod) ([OH_NativeVSync](#oh_nativevsync) \*nativeVsync, long long \*period) |获取vsync周期。|
50| 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信号。 | 
51
52## 类型定义说明
53
54
55### OH_NativeVSync
56
57
58```
59typedef struct OH_NativeVSync OH_NativeVSync
60```
61
62**描述:**
63
64提供OH_NativeVSync结构体声明。
65
66
67### OH_NativeVSync_FrameCallback
68
69
70```
71typedef void(* OH_NativeVSync_FrameCallback) (long long timestamp, void *data)
72```
73
74**描述:**
75
76VSync回调函数类型。
77
78\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
79
80**参数:**
81
82| 名称 | 描述 |
83| -------- | -------- |
84| timestamp | VSync时间戳。 |
85| data | 用户自定义数据。 |
86
87
88### OHNativeErrorCode
89
90```
91typedef enum OHNativeErrorCode OHNativeErrorCode
92```
93
94**描述**
95
96接口错误码说明（仅用于查询）。
97
98**起始版本：** 12
99
100
101## 枚举类型说明
102
103
104### OHNativeErrorCode
105
106```
107enum OHNativeErrorCode
108```
109
110**描述**
111
112接口错误码说明（仅用于查询）。
113
114**起始版本：** 12
115
116| 枚举值 | 描述 | 
117| -------- | -------- |
118| NATIVE_ERROR_OK  | 成功   | 
119| NATIVE_ERROR_INVALID_ARGUMENTS  | 入参无效   | 
120| NATIVE_ERROR_NO_PERMISSION  | 无权限操作   | 
121| NATIVE_ERROR_NO_BUFFER  | 无空闲可用的buffer   | 
122| NATIVE_ERROR_NO_CONSUMER  | 消费端不存在   | 
123| NATIVE_ERROR_NOT_INIT  | 未初始化   | 
124| NATIVE_ERROR_CONSUMER_CONNECTED  | 消费端已经被连接   | 
125| NATIVE_ERROR_BUFFER_STATE_INVALID  | buffer状态不符合预期   | 
126| NATIVE_ERROR_BUFFER_IN_CACHE  | buffer已在缓存队列中   | 
127| NATIVE_ERROR_BUFFER_QUEUE_FULL  | 队列已满   | 
128| NATIVE_ERROR_BUFFER_NOT_IN_CACHE  | buffer不在缓存队列中   | 
129| NATIVE_ERROR_CONSUMER_DISCONNECTED | 消费端已经被断开连接 |
130| NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED | 消费端未注册listener回调函数 |
131| NATIVE_ERROR_UNSUPPORTED  | 当前设备或平台不支持   | 
132| NATIVE_ERROR_UNKNOWN  | 未知错误，请查看日志   | 
133| NATIVE_ERROR_HDI_ERROR  | HDI接口调用失败   | 
134| NATIVE_ERROR_BINDER_ERROR  | 跨进程通信失败   |  
135| NATIVE_ERROR_EGL_STATE_UNKNOWN  | egl环境状态异常   | 
136| NATIVE_ERROR_EGL_API_FAILED  | egl接口调用失败   | 
137
138## 函数说明
139
140
141### OH_NativeVSync_DVSyncSwitch()
142
143```
144int OH_NativeVSync_DVSyncSwitch (OH_NativeVSync* nativeVsync, bool enable )
145```
146
147**描述**
148
149启用DVSync以提高自绘制动画场景的流畅性。 DVSync是Decoupled VSync的缩写，它是一种与硬件VSync解耦的帧时序管理策略。
150
151DVSync通过提前发送带有未来时间戳的VSync信号驱动后续动画帧的提前绘制，这些帧会被帧缓冲队列缓存；DVSync通过缓存的帧减少未来可能发生的丢帧，进而提高动画场景的流畅性。
152
153因为DVSync需要占用空闲的自绘制帧缓冲用于缓存提前绘制的动画帧，用户需要确保至少有一个空闲的帧缓冲区，否则不建议启用此功能。
154
155启用DVSync后，用户需要正确响应提前发送的VSync信号，并在前一个VSync对应的动画帧完成后再请求下一个VSync，且自绘制帧需要携带与VSync一致的时间戳。
156
157在动画结束之后，用户需要关闭DVSync。
158
159在不支持DVSync的平台或者如果有另一个应用程序已经启用了DVSync，则当前的启用操作将不会生效，应用程序仍将收到正常的VSync信号。
160
161**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync
162
163**起始版本：** 14
164
165**参数:**
166
167| 名称 | 描述 | 
168| -------- | -------- |
169| nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 
170| enable | 表示打开或者关闭DVSync，true表示打开，false表示关闭。 | 
171
172**返回：**
173
174返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。
175
176
177
178### OH_NativeVSync_GetPeriod()
179
180
181```
182int OH_NativeVSync_GetPeriod (OH_NativeVSync * nativeVsync, long long * period )
183```
184
185**描述:**
186
187获取vsync周期。
188
189\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
190
191**参数:**
192
193| 名称 | 描述 |
194| -------- | -------- |
195| nativeVsync | 一个指向OH_NativeVSync实例的指针。|
196| period | 用于获取vsync周期的变量。 |
197
198**返回:**
199
200返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。
201
202**起始版本：**
203
20410
205
206
207### OH_NativeVSync_Create()
208
209
210```
211OH_NativeVSync* OH_NativeVSync_Create (const char * name, unsigned int length )
212```
213
214**描述:**
215
216创建一个OH_NativeVSync实例，每次调用都会产生一个新的实例。
217
218\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
219
220**参数:**
221
222| 名称 | 描述 |
223| -------- | -------- |
224| name | 表示一个名字，与创建的OH_NativeVSync实例关联。 |
225| length | name的长度。 |
226
227**返回:**
228
229返回一个指向OH_NativeVSync实例的指针。
230
231
232### OH_NativeVSync_Destroy()
233
234
235```
236void OH_NativeVSync_Destroy (OH_NativeVSync * nativeVsync)
237```
238
239**描述:**
240
241销毁OH_NativeVSync实例。
242
243\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
244
245**参数:**
246
247| 名称 | 描述 |
248| -------- | -------- |
249| nativeVsync | 一个指向OH_NativeVSync实例的指针。 |
250
251
252### OH_NativeVSync_RequestFrame()
253
254
255```
256int OH_NativeVSync_RequestFrame (OH_NativeVSync * nativeVsync, OH_NativeVSync_FrameCallback callback, void * data )
257```
258
259**描述:**
260
261请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，则只会触发最后一个回调。
262
263\@syscap SystemCapability.Graphic.Graphic2D.NativeVsync
264
265**参数:**
266
267| 名称 | 描述 |
268| -------- | -------- |
269| nativeVsync | 一个指向OH_NativeVSync实例的指针。 |
270| callback | 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。 |
271| data | 一个指向用户自定义数据结构的指针，类型是void\*。 |
272
273**返回:**
274
275返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。
276
277
278### OH_NativeVSync_RequestFrameWithMultiCallback()
279
280```
281int OH_NativeVSync_RequestFrameWithMultiCallback (OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data )
282```
283
284**描述**
285
286请求下一次vsync信号，当信号到来时，调用回调函数callback。 如果在同一帧内中多次调用此接口，每一次传入的callback都会被执行。
287
288**系统能力：** SystemCapability.Graphic.Graphic2D.NativeVsync
289
290**起始版本：** 12
291
292**参数:**
293
294| 名称 | 描述 | 
295| -------- | -------- |
296| nativeVsync | 一个指向OH_NativeVSync实例的指针。 | 
297| callback | 一个OH_NativeVSync_FrameCallback类型的函数指针，当下一次vsync信号到来时会被调用。 | 
298| data | 一个指向用户自定义数据结构的指针，类型是void\*。 | 
299
300**返回：**
301
302返回值为0表示执行成功，其他返回值可参考[OHNativeErrorCode](#ohnativeerrorcode)。