From 0f8aeda99d4400c691a70c14c9628ae1ca893c8c Mon Sep 17 00:00:00 2001 From: "timkingh.huang" Date: Wed, 8 Nov 2017 18:01:08 +0800 Subject: [PATCH] [comment]: add comments in the format of Doxygen Change-Id: I1df49ed78b5b5cf88ff253c35c59cb0b061b4ea9 Signed-off-by: timkingh.huang --- inc/mpp_task.h | 2 +- inc/rk_mpi.h | 197 +++++++++++++++++++++++++++++++--------------- inc/rk_type.h | 3 + inc/rk_venc_cmd.h | 13 ++- 4 files changed, 146 insertions(+), 69 deletions(-) diff --git a/inc/mpp_task.h b/inc/mpp_task.h index c91899eb..d526e3a0 100644 --- a/inc/mpp_task.h +++ b/inc/mpp_task.h @@ -94,7 +94,7 @@ typedef enum { } MppTaskWorkMode; /* - * Mpp port pull type + * Mpp port poll type * * MPP_POLL_BLOCK - for block poll * MPP_POLL_NON_BLOCK - for non-block poll diff --git a/inc/rk_mpi.h b/inc/rk_mpi.h index 43f6c51e..ba3c67a4 100644 --- a/inc/rk_mpi.h +++ b/inc/rk_mpi.h @@ -19,9 +19,13 @@ /** * @addtogroup rk_mpi - * @brief rockchip media process interface - * - * Mpp provides application programming interface for the application layer. + * @brief Rockchip Media Process Interface + * @details Media Process Platform(MPP) provides application programming + * interface for the application layer, by which applications can + * call hardware encode and decode. Current MPP fully supports + * chipset RK3288/RK3228/RK3229/RK3399/RK3328/RV1108. Old chipset + * like RK29xx/RK30xx/RK31XX/RK3368 is partly supported due to lack + * of some hardware register generation module. */ #include "rk_mpi_cmd.h" @@ -29,116 +33,155 @@ /** * @ingroup rk_mpi - * @brief mpp main work function set + * @brief MPP main work function set + * @details all api function are seperated into two sets: data io api set + * and control api set * - * @note all api function are seperated into two sets: data io api set and control api set + * (1). the data api set is for data input/output flow including: * - * the data api set is for data input/output flow including: - * - * simple data api set: + * (1.1) simple data api set: * * decode : both send video stream packet to decoder and get video frame from * decoder at the same time. + * * encode : both send video frame to encoder and get encoded video stream from * encoder at the same time. * * decode_put_packet: send video stream packet to decoder only, async interface + * * decode_get_frame : get video frame from decoder only, async interface * * encode_put_frame : send video frame to encoder only, async interface + * * encode_get_packet: get encoded video packet from encoder only, async interface * - * advance task api set: + * (1.2) advanced task api set: * + * poll : poll port for dequeue + * + * dequeue : pop a task from mpp task queue + * + * enqueue : push a task to mpp task queue + * + * (2). the control api set is for mpp context control including: * - * the control api set is for mpp context control including: * control : similiar to ioctl in kernel driver, setup or get mpp internal parameter - * reset : clear all data in mpp context, reset to initialized status - * the simple api set is for simple codec usage including: * - * - * reset : discard all packet and frame, reset all component, - * for both decoder and encoder - * control : control function for mpp property setting + * reset : clear all data in mpp context, discard all packet and frame, + * reset all components to initialized status */ typedef struct MppApi_t { + /** + * @brief size of struct MppApi + */ RK_U32 size; + /** + * @brief mpp api version, generated by Git + */ RK_U32 version; // simple data flow interface /** * @brief both send video stream packet to decoder and get video frame from * decoder at the same time - * @param ctx The context of mpp - * @param packet[in] The input video stream - * @param frame[out] The output picture - * @return 0 for decode success, others for failure + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[in] packet The input video stream, its usage can refer mpp_packet.h. + * @param[out] frame The output picture, its usage can refer mpp_frame.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*decode)(MppCtx ctx, MppPacket packet, MppFrame *frame); /** * @brief send video stream packet to decoder only, async interface - * @param ctx The context of mpp - * @param packet The input video stream - * @return 0 for success, others for failure + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[in] packet The input video stream, its usage can refer mpp_packet.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*decode_put_packet)(MppCtx ctx, MppPacket packet); /** * @brief get video frame from decoder only, async interface - * @param ctx The context of mpp - * @param frame The output picture - * @return 0 for success, others for failure + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[out] frame The output picture, its usage can refer mpp_frame.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*decode_get_frame)(MppCtx ctx, MppFrame *frame); /** * @brief both send video frame to encoder and get encoded video stream from * encoder at the same time - * @param ctx The context of mpp - * @param frame[in] The input video data - * @param packet[out] The output compressed data - * @return 0 for encode success, others for failure + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[in] frame The input video data, its usage can refer mpp_frame.h. + * @param[out] packet The output compressed data, its usage can refer mpp_packet.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*encode)(MppCtx ctx, MppFrame frame, MppPacket *packet); /** * @brief send video frame to encoder only, async interface - * @param ctx The context of mpp - * @param frame The input video data - * @return 0 for success, others for failure + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[in] frame The input video data, its usage can refer mpp_frame.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*encode_put_frame)(MppCtx ctx, MppFrame frame); /** * @brief get encoded video packet from encoder only, async interface - * @param ctx The context of mpp - * @param packet The output compressed data - * @return 0 for success, others for failure + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[out] packet The output compressed data, its usage can refer mpp_packet.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*encode_get_packet)(MppCtx ctx, MppPacket *packet); + /** + * @brief ISP interface, will be supported in the future. + */ MPP_RET (*isp)(MppCtx ctx, MppFrame dst, MppFrame src); + /** + * @brief ISP interface, will be supported in the future. + */ MPP_RET (*isp_put_frame)(MppCtx ctx, MppFrame frame); + /** + * @brief ISP interface, will be supported in the future. + */ MPP_RET (*isp_get_frame)(MppCtx ctx, MppFrame *frame); // advance data flow interface /** * @brief poll port for dequeue - * @param ctx The context of mpp - * @param type input port or output port which are both for data transaction - * @return 0 for success there is valid task for dequeue, others for failure + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[in] type input port or output port which are both for data transaction + * @param[in] timeout mpp poll type, its usage can refer mpp_task.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*poll)(MppCtx ctx, MppPortType type, MppPollType timeout); /** - * @brief dequeue MppTask - * @param ctx The context of mpp - * @param type input port or output port which are both for data transaction - * @param task MppTask which is sent to mpp for process - * @return 0 for success, others for failure + * @brief dequeue MppTask, pop a task from mpp task queue + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[in] type input port or output port which are both for data transaction + * @param[out] task MppTask popped from mpp task queue, its usage can refer mpp_task.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*dequeue)(MppCtx ctx, MppPortType type, MppTask *task); /** - * @brief enqueue MppTask - * @param ctx The context of mpp - * @param type input port or output port which are both for data transaction - * @param task MppTask which is sent to mpp for process - * @return 0 for success, others for failure + * @brief enqueue MppTask, push a task to mpp task queue + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[in] type input port or output port which are both for data transaction + * @param[in] task MppTask which is sent to mpp for process, its usage can refer mpp_task.h. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*enqueue)(MppCtx ctx, MppPortType type, MppTask task); @@ -146,20 +189,25 @@ typedef struct MppApi_t { /** * @brief discard all packet and frame, reset all component, * for both decoder and encoder - * @param ctx The context of mpp + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*reset)(MppCtx ctx); /** * @brief control function for mpp property setting - * @param ctx The context of mpp - * @param cmd The mpi command - * @param param The mpi command parameter - * @return 0 for success, others for failure + * @param[in] ctx The context of mpp, created by mpp_create() and initiated + * by mpp_init(). + * @param[in] cmd The mpi command, its definition can refer rk_mpi_cmd.h. + * @param[in,out] param The mpi command parameter + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET (*control)(MppCtx ctx, MpiCmd cmd, MppParam param); /** - * @brief The reserved segment + * @brief The reserved segment, may be used in the future */ RK_U32 reserv[16]; } MppApi; @@ -173,28 +221,49 @@ extern "C" { * @ingroup rk_mpi * @brief Create empty context structure and mpi function pointers. * Use functions in MppApi to access mpp services. - * @param ctx pointer of the mpp context - * @param mpi pointer of mpi function + * @param[in,out] ctx pointer of the mpp context, refer to MpiImpl_t. + * @param[in,out] mpi pointer of mpi function, refer to MppApi. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. + * @note This interface creates base flow context, all function calls + * are based on it. */ MPP_RET mpp_create(MppCtx *ctx, MppApi **mpi); /** * @ingroup rk_mpi * @brief Call after mpp_create to setup mpp type and video format. * This function will call internal context init function. - * @param ctx The context of mpp - * @param type MppCtxType, decoder or encoder - * @param coding video compression coding + * @param[in] ctx The context of mpp, created by mpp_create(). + * @param[in] type specify decoder or encoder, refer to MppCtxType. + * @param[in] coding specify video compression coding, refer to MppCodingType. + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET mpp_init(MppCtx ctx, MppCtxType type, MppCodingType coding); /** * @ingroup rk_mpi - * @brief Destroy mpp context and free both context and mpi structure - * @param ctx The context of mpp + * @brief Destroy mpp context and free both context and mpi structure, + * it matches with mpp_init(). + * @param[in] ctx The context of mpp, created by mpp_create(). + * @return 0 for success, others for failure. The return value is an + * error code. For details, please refer mpp_err.h. */ MPP_RET mpp_destroy(MppCtx ctx); - -// coding type format function +/** + * @ingroup rk_mpi + * @brief judge given format is supported or not by MPP. + * @param[in] type specify decoder or encoder, refer to MppCtxType. + * @param[in] coding specify video compression coding, refer to MppCodingType. + * @return 0 for support, -1 for unsupported. + */ MPP_RET mpp_check_support_format(MppCtxType type, MppCodingType coding); +/** + * @ingroup rk_mpi + * @brief List all formats supported by MPP + * @param NULL no need to input parameter + * @return No return value. This function just prints format information supported + * by MPP on standard output. + */ void mpp_show_support_format(void); void mpp_show_color_format(void); diff --git a/inc/rk_type.h b/inc/rk_type.h index 6d131d08..61d342ec 100644 --- a/inc/rk_type.h +++ b/inc/rk_type.h @@ -57,6 +57,9 @@ typedef signed long long int RK_S64; /** * @ingroup rk_mpi * @brief The type of mpp context + * @details This type is used when calling mpp_init(), which including decoder, + * encoder and Image Signal Process(ISP). So far decoder and encoder + * are supported perfectly, and ISP will be supported in the future. */ typedef enum { MPP_CTX_DEC, /**< decoder */ diff --git a/inc/rk_venc_cmd.h b/inc/rk_venc_cmd.h index b4ad93ee..4918037d 100644 --- a/inc/rk_venc_cmd.h +++ b/inc/rk_venc_cmd.h @@ -926,10 +926,15 @@ typedef struct MppEncVp8Cfg_t { RK_S32 qp_max_step; } MppEncVp8Cfg; -/* - * in decoder mode application need to specify the coding type first - * send a stream header to mpi ctx using parameter data / size - * and decoder will try to decode the input stream. +/** + * @ingroup rk_mpi + * @brief MPP encoder codec configuration parameters + * @details The encoder codec configuration parameters are different for each + * compression codings. For example, H.264 encoder can configure + * profile, level, qp, etc. while jpeg encoder can configure qp + * only. The detailed parameters can refer the corresponding data + * structure such as MppEncH264Cfg and MppEncJpegCfg. This data + * structure is associated with MPP_ENC_SET_CODEC_CFG command. */ typedef struct MppEncCodecCfg_t { MppCodingType coding;