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