• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# VideoDecoder
2
3
4## 概述
5
6VideoDecoder模块提供用于视频解码功能的函数。该模块在部分设备上可能不支持，可以通过[CanIUse](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/syscap.md)接口确认。
7
8@syscap SystemCapability.Multimedia.Media.VideoDecoder
9
10**起始版本：**
119
12
13
14## 汇总
15
16
17### 文件
18
19  | 名称 | 描述 |
20| -------- | -------- |
21| [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | 声明用于视频解码的Native API。<br>引用文件：<multimedia/player_framework/native_avcodec_videodecoder.h>  |
22
23
24### 函数
25
26  | 名称 | 描述 |
27| -------- | -------- |
28| [OH_VideoDecoder_CreateByMime](#oh_videodecoder_createbymime) (const char \*mime) | 通过mime类型创建一个视频解码器实例，大多数情况下推荐使用该接口。  |
29| [OH_VideoDecoder_CreateByName](#oh_videodecoder_createbyname) (const char \*name) | 通过视频解码器名称创建一个视频解码器实例，使用这个接口的前提是必须清楚解码器准确的名称。  |
30| [OH_VideoDecoder_Destroy](#oh_videodecoder_destroy) (OH_AVCodec \*codec) | 清空解码器内部资源，并销毁解码器实例。  |
31| [OH_VideoDecoder_SetCallback](#oh_videodecoder_setcallback) (OH_AVCodec \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | 设置异步回调函数，使得你的应用能够响应视频解码器产生的事件，该接口被调用必须是在Prepare被调用前。  |
32| [OH_VideoDecoder_SetSurface](#oh_videodecoder_setsurface) (OH_AVCodec \*codec, OHNativeWindow \*window) | 指定输出Surface，以提供视频解码输出，该接口被调用必须是在Prepare被调用前。  |
33| [OH_VideoDecoder_Configure](#oh_videodecoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | 配置视频解码器，典型地，需要配置被解码视频轨道的描述信息，这些信息能够从容器中提取出来， 该接口被调用必须是在Prepare被调用前。  |
34| [OH_VideoDecoder_Prepare](#oh_videodecoder_prepare) (OH_AVCodec \*codec) | 准备解码器内部资源，调用该接口前必须先调用Configure接口。  |
35| [OH_VideoDecoder_Start](#oh_videodecoder_start) (OH_AVCodec \*codec) | 启动解码器，该接口必须在已经Prepare成功后调用。 在启动成功后，解码器将开始报告[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)事件。  |
36| [OH_VideoDecoder_Stop](#oh_videodecoder_stop) (OH_AVCodec \*codec) | 停止解码器。在停止后可通过Start重新进入Started状态，但需要注意的是，若先前给解码器输入过 Codec-Specific-Data，则需要重新输入。  |
37| [OH_VideoDecoder_Flush](#oh_videodecoder_flush) (OH_AVCodec \*codec) | 清空解码器内部缓存的输入输出数据。在该接口被调用后，所有先前通过异步回调报告的Buffer的索引都将 失效，确保不要再访问这些索引对应的Buffers。  |
38| [OH_VideoDecoder_Reset](#oh_videodecoder_reset) (OH_AVCodec \*codec) | 重置解码器。如需继续解码工作，需要重新调用Configure接口以配置该解码器实例。  |
39| [OH_VideoDecoder_GetOutputDescription](#oh_videodecoder_getoutputdescription) (OH_AVCodec \*codec) | 获取该解码器输出数据的描述信息，需要注意的是，返回值所指向的OH_AVFormat实例的生命周期 将会再下一次调用该接口时或者该OH_AVCodec实例被销毁时失效。  |
40| [OH_VideoDecoder_SetParameter](#oh_videodecoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | 向解码器设置动态参数，注意：该接口仅能在解码器被启动后调用，同时错误的参数设置，可能会导致解码失败。  |
41| [OH_VideoDecoder_PushInputData](#oh_videodecoder_pushinputdata) (OH_AVCodec \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | 将填充好数据的输入Buffer提交给视频解码器。[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)回调会报告可用的输入 Buffer及对应的索引值。一旦指定索引的Buffer被提交给解码器，直到再一次收到[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) 回调报告相同索引的Buffer可用前，该Buffer都不可以再次被访问。另外，对于部分解码器，要求在最开始给解码器输入 Codec-Specific-Data，用以初始化解码器的解码过程，例如H264格式的PPS/SPS数据。  |
42| [OH_VideoDecoder_RenderOutputData](#oh_videodecoder_renderoutputdata) (OH_AVCodec \*codec, uint32_t index) | 将处理结束的输出Buffer交还给解码器，并通知解码器完成将该Buffer内包含的解码后的数据在输出Surface上渲染。 如果先前未配置输出Surface，调用该接口仅仅将指定索引对应的输出Buffer交还给解码器。  |
43| [OH_VideoDecoder_FreeOutputData](#oh_videodecoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | 将处理结束的输出Buffer交还给解码器。  |
44
45
46## 函数说明
47
48
49### OH_VideoDecoder_Configure()
50
51
52```
53OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec * codec, OH_AVFormat * format )
54```
55**描述:**
56配置视频解码器，典型地，需要配置被解码视频轨道的描述信息，这些信息能够从容器中提取出来， 该接口被调用必须是在Prepare被调用前。
57
58@syscap SystemCapability.Multimedia.Media.VideoDecoder
59
60**参数:**
61
62  | 名称 | 描述 |
63| -------- | -------- |
64| codec | 指向OH_AVCodec实例的指针  |
65| format | 指向OH_AVFormat的指针，用以给出待解码视频轨道的描述信息  |
66
67**返回:**
68
69执行成功返回AV_ERR_OK
70
71执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
72
73
74### OH_VideoDecoder_CreateByMime()
75
76
77```
78OH_AVCodec* OH_VideoDecoder_CreateByMime (const char * mime)
79```
80**描述:**
81通过mime类型创建一个视频解码器实例，大多数情况下推荐使用该接口。
82
83@syscap SystemCapability.Multimedia.Media.VideoDecoder
84
85**参数:**
86
87  | 名称 | 描述 |
88| -------- | -------- |
89| mime | mime类型描述字符串，参考[OH_AVCODEC_MIMETYPE_VIDEO_AVC](_codec_base.md#oh_avcodec_mimetype_video_avc) |
90
91**返回:**
92
93返回一个指向OH_AVCodec实例的指针
94
95
96### OH_VideoDecoder_CreateByName()
97
98
99```
100OH_AVCodec* OH_VideoDecoder_CreateByName (const char * name)
101```
102**描述:**
103通过视频解码器名称创建一个视频解码器实例，使用这个接口的前提是必须清楚解码器准确的名称。
104
105@syscap SystemCapability.Multimedia.Media.VideoDecoder
106
107**参数:**
108
109  | 名称 | 描述 |
110| -------- | -------- |
111| name | 视频解码器名称  |
112
113**返回:**
114
115返回一个指向OH_AVCodec实例的指针
116
117
118### OH_VideoDecoder_Destroy()
119
120
121```
122OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec * codec)
123```
124**描述:**
125清空解码器内部资源，并销毁解码器实例。
126
127@syscap SystemCapability.Multimedia.Media.VideoDecoder
128
129**参数:**
130
131  | 名称 | 描述 |
132| -------- | -------- |
133| codec | 指向OH_AVCodec实例的指针  |
134
135**返回:**
136
137执行成功返回AV_ERR_OK
138
139执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
140
141
142### OH_VideoDecoder_Flush()
143
144
145```
146OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec * codec)
147```
148**描述:**
149清空解码器内部缓存的输入输出数据。在该接口被调用后，所有先前通过异步回调报告的Buffer的索引都将 失效，确保不要再访问这些索引对应的Buffers。
150
151@syscap SystemCapability.Multimedia.Media.VideoDecoder
152
153**参数:**
154
155  | 名称 | 描述 |
156| -------- | -------- |
157| codec | 指向OH_AVCodec实例的指针  |
158
159**返回:**
160
161执行成功返回AV_ERR_OK
162
163执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
164
165
166### OH_VideoDecoder_FreeOutputData()
167
168
169```
170OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec * codec, uint32_t index )
171```
172**描述:**
173将处理结束的输出Buffer交还给解码器。
174
175@syscap SystemCapability.Multimedia.Media.VideoDecoder
176
177**参数:**
178
179  | 名称 | 描述 |
180| -------- | -------- |
181| codec | 指向OH_AVCodec实例的指针  |
182| index | 输出Buffer对应的索引值  |
183
184**返回:**
185
186执行成功返回AV_ERR_OK
187
188执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
189
190
191### OH_VideoDecoder_GetOutputDescription()
192
193
194```
195OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec * codec)
196```
197**描述:**
198获取该解码器输出数据的描述信息，需要注意的是，返回值所指向的OH_AVFormat实例的生命周期 将会再下一次调用该接口时或者该OH_AVCodec实例被销毁时失效。
199
200@syscap SystemCapability.Multimedia.Media.VideoDecoder
201
202**参数:**
203
204  | 名称 | 描述 |
205| -------- | -------- |
206| codec | 指向OH_AVCodec实例的指针  |
207
208**返回:**
209
210返回AVFormat实例的指针
211
212
213### OH_VideoDecoder_Prepare()
214
215
216```
217OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec * codec)
218```
219**描述:**
220准备解码器内部资源，调用该接口前必须先调用Configure接口。
221
222@syscap SystemCapability.Multimedia.Media.VideoDecoder
223
224**参数:**
225
226  | 名称 | 描述 |
227| -------- | -------- |
228| codec | 指向OH_AVCodec实例的指针  |
229
230**返回:**
231
232执行成功返回AV_ERR_OK
233
234执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
235
236
237### OH_VideoDecoder_PushInputData()
238
239
240```
241OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec * codec, uint32_t index, OH_AVCodecBufferAttr attr )
242```
243**描述:**
244将填充好数据的输入Buffer提交给视频解码器。[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)回调会报告可用的输入 Buffer及对应的索引值。一旦指定索引的Buffer被提交给解码器，直到再一次收到[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) 回调报告相同索引的Buffer可用前，该Buffer都不可以再次被访问。另外，对于部分解码器，要求在最开始给解码器输入 Codec-Specific-Data，用以初始化解码器的解码过程，例如H264格式的PPS/SPS数据。
245
246@syscap SystemCapability.Multimedia.Media.VideoDecoder
247
248**参数:**
249
250  | 名称 | 描述 |
251| -------- | -------- |
252| codec | 指向OH_AVCodec实例的指针  |
253| index | 输入Buffer对应的索引值  |
254| attr | 描述该Buffer内所包含数据的信息  |
255
256**返回:**
257
258执行成功返回AV_ERR_OK
259
260执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
261
262
263### OH_VideoDecoder_RenderOutputData()
264
265
266```
267OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec * codec, uint32_t index )
268```
269**描述:**
270将处理结束的输出Buffer交还给解码器，并通知解码器完成将该Buffer内包含的解码后的数据在输出Surface上渲染。 如果先前未配置输出Surface，调用该接口仅仅将指定索引对应的输出Buffer交还给解码器。
271
272@syscap SystemCapability.Multimedia.Media.VideoDecoder
273
274**参数:**
275
276  | 名称 | 描述 |
277| -------- | -------- |
278| codec | 指向OH_AVCodec实例的指针  |
279| index | 输出Buffer对应的索引值  |
280
281**返回:**
282
283执行成功返回AV_ERR_OK
284
285执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
286
287
288### OH_VideoDecoder_Reset()
289
290
291```
292OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec * codec)
293```
294**描述:**
295重置解码器。如需继续解码工作，需要重新调用Configure接口以配置该解码器实例。
296
297@syscap SystemCapability.Multimedia.Media.VideoDecoder
298
299**参数:**
300
301  | 名称 | 描述 |
302| -------- | -------- |
303| codec | 指向OH_AVCodec实例的指针  |
304
305**返回:**
306
307执行成功返回AV_ERR_OK
308
309执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
310
311
312### OH_VideoDecoder_SetCallback()
313
314
315```
316OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec * codec, OH_AVCodecAsyncCallback callback, void * userData )
317```
318**描述:**
319设置异步回调函数，使得你的应用能够响应视频解码器产生的事件，该接口被调用必须是在Prepare被调用前。
320
321@syscap SystemCapability.Multimedia.Media.VideoDecoder
322
323**参数:**
324
325  | 名称 | 描述 |
326| -------- | -------- |
327| codec | 指向OH_AVCodec实例的指针  |
328| callback | 一个包含所有回调函数的集合体，参考[OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) |
329| userData | 用户特定数据  |
330
331**返回:**
332
333执行成功返回AV_ERR_OK
334
335执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
336
337
338### OH_VideoDecoder_SetParameter()
339
340
341```
342OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec * codec, OH_AVFormat * format )
343```
344**描述:**
345向解码器设置动态参数，注意：该接口仅能在解码器被启动后调用，同时错误的参数设置，可能会导致解码失败。
346
347@syscap SystemCapability.Multimedia.Media.VideoDecoder
348
349**参数:**
350
351  | 名称 | 描述 |
352| -------- | -------- |
353| codec | 指向OH_AVCodec实例的指针  |
354| format | 指向OH_AVFormat实例的指针  |
355
356**返回:**
357
358执行成功返回AV_ERR_OK
359
360执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
361
362
363### OH_VideoDecoder_SetSurface()
364
365
366```
367OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec * codec, OHNativeWindow * window )
368```
369**描述:**
370指定输出Surface，以提供视频解码输出，该接口被调用必须是在Prepare被调用前。
371
372@syscap SystemCapability.Multimedia.Media.VideoDecoder
373
374**参数:**
375
376  | 名称 | 描述 |
377| -------- | -------- |
378| codec | 指向OH_AVCodec实例的指针  |
379| window | 指向一个OHNativeWindow实例的指针  |
380
381**返回:**
382
383执行成功返回AV_ERR_OK
384
385执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
386
387
388### OH_VideoDecoder_Start()
389
390
391```
392OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec * codec)
393```
394**描述:**
395启动解码器，该接口必须在已经Prepare成功后调用。 在启动成功后，解码器将开始报告[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)事件。
396
397@syscap SystemCapability.Multimedia.Media.VideoDecoder
398
399**参数:**
400
401  | 名称 | 描述 |
402| -------- | -------- |
403| codec | 指向OH_AVCodec实例的指针  |
404
405**返回:**
406
407执行成功返回AV_ERR_OK
408
409执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
410
411
412### OH_VideoDecoder_Stop()
413
414
415```
416OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec * codec)
417```
418**描述:**
419停止解码器。在停止后可通过Start重新进入Started状态，但需要注意的是，若先前给解码器输入过 Codec-Specific-Data，则需要重新输入。
420
421@syscap SystemCapability.Multimedia.Media.VideoDecoder
422
423**参数:**
424
425  | 名称 | 描述 |
426| -------- | -------- |
427| codec | 指向OH_AVCodec实例的指针  |
428
429**返回:**
430
431执行成功返回AV_ERR_OK
432
433执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
434