* Copyright (C) 2023 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef MEDIA_AVCODEC_VIDEO_DECODER_H
#define MEDIA_AVCODEC_VIDEO_DECODER_H
#include "avcodec_common.h"
#include "avcodec_info.h"
#include "buffer/avsharedmemory.h"
#include "meta/format.h"
#include "surface.h"
#include "drm_i_keysession_service.h"
namespace OHOS {
namespace MediaAVCodec {
class AVCodecVideoDecoder {
public:
virtual ~AVCodecVideoDecoder() = default;
* @brief Configure the decoder. This interface must be called before {@link Prepare} is called.
*
* @param format The format of the input data and the desired format of the output data.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t Configure(const Format &format) = 0;
* @brief Prepare for decoding.
*
* This function must be called after {@link Configure} and before {@link Start}
*
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t Prepare() = 0;
* @brief Start decoding.
*
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t Start() = 0;
* @brief Stop decoding.
*
* This function must be called during running
*
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t Stop() = 0;
* @brief Flush both input and output buffers of the decoder.
*
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t Flush() = 0;
* @brief Restores the decoder to the initial state.
*
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t Reset() = 0;
* @brief Releases decoder resources. All methods are unavailable after calling this.
*
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t Release() = 0;
* @brief Sets the surface on which to render the output of this decoder.
*
* This function must be called before {@link Prepare}
*
* @param index The index of the output buffer.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t SetOutputSurface(sptr<Surface> surface) = 0;
* @brief Submits input buffer to decoder.
*
* This function must be called during running. The {@link AVCodecCallback} callback
* will report the available input buffer and the corresponding index value. Once the buffer with the specified
* index is submitted to the video decoder, the buffer cannot be accessed again until the {@link
* AVCodecCallback} callback is received again reporting that the buffer with the same index is available.
* In addition, for some decoders, it is required to input Codec-Specific-Data to the decoder at the beginning to
* initialize the decoding process of the decoder, such as PPS/SPS data in H264 format.
*
* @param index The index of the input buffer.
* @param info The info of the input buffer. For details, see {@link AVCodecBufferInfo}
* @param flag The flag of the input buffer. For details, see {@link AVCodecBufferFlag}
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t QueueInputBuffer(uint32_t index, AVCodecBufferInfo info, AVCodecBufferFlag flag) = 0;
* @brief Submits input buffer to decoder.
*
* This function must be called during running. The {@link MediaCodecCallback} callback
* will report the available input buffer and the corresponding index value. Once the buffer with the specified
* index is submitted to the video decoder, the buffer cannot be accessed again until the {@link
* MediaCodecCallback} callback is received again reporting that the buffer with the same index is available.
* In addition, for some decoders, it is required to input Codec-Specific-Data to the decoder at the beginning to
* initialize the decoding process of the decoder, such as PPS/SPS data in H264 format.
*
* @param index The index of the input buffer.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 4.1
*/
virtual int32_t QueueInputBuffer(uint32_t index) = 0;
* @brief Gets the format of the output data.
*
* This function must be called after {@link Configure}
*
* @param format
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t GetOutputFormat(Format &format) = 0;
* @brief Returns the output buffer to the decoder.
*
* This function must be called during running, and notify the decoder to finish rendering the
* decoded data contained in the Buffer on the output Surface. If the output surface is not configured before,
* calling this interface only returns the output buffer corresponding to the specified index to the decoder.
*
* @param index The index of the output buffer.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t ReleaseOutputBuffer(uint32_t index, bool render) = 0;
* @brief Return the processed output buffer with render timestamp to the decoder, and notify the decoder to finish
* rendering the decoded data contained in the buffer on the output surface. If the output surface is not
* configured before, calling this interface only returns the output buffer corresponding to the specified index to
* the decoder. The timestamp may have special meaning depending on the destination surface.
*
* This function must be called during running
*
* @param index The index of the output buffer.
* @param renderTimestampNs The timestamp is associated with the output buffer when it is sent to the surface. The
* unit is nanosecond.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 5.0
*/
virtual int32_t RenderOutputBufferAtTime(uint32_t index, int64_t renderTimestampNs) = 0;
* @brief Sets the parameters to the decoder.
*
* This interface can only be called after the decoder is started.
* At the same time, incorrect parameter settings may cause decoding failure.
*
* @param format The parameters.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t SetParameter(const Format &format) = 0;
* @brief Registers a decoder listener.
*
* This function must be called before {@link Configure}
*
* @param callback Indicates the decoder listener to register. For details, see {@link AVCodecCallback}.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t SetCallback(const std::shared_ptr<AVCodecCallback> &callback) = 0;
* @brief Registers a decoder listener.
*
* This function must be called before {@link Configure}
*
* @param callback Indicates the decoder listener to register. For details, see {@link MediaCodecCallback}.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 4.1
*/
virtual int32_t SetCallback(const std::shared_ptr<MediaCodecCallback> &callback) = 0;
* @brief Set media key session which includes a decrypt module and a svp flag for decrypt video.
* @param svp is the flag whether use secure decoder
* @return Returns AV_ERR_OK if the execution is successful,
* otherwise returns a specific error code, refer to {@link OH_AVErrCode}
* @since
*/
virtual int32_t SetDecryptConfig(const sptr<DrmStandard::IMediaKeySessionService> &keySession,
const bool svpFlag)
{
(void)keySession;
(void)svpFlag;
return 0;
}
* @brief Get video Channel Id. All methods are unavailable after calling this.
*
* @param channelId channel id
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t GetChannelId(int32_t &channelId) = 0;
* @brief Sets the lpp mode to the decoder.
*
* @param isLpp lpp mode.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 3.1
* @version 3.1
*/
virtual int32_t SetLowPowerPlayerMode(bool isLpp) = 0;
* @brief Recycle dma memory when decoder user has been frozen
*
* This function must be called before {@link Configure}, only provided for {@link Player}
*
* @param exchangeFlag the flag whether memory should be displaced from RAM to ROM or from ROM to RAM
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 6.0
* @version 6.0
*/
virtual int32_t NotifyMemoryExchange(const bool exchangeFlag)
{
(void)exchangeFlag;
return 0;
}
* @brief Query available input buffer from decoder
*
* This function blocks until an input buffer becomes available or timeout occurs.
*
* @param index [out] Reference to store the index of available input buffer
* @param timeoutUs Timeout duration in microseconds (negative value means infinite wait)
* @return Returns {@link AVCS_ERR_OK} if buffer is available;
* returns error code if timeout or other failures occur.
* @since 6.0
* @version 6.0
*/
virtual int32_t QueryInputBuffer(uint32_t &index, int64_t timeoutUs)
{
(void)index;
(void)timeoutUs;
return 0;
}
* @brief Query available output buffer from decoder
*
* This function blocks until an output buffer with decoded data becomes available or timeout occurs.
*
* @param index [out] Reference to store the index of available output buffer
* @param timeoutUs Timeout duration in microseconds (negative value means infinite wait)
* @return Returns {@link AVCS_ERR_OK} if buffer is available;
* returns error code if timeout or other failures occur.
* @since 6.0
* @version 6.0
*/
virtual int32_t QueryOutputBuffer(uint32_t &index, int64_t timeoutUs)
{
(void)index;
(void)timeoutUs;
return 0;
}
* @brief Get input buffer object by index
*
* Caller should use {@link QueryInputBuffer} to get valid index before calling this function.
*
* @param index Index of the input buffer obtained from {@link QueryInputBuffer}
* @return Shared pointer to {@link AVBuffer} if index is valid;
* returns nullptr if index is invalid or buffer unavailable.
* @since 6.0
* @version 6.0
*/
virtual std::shared_ptr<AVBuffer> GetInputBuffer(uint32_t index)
{
(void)index;
return nullptr;
}
* @brief Get output buffer object by index
*
* Caller should use {@link QueryOutputBuffer} to get valid index before calling this function.
*
* @param index Index of the output buffer obtained from {@link QueryOutputBuffer}
* @return Shared pointer to {@link AVBuffer} containing decoded data if index is valid;
* returns nullptr if index is invalid or buffer unavailable.
* @since 6.0
* @version 6.0
*/
virtual std::shared_ptr<AVBuffer> GetOutputBuffer(uint32_t index)
{
(void)index;
return nullptr;
}
* @brief Gets the description information of the decoder
*
* @param format
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 6.0
* @version 6.0
*/
virtual int32_t GetCodecInfo(Format &format) = 0;
};
class __attribute__((visibility("default"))) VideoDecoderFactory {
public:
#ifdef UNSUPPORT_CODEC
static std::shared_ptr<AVCodecVideoDecoder> CreateByMime(const std::string &mime)
{
(void)mime;
return nullptr;
}
static std::shared_ptr<AVCodecVideoDecoder> CreateByName(const std::string &name)
{
(void)name;
return nullptr;
}
static int32_t CreateByMime(const std::string &mime, Format &format, std::shared_ptr<AVCodecVideoDecoder> &decoder)
{
(void)name;
(void)format;
codec = nullptr;
return codec;
}
static int32_t CreateByName(const std::string &name, Format &format, std::shared_ptr<AVCodecVideoDecoder> &decoder)
{
(void)name;
(void)format;
codec = nullptr;
return codec;
}
#else
* @brief Instantiate the preferred decoder of the given mime type.
*
* @param mime The mime type.
* @return Returns the preferred decoder.
* @since 3.1
* @version 3.1
*/
static std::shared_ptr<AVCodecVideoDecoder> CreateByMime(const std::string &mime);
* @brief Instantiates the designated decoder.
*
* @param name The decoder's name.
* @return Returns the designated decoder.
* @since 3.1
* @version 3.1
*/
static std::shared_ptr<AVCodecVideoDecoder> CreateByName(const std::string &name);
* @brief Instantiate the preferred decoder of the given mime type.
*
* @param mime The mime type.
* @param format Caller info
* @param codec The designated decoder.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 5.0
* @version 5.0
*/
static int32_t CreateByMime(const std::string &mime, Format &format, std::shared_ptr<AVCodecVideoDecoder> &decoder);
* @brief Instantiate the preferred decoder of the given mime type.
*
* @param mime The mime type.
* @param format Caller info
* @param codec The designated decoder.
* @return Returns {@link AVCS_ERR_OK} if success; returns an error code otherwise.
* @since 5.0
* @version 5.0
*/
static int32_t CreateByName(const std::string &name, Format &format, std::shared_ptr<AVCodecVideoDecoder> &decoder);
#endif
private:
VideoDecoderFactory() = default;
~VideoDecoderFactory() = default;
};
}
}
#endif
