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