1# VideoDecoder 2 3 4## 概述 5 6VideoDecoder模块提供用于视频解码的接口。 7 8对应的开发指南及样例可参考[视频解码](../../media/avcodec/video-decoding.md)。 9 10**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 11 12**起始版本：** 9 13 14接口在每个版本的支持情况以及在解码过程中可以调用的情况，如下图所示： 15 16 17 18 19 20## 汇总 21 22 23### 文件 24 25| 名称 | 描述 | 26| -------- | -------- | 27| [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | 声明用于视频解码的接口。 | 28 29 30### 函数 31 32| 名称 | 描述 | 33| -------- | -------- | 34| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoDecoder_CreateByMime](#oh_videodecoder_createbymime) (const char \*mime) | 根据[MIME](_codec_base.md#媒体编解码格式)类型创建视频解码器实例。 | 35| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoDecoder_CreateByName](#oh_videodecoder_createbyname) (const char \*name) | 根据视频解码器名称创建视频解码器实例。 | 36| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Destroy](#oh_videodecoder_destroy) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 清理解码器内部资源，销毁解码器实例。 | 37| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetCallback](#oh_videodecoder_setcallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | 设置异步回调函数，让应用可以响应视频解码器生成的事件。（API11废弃） | 38| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecCallback](_o_h___a_v_codec_callback.md) callback, void \*userData) | 注册异步回调函数，让应用可以响应视频解码器生成的事件。 | 39| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetSurface](#oh_videodecoder_setsurface) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OHNativeWindow](_codec_base.md#ohnativewindow) \*window) | 设置输出surface以提供视频解码输出。 | 40| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Configure](#oh_videodecoder_configure) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVFormat](_core.md#oh_avformat) \*format) | 配置视频解码器，通常需要配置解码视频轨迹的描述信息，这些信息可以从[OH_AVSource](_a_v_source.md)中提取。 | 41| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Prepare](#oh_videodecoder_prepare) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 准备解码器的内部资源。 | 42| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Start](#oh_videodecoder_start) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 调用OH_VideoDecoder_Prepare接口成功后调用此接口启动解码器。 | 43| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Stop](#oh_videodecoder_stop) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 停止解码器，释放输入输出buffer。 | 44| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Flush](#oh_videodecoder_flush) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 清除解码器中缓存的输入和输出数据及参数集如H264格式的PPS/SPS。 | 45| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Reset](#oh_videodecoder_reset) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 重置解码器，解码器回到初始化状态。 | 46| [OH_AVFormat](_core.md#oh_avformat) \* [OH_VideoDecoder_GetOutputDescription](#oh_videodecoder_getoutputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 获取解码器输出数据的OH_AVFormat信息。 | 47| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetParameter](#oh_videodecoder_setparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVFormat](_core.md#oh_avformat) \*format) | 设置解码器的动态参数。 | 48| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_PushInputData](#oh_videodecoder_pushinputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | 将填充数据的输入缓冲区提交给视频解码器。（API11废弃） | 49| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputData](#oh_videodecoder_renderoutputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将处理后的输出buffer返回给解码器，并通知解码器完成在输出surface上渲染Buffer中包含的解码数据。（API11废弃） | 50| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_FreeOutputData](#oh_videodecoder_freeoutputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将处理后的输出缓冲区返回到解码器。（API11废弃） | 51| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 通知视频解码器已对index对应的缓冲区完成输入数据的填充。 | 52| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将index对应的输出缓冲返回给解码器，缓冲中携带解码输出数据，并通知解码器完成在输出surface上渲染，输出缓冲包含解码数据。 | 53| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputBufferAtTime](#oh_videodecoder_renderoutputbufferattime) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, int64_t renderTimestampNs) | 将index对应的输出缓冲返回给解码器，缓冲中携带解码输出数据，并通知解码器在调用者指定的时间内完成在输出surface上渲染，输出缓冲包含解码数据。 | 54| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将处理后的输出缓冲区返回到解码器。 | 55| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_IsValid](#oh_videodecoder_isvalid) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, bool \*isValid) | 检查当前解码实例是否有效。 | 56| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetDecryptionConfig](#oh_videodecoder_setdecryptionconfig) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, MediaKeySession \*mediaKeySession, bool secureVideoPath) | 设置解密配置。 | 57 58 59## 函数说明 60 61 62### OH_VideoDecoder_Configure() 63 64``` 65OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 66``` 67**描述** 68配置视频解码器，通常需要配置解码视频的描述信息，这些信息可以从[OH_AVSource](_a_v_source.md)中提取。在调用OH_VideoDecoder_Prepare接口之前，必须调用此接口。 69 70以下参数的配置范围可通过[能力查询](../../media/avcodec/obtain-supported-codecs.md)获取，OH_MD_KEY_ROTATION配置的参数都支持。 71 72设置OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY接口时如果当前平台不支持，不报错，走正常解码流程。 73 74参数校验规则： 75 76| Key | 配置正常范围的值 | 配置超出范围的值 | 不配置该参数 | 77| -----------------------------------------------------------------------------| -------- | -------- | ------ | 78| OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 79| OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 80| OH_MD_KEY_PIXEL_FORMAT 请参阅[OH_AVPixelFormat](_core.md#oh_avpixelformat) | AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK | 81| OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | 82| OH_MD_KEY_ROTATION 请参阅[OH_MD_KEY_ROTATION](_codec_base.md#oh_md_key_rotation)| AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | 83 84> **说明：** 85> 86> 建议按照该实例需要支持的最大分辨率来配置，否则可能会出现高于该分辨率的码流解码会触发异常。该设置直接影响应用的内存使用情况。 87 88 89**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 90 91**起始版本：** 9 92 93**参数:** 94 95| 名称 | 描述 | 96| -------- | -------- | 97| codec | 指向视频解码实例的指针。 | 98| format | 指向OH_AVFormat的指针，用于给出要解码的视频轨道的描述。 | 99 100**返回：** 101 102返回接口结果： 103 104AV_ERR_OK：执行成功。 105 106AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 107 108AV_ERR_INVALID_VAL： 109 110 1. 输入的codec指针为非解码器实例，或者为空指针； 111 2. 输入format参数不支持。 112 113AV_ERR_UNKNOWN：未知错误。 114 115AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 116 117AV_ERR_INVALID_STATE：本接口必须在OH_VideoDecoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 118 119AV_ERR_VIDEO_UNSUPPORTED_COLOR_SPACE_CONVERSION：不支持色彩空间转换功能。 120 121 122### OH_VideoDecoder_CreateByMime() 123 124``` 125OH_AVCodec* OH_VideoDecoder_CreateByMime (const char *mime) 126``` 127**描述** 128根据MIME类型创建视频解码器实例，大多数情况下建议使用。 129 130**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 131 132**起始版本：** 9 133 134**参数:** 135 136| 名称 | 描述 | 137| -------- | -------- | 138| mime | MIME类型描述字符串，请参阅[AVCODEC_MIMETYPE](_codec_base.md#变量)。 | 139 140**返回：** 141 142返回一个指向视频解码实例的指针。当传入的解码器类型不支持或者内存资源耗尽时，返回NULL。 143 144 145### OH_VideoDecoder_CreateByName() 146 147``` 148OH_AVCodec* OH_VideoDecoder_CreateByName (const char *name) 149``` 150**描述** 151根据视频解码器名称创建视频解码器实例。使用此接口的前提是知道解码器的确切名称，解码器的名称可以通过能力查询获取。 152 153详情请参见：[获取支持的编解码能力](../../media/avcodec/obtain-supported-codecs.md#创建指定名称的编解码器)。 154 155**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 156 157**起始版本：** 9 158 159**参数:** 160 161| 名称 | 描述 | 162| -------- | -------- | 163| name | 视频解码器名称。 | 164 165**返回：** 166 167返回指向视频解码实例的指针。当输入的解码器名称不支持或者内存资源耗尽时，返回NULL。 168 169 170### OH_VideoDecoder_Destroy() 171 172``` 173OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec *codec) 174``` 175**描述** 176清理解码器内部资源，销毁解码器实例。不能重复销毁。 177 178**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 179 180**起始版本：** 9 181 182**参数:** 183 184| 名称 | 描述 | 185| -------- | -------- | 186| codec | 指向视频解码实例的指针。 | 187 188**返回：** 189 190返回接口结果： 191 192AV_ERR_OK：执行成功。 193 194AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 195 196AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 197 198AV_ERR_UNKNOWN：未知错误。 199 200AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 201 202 203### OH_VideoDecoder_Flush() 204 205``` 206OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec *codec) 207``` 208**描述** 209清除解码器中缓存的输入和输出数据及参数集如H264格式的PPS/SPS。调用此接口后，以前通过异步回调上报的所有缓冲区index都将失效，请确保不要访问这些index对应的缓冲区。 210 211**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 212 213**起始版本：** 9 214 215**参数:** 216 217| 名称 | 描述 | 218| -------- | -------- | 219| codec | 指向视频解码实例的指针。 | 220 221**返回：** 222 223返回接口结果： 224 225AV_ERR_OK：执行成功。 226 227AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 228 229AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 230 231AV_ERR_UNKNOWN：未知错误。 232 233AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 234 235AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 236 237 238### OH_VideoDecoder_FreeOutputBuffer() 239 240``` 241OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 242``` 243**描述** 244将处理后的输出缓冲区返回到解码器。用户使用完需要及时调用此接口释放输出缓存区，否则会阻塞解码流程。 245 246详情请参见：[视频解码](../../media/avcodec/video-decoding.md) “Surface模式的步骤-13或Buffer模式步骤-10”。 247 248**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 249 250**起始版本：** 11 251 252**参数:** 253 254| 名称 | 描述 | 255| -------- | -------- | 256| codec | 指向视频解码实例的指针。 | 257| index | 输出buffer对应的索引值。由[OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer)给出。 | 258 259**返回：** 260 261返回接口结果： 262 263AV_ERR_OK：执行成功。 264 265AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 266 267AV_ERR_INVALID_VAL： 268 269 1. 输入的codec指针为非解码器实例，或者为空指针； 270 2. index非法或者连续给同一个index，该错误不影响后续解码流程。 271 272AV_ERR_UNKNOWN：未知错误。 273 274AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 275 276AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 277 278 279### OH_VideoDecoder_GetOutputDescription() 280 281``` 282OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec *codec) 283``` 284**描述** 285获取解码器输出数据的OH_AVFormat信息，请参阅[OH_AVFormat](_core.md#oh_avformat)。 286 287需要注意的是，返回值指向的OH_AVFormat实例的生命周期需要调用者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 288 289**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 290 291**起始版本：** 9 292 293**参数:** 294 295| 名称 | 描述 | 296| -------- | -------- | 297| codec | 指向视频解码实例的指针。 | 298 299**返回：** 300 301返回指向OH_AVFormat实例的指针。当输入的codec指针非解码器实例，或者为空指针，则返回NULL。 302 303 304### OH_VideoDecoder_IsValid() 305 306``` 307OH_AVErrCode OH_VideoDecoder_IsValid (OH_AVCodec *codec, bool *isValid ) 308``` 309**描述** 310检查当前解码实例是否有效。 311 312**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 313 314**起始版本：** 10 315 316**参数:** 317 318| 名称 | 描述 | 319| -------- | -------- | 320| codec | 指向视频解码实例的指针。 | 321| isValid | 输出参数。指向布尔类型的指针，如果解码器实例有效，则为true，如果解码器实例无效，则为false。建议调用者将isValid初始化为false。 | 322 323**返回：** 324 325返回接口结果： 326 327AV_ERR_OK：执行成功。 328 329AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 330 331 332### OH_VideoDecoder_Prepare() 333 334``` 335OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec *codec) 336``` 337**描述** 338准备解码器的内部资源，在调用该接口之前，必须调用OH_VideoDecoder_Configure接口。 339 340**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 341 342**起始版本：** 9 343 344**参数:** 345 346| 名称 | 描述 | 347| -------- | -------- | 348| codec | 指向视频解码实例的指针。 | 349 350**返回：** 351 352返回接口结果： 353 354AV_ERR_OK：执行成功。 355 356AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 357 358AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 359 360AV_ERR_UNKNOWN：未知错误。 361 362AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 363 364AV_ERR_OPERATE_NOT_PERMIT： 365 366 1. 内部执行错误； 367 2. 配置了色彩空间转换功能，但解码器处于Buffer模式。 368 369 370### OH_VideoDecoder_PushInputBuffer() 371 372``` 373OH_AVErrCode OH_VideoDecoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 374``` 375**描述** 376通知视频解码器已对index对应的缓冲区完成输入数据的填充。 377 378输入回调将报告可用的输入缓冲区和相应的index值，请参阅[OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer)。 一旦具有指定index的缓冲区提交到视频解码器，则无法再次访问缓冲区，直到再次收到输入回调，报告具有相同index的缓冲区可用。 379 380此外，对于某些解码器，需要在开始时向解码器输入编解码特定数据，以初始化解码器的解码过程，如H264格式的PPS/SPS数据。 381调用者可以使用该接口把解码需要的参数集如H264格式的PPS/SPS传递给解码器，该参数集可以单独送入解码器也可以和要解码的数据一起传入。 382 383**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 384 385**起始版本：** 11 386 387**参数:** 388 389| 名称 | 描述 | 390| -------- | -------- | 391| codec | 指向视频解码实例的指针。 | 392| index | 输入buffer对应的索引值。由[OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer)给出。| 393 394**返回：** 395 396返回接口结果： 397 398AV_ERR_OK：执行成功。 399 400AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 401 402AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 403 404AV_ERR_UNKNOWN：未知错误。 405 406AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 407 408AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 409 410 411### OH_VideoDecoder_RegisterCallback() 412 413``` 414OH_AVErrCode OH_VideoDecoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 415``` 416**描述** 417注册异步回调函数，让应用可以响应视频解码器生成的事件。在调用OH_VideoDecoder_Prepare接口之前，必须调用此接口。 418 419**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 420 421**起始版本：** 11 422 423**参数:** 424 425| 名称 | 描述 | 426| -------- | -------- | 427| codec | 指向视频解码器实例的指针。 | 428| callback | 所有回调函数的集合，请参见[OH_AVCodecCallback](_o_h___a_v_codec_callback.md)。 | 429| userData | 调用者执行回调所依赖的数据。 | 430 431**返回：** 432 433返回接口结果： 434 435AV_ERR_OK：执行成功。 436 437AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 438 439AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 440 441AV_ERR_UNKNOWN：未知错误。 442 443AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 444 445AV_ERR_INVALID_STATE：本接口必须在OH_VideoDecoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 446 447 448### OH_VideoDecoder_RenderOutputBuffer() 449 450``` 451OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer (OH_AVCodec *codec, uint32_t index ) 452``` 453**描述** 454将index对应的输出缓冲返回给解码器，缓冲中携带解码输出数据，并通知解码器完成在输出surface上渲染，输出缓冲包含解码数据。 455 456如果之前没有配置输出surface，则调用此接口仅将指定index对应的输出缓冲区返回给解码器。 457 458**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 459 460**起始版本：** 11 461 462**参数:** 463 464| 名称 | 描述 | 465| -------- | -------- | 466| codec | 指向视频解码实例的指针。 | 467| index | 输出buffer对应的索引值。由[OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer)给出。 | 468 469**返回：** 470 471返回接口结果： 472 473AV_ERR_OK：执行成功。 474 475AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 476 477AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 478 479AV_ERR_UNKNOWN：未知错误。 480 481AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 482 483AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 484 485 486### OH_VideoDecoder_RenderOutputBufferAtTime() 487 488``` 489OH_AVErrCode OH_VideoDecoder_RenderOutputBufferAtTime(OH_AVCodec *codec, uint32_t index, int64_t renderTimestampNs); 490``` 491**描述** 492将index对应的输出缓冲返回给解码器，缓冲中携带解码输出数据，并通知解码器在调用者指定的时间内完成在输出surface上渲染，输出缓冲包含解码数据。 493如果之前没有配置输出surface，则调用此接口仅将指定index对应的输出缓冲区返回给解码器。 494 495调用者可以使用时间戳在特定时间（在VSYNC或者缓冲区时间戳之后）渲染缓冲区。若要在指定的时间戳显示，时间戳需要合理接近系统时间，有几点需要注意： 4961. 缓冲区是按照顺序处理的，因此可能会阻塞后续缓冲区在surface上的显示，如果想要对用户的一些行为做出反应，例如停止或者快进快退视频，这一点很重要。 4972. 如果多个缓冲区被发送到surface要在同一个VSYNC上渲染，那么最后一个将会被显示，其他的将被丢弃。 4983. 如果时间戳与当前的系统时间不是“合理接近”，surface将会忽略时间戳，并在可行的最早时间里显示buffer。在此模式下不会丢弃帧。 499 500**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 501 502**起始版本：** 12 503 504**参数:** 505 506| 名称 | 描述 | 507| -------- | -------- | 508| codec | 指向视频解码实例的指针。 | 509| index | 输出buffer对应的索引值。 由[OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer)给出。 | 510| renderTimestampNs | 输出buffer被发送到surface的时间戳，取值范围大于0，应由std::chrono::steady_clock标准库时钟生成，且单位为纳秒。 | 511 512**返回：** 513 514返回接口结果： 515 516AV_ERR_OK：执行成功。 517 518AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 519 520AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 521 522AV_ERR_UNKNOWN：未知错误。 523 524AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 525 526AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 527 528 529### OH_VideoDecoder_Reset() 530 531``` 532OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec *codec) 533``` 534**描述** 535重置解码器，解码器回到初始化状态。如果要继续解码，需要再次调用OH_VideoDecoder_Configure接口配置解码器实例。 536 537**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 538 539**起始版本：** 9 540 541**参数:** 542 543| 名称 | 描述 | 544| -------- | -------- | 545| codec | 指向视频解码实例的指针。 | 546 547**返回：** 548 549返回接口结果： 550 551AV_ERR_OK：执行成功。 552 553AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 554 555AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 556 557AV_ERR_UNKNOWN：未知错误。 558 559AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 560 561 562### OH_VideoDecoder_SetDecryptionConfig() 563 564``` 565OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig (OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureVideoPath) 566``` 567**描述** 568设置解密配置。在调用OH_VideoDecoder_Prepare接口之前，可选择调用此接口。 569 570**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 571 572**起始版本：** 11 573 574**参数:** 575 576| 名称 | 描述 | 577| -------- | -------- | 578| codec | 指向视频解码实例的指针。 | 579| mediaKeySession | 指向带有解密功能的DRM会话实例的指针，请参阅**MediaKeySession**。 | 580| secureVideoPath | 安全视频通路。指定安全视频通路为true，非安全视频通路为false。在[Surface模式](../../media/avcodec/video-decoding.md#surface模式)下，既支持安全视频通路，也支持非安全视频通路。在[Buffer模式](../../media/avcodec/video-decoding.md#buffer模式)下，仅支持非安全视频通路。 | 581 582**返回：** 583 584返回接口结果： 585 586AV_ERR_OK：操作成功。 587 588AV_ERR_OPERATE_NOT_PERMIT： 589 590 1. 内部执行错误； 591 2. 解码服务进程异常； 592 3. 媒体密钥会话服务处于错误状态。 593 594AV_ERR_INVALID_VAL： 595 596 1. 输入的codec指针为非解码器实例或为空指针； 597 2. mediaKeySession为nullptr或无效。 598 599AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 600 601 602### OH_VideoDecoder_SetParameter() 603 604``` 605OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 606``` 607**描述** 608设置解码器的动态参数。 609 610注意，该接口只能在解码器启动后调用。同时，参数配置错误可能会导致解码失败。 611 612**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 613 614**起始版本：** 9 615 616**参数:** 617 618| 名称 | 描述 | 619| -------- | -------- | 620| codec | 指向视频解码实例的指针。 | 621| format | 指向OH_AVFormat实例的指针。 | 622 623**返回：** 624 625返回接口结果： 626 627AV_ERR_OK：执行成功。 628 629AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 630 631AV_ERR_INVALID_VAL： 632 633 1. 输入的codec指针为非解码器实例，或者为空指针； 634 2. 输入format参数不支持。 635 636AV_ERR_UNKNOWN：未知错误。 637 638AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 639 640AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 641 642 643### OH_VideoDecoder_SetSurface() 644 645``` 646OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec * codec, OHNativeWindow * window ) 647``` 648**描述** 649 650设置输出surface以提供视频解码输出。 651 652在初始化阶段，必须在调用OH_VideoDecoder_Prepare接口之前调用此接口。在Executing状态可以直接调用该接口。 653 654 655**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 656 657**起始版本：** 9 658 659**参数:** 660 661| 名称 | 描述 | 662| -------- | -------- | 663| codec | 指向视频解码实例的指针。 | 664| window | 指向OHNativeWindow实例的指针，请参阅[OHNativeWindow](_codec_base.md#ohnativewindow)。 | 665 666**返回：** 667 668返回接口结果： 669 670AV_ERR_OK：执行成功。 671 672AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 673 674AV_ERR_OPERATE_NOT_PERMIT：本接口仅支持在Surface模式下调用, 如果在Buffer模式调用, 则返回此错误码。 675 676AV_ERR_INVALID_VAL： 677 678 1. 输入的codec指针为非解码器实例，或者为空指针； 679 2. window为空指针。 680 681AV_ERR_UNKNOWN：未知错误。 682 683AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 684 685 686### OH_VideoDecoder_Start() 687 688``` 689OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec *codec) 690``` 691**描述** 692调用OH_VideoDecoder_Prepare接口成功后调用此接口启动解码器。成功启动后，解码器将开始报告注册的回调事件。 693 694**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 695 696**起始版本：** 9 697 698**参数:** 699 700| 名称 | 描述 | 701| -------- | -------- | 702| codec | 指向视频解码实例的指针。 | 703 704**返回：** 705 706返回接口结果： 707 708AV_ERR_OK：执行成功。 709 710AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 711 712AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 713 714AV_ERR_UNKNOWN：未知错误。 715 716AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 717 718AV_ERR_OPERATE_NOT_PERMIT： 719 720 1. 内部执行错误； 721 2. 视频色彩空间转换功能已配置，但是没有调用OH_VideoDecoder_Prepare接口。 722 723 724### OH_VideoDecoder_Stop() 725 726``` 727OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec *codec) 728``` 729**描述** 730 731停止解码器，释放输入输出buffer。停止后，可以通过调用OH_VideoDecoder_Start接口重新进入Running状态。 732 733需要注意的是，如果编解码器特定数据以前已输入到解码器，则需要再次输入。 734 735**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 736 737**起始版本：** 9 738 739**参数:** 740 741| 名称 | 描述 | 742| -------- | -------- | 743| codec | 指向视频解码实例的指针。 | 744 745**返回：** 746 747返回接口结果： 748 749AV_ERR_OK：执行成功。 750 751AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 752 753AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 754 755AV_ERR_UNKNOWN：未知错误。 756 757AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 758 759AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 760 761 762## 废弃函数说明 763 764 765### OH_VideoDecoder_SetCallback() 766 767``` 768OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 769``` 770**描述** 771设置异步回调函数，让应用可以响应视频解码器生成的事件。在调用OH_VideoDecoder_Prepare接口之前，必须调用此接口。 772 773**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 774 775**起始版本：** 9 776 777**废弃版本：** 11 778 779**替代接口：**[OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) 780 781**参数:** 782 783| 名称 | 描述 | 784| -------- | -------- | 785| codec | 指向视频解码实例的指针。 | 786| callback | 所有回调函数的集合，请参阅[OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md)。 | 787| userData | 调用者执行回调所依赖的数据。 | 788 789**返回：** 790 791返回接口结果： 792 793AV_ERR_OK：执行成功。 794 795AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 796 797AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 798 799AV_ERR_UNKNOWN：未知错误。 800 801AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 802 803AV_ERR_INVALID_STATE：本接口必须在OH_VideoDecoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 804 805 806### OH_VideoDecoder_RenderOutputData() 807 808``` 809OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec *codec, uint32_t index ) 810``` 811**描述** 812将处理后的输出buffer返回给解码器，并通知解码器完成在输出surface上渲染Buffer中包含的解码数据。 813 814如果之前没有配置输出surface，则调用此接口仅将指定index对应的输出缓冲区返回给解码器。 815 816**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 817 818**起始版本：** 9 819 820**废弃版本：** 11 821 822**替代接口：**[OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) 823 824**参数:** 825 826| 名称 | 描述 | 827| -------- | -------- | 828| codec | 指向视频解码实例的指针。 | 829| index | 输出buffer对应的索引值。由[OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata)给出。 | 830 831**返回：** 832 833返回接口结果： 834 835AV_ERR_OK：执行成功。 836 837AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 838 839AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 840 841AV_ERR_UNKNOWN：未知错误。 842 843AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 844 845AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 846 847 848### OH_VideoDecoder_PushInputData() 849 850``` 851OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 852``` 853**描述** 854将填充数据的输入缓冲区提交给视频解码器。 855 856输入回调将报告可用的输入缓冲区和相应的index值，请参阅[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)。 一旦具有指定index的缓冲区提交到视频解码器，则无法再次访问缓冲区，直到再次收到输入回调，报告具有相同index的缓冲区可用。 857 858此外，对于某些解码器，需要在开始时向解码器输入编解码特定数据，以初始化解码器的解码过程，如H264格式的PPS/SPS数据。 859 860**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 861 862**起始版本：** 9 863 864**废弃版本：** 11 865 866**替代接口：**[OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) 867 868**参数:** 869 870| 名称 | 描述 | 871| -------- | -------- | 872| codec | 指向视频解码实例的指针。 | 873| index | 输入buffer对应的索引值。由[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)给出。 | 874| attr | 描述缓冲区中包含的数据的信息。 | 875 876**返回：** 877 878返回接口结果： 879 880AV_ERR_OK：执行成功。 881 882AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 883 884AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 885 886AV_ERR_UNKNOWN：未知错误。 887 888AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 889 890AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 891 892 893### OH_VideoDecoder_FreeOutputData() 894 895``` 896OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 897``` 898**描述** 899将处理后的输出缓冲区返回到解码器。 900 901**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 902 903**起始版本：** 9 904 905**废弃版本：** 11 906 907**替代接口：**[OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) 908 909**参数:** 910 911| 名称 | 描述 | 912| -------- | -------- | 913| codec | 指向视频解码实例的指针。 | 914| index | 输出buffer对应的索引值。由[OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata)给出。 | 915 916**返回：** 917 918返回接口结果： 919 920AV_ERR_OK：执行成功。 921 922AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 923 924AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 925 926AV_ERR_UNKNOWN：未知错误。 927 928AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 929 930AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 931
