1 /* 2 * Copyright (c) 2021 Rockchip Electronics Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef __RK_MPI_H__ 17 #define __RK_MPI_H__ 18 19 /** 20 * @addtogroup rk_mpi 21 * @brief Rockchip Media Process Interface 22 * @details Media Process Platform(MPP) provides application programming 23 * interface for the application layer, by which applications can 24 * call hardware encode and decode. Current MPP fully supports 25 * chipset RK3288/RK3228/RK3229/RK3399/RK3328/RV1108. Old chipset 26 * like RK29xx/RK30xx/RK31XX/RK3368 is partly supported due to lack 27 * of some hardware register generation module. 28 */ 29 30 #include "rk_mpi_cmd.h" 31 #include "mpp_task.h" 32 33 /** 34 * @ingroup rk_mpi 35 * @brief MPP main work function set 36 * @details all api function are seperated into two sets: data io api set 37 * and control api set 38 * 39 * (1). the data api set is for data input/output flow including: 40 * 41 * (1.1) simple data api set: 42 * 43 * decode : both send video stream packet to decoder and get video frame from 44 * decoder at the same time. 45 * 46 * encode : both send video frame to encoder and get encoded video stream from 47 * encoder at the same time. 48 * 49 * decode_put_packet: send video stream packet to decoder only, async interface 50 * 51 * decode_get_frame : get video frame from decoder only, async interface 52 * 53 * encode_put_frame : send video frame to encoder only, async interface 54 * 55 * encode_get_packet: get encoded video packet from encoder only, async interface 56 * 57 * (1.2) advanced task api set: 58 * 59 * poll : poll port for dequeue 60 * 61 * dequeue : pop a task from mpp task queue 62 * 63 * enqueue : push a task to mpp task queue 64 * 65 * (2). the control api set is for mpp context control including: 66 * 67 * control : similiar to ioctl in kernel driver, setup or get mpp internal parameter 68 * 69 * reset : clear all data in mpp context, discard all packet and frame, 70 * reset all components to initialized status 71 */ 72 typedef struct MppApi_t { 73 /** 74 * @brief size of struct MppApi 75 */ 76 unsigned int size; 77 /** 78 * @brief mpp api version, generated by Git 79 */ 80 unsigned int version; 81 82 // simple data flow interface 83 /** 84 * @brief both send video stream packet to decoder and get video frame from 85 * decoder at the same time 86 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 87 * by mpp_init(). 88 * @param[in] packet The input video stream, its usage can refer mpp_packet.h. 89 * @param[out] frame The output picture, its usage can refer mpp_frame.h. 90 * @return 0 and positive for success, negative for failure. The return 91 * value is an error code. For details, please refer mpp_err.h. 92 */ 93 MPP_RET (*decode)(MppCtx ctx, MppPacket packet, MppFrame *frame); 94 /** 95 * @brief send video stream packet to decoder only, async interface 96 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 97 * by mpp_init(). 98 * @param[in] packet The input video stream, its usage can refer mpp_packet.h. 99 * @return 0 and positive for success, negative for failure. The return 100 * value is an error code. For details, please refer mpp_err.h. 101 */ 102 MPP_RET (*decode_put_packet)(MppCtx ctx, MppPacket packet); 103 /** 104 * @brief get video frame from decoder only, async interface 105 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 106 * by mpp_init(). 107 * @param[out] frame The output picture, its usage can refer mpp_frame.h. 108 * @return 0 and positive for success, negative for failure. The return 109 * value is an error code. For details, please refer mpp_err.h. 110 */ 111 MPP_RET (*decode_get_frame)(MppCtx ctx, MppFrame *frame); 112 /** 113 * @brief both send video frame to encoder and get encoded video stream from 114 * encoder at the same time 115 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 116 * by mpp_init(). 117 * @param[in] frame The input video data, its usage can refer mpp_frame.h. 118 * @param[out] packet The output compressed data, its usage can refer mpp_packet.h. 119 * @return 0 and positive for success, negative for failure. The return 120 * value is an error code. For details, please refer mpp_err.h. 121 */ 122 MPP_RET (*encode)(MppCtx ctx, MppFrame frame, MppPacket *packet); 123 /** 124 * @brief send video frame to encoder only, async interface 125 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 126 * by mpp_init(). 127 * @param[in] frame The input video data, its usage can refer mpp_frame.h. 128 * @return 0 and positive for success, negative for failure. The return 129 * value is an error code. For details, please refer mpp_err.h. 130 */ 131 MPP_RET (*encode_put_frame)(MppCtx ctx, MppFrame frame); 132 /** 133 * @brief get encoded video packet from encoder only, async interface 134 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 135 * by mpp_init(). 136 * @param[out] packet The output compressed data, its usage can refer mpp_packet.h. 137 * @return 0 and positive for success, negative for failure. The return 138 * value is an error code. For details, please refer mpp_err.h. 139 */ 140 MPP_RET (*encode_get_packet)(MppCtx ctx, MppPacket *packet); 141 142 /** 143 * @brief ISP interface, will be supported in the future. 144 */ 145 MPP_RET (*isp)(MppCtx ctx, MppFrame dst, MppFrame src); 146 /** 147 * @brief ISP interface, will be supported in the future. 148 */ 149 MPP_RET (*isp_put_frame)(MppCtx ctx, MppFrame frame); 150 /** 151 * @brief ISP interface, will be supported in the future. 152 */ 153 MPP_RET (*isp_get_frame)(MppCtx ctx, MppFrame *frame); 154 155 // advance data flow interface 156 /** 157 * @brief poll port for dequeue 158 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 159 * by mpp_init(). 160 * @param[in] type input port or output port which are both for data transaction 161 * @param[in] timeout mpp poll type, its usage can refer mpp_task.h. 162 * @return 0 and positive for success, negative for failure. The return 163 * value is an error code. For details, please refer mpp_err.h. 164 */ 165 MPP_RET (*poll)(MppCtx ctx, MppPortType type, MppPollType timeout); 166 /** 167 * @brief dequeue MppTask, pop a task from mpp task queue 168 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 169 * by mpp_init(). 170 * @param[in] type input port or output port which are both for data transaction 171 * @param[out] task MppTask popped from mpp task queue, its usage can refer mpp_task.h. 172 * @return 0 and positive for success, negative for failure. The return 173 * value is an error code. For details, please refer mpp_err.h. 174 */ 175 MPP_RET (*dequeue)(MppCtx ctx, MppPortType type, MppTask *task); 176 /** 177 * @brief enqueue MppTask, push a task to mpp task queue 178 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 179 * by mpp_init(). 180 * @param[in] type input port or output port which are both for data transaction 181 * @param[in] task MppTask which is sent to mpp for process, its usage can refer mpp_task.h. 182 * @return 0 and positive for success, negative for failure. The return 183 * value is an error code. For details, please refer mpp_err.h. 184 */ 185 MPP_RET (*enqueue)(MppCtx ctx, MppPortType type, MppTask task); 186 187 // control interface 188 /** 189 * @brief discard all packet and frame, reset all component, 190 * for both decoder and encoder 191 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 192 * by mpp_init(). 193 * @return 0 for success, others for failure. The return value is an 194 * error code. For details, please refer mpp_err.h. 195 */ 196 MPP_RET (*reset)(MppCtx ctx); 197 /** 198 * @brief control function for mpp property setting 199 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 200 * by mpp_init(). 201 * @param[in] cmd The mpi command, its definition can refer rk_mpi_cmd.h. 202 * @param[in,out] param The mpi command parameter 203 * @return 0 for success, others for failure. The return value is an 204 * error code. For details, please refer mpp_err.h. 205 */ 206 MPP_RET (*control)(MppCtx ctx, MpiCmd cmd, MppParam param); 207 208 /** 209 * @brief The reserved segment, may be used in the future 210 */ 211 unsigned int reserv[16]; 212 } MppApi; 213 214 #ifdef __cplusplus 215 extern "C" { 216 #endif 217 218 /** 219 * @ingroup rk_mpi 220 * @brief Create empty context structure and mpi function pointers. 221 * Use functions in MppApi to access mpp services. 222 * @param[in,out] ctx pointer of the mpp context, refer to MpiImpl_t. 223 * @param[in,out] mpi pointer of mpi function, refer to MppApi. 224 * @return 0 for success, others for failure. The return value is an 225 * error code. For details, please refer mpp_err.h. 226 * @note This interface creates base flow context, all function calls 227 * are based on it. 228 */ 229 MPP_RET mpp_create(MppCtx *ctx, MppApi **mpi); 230 /** 231 * @ingroup rk_mpi 232 * @brief Call after mpp_create to setup mpp type and video format. 233 * This function will call internal context init function. 234 * @param[in] ctx The context of mpp, created by mpp_create(). 235 * @param[in] type specify decoder or encoder, refer to MppCtxType. 236 * @param[in] coding specify video compression coding, refer to MppCodingType. 237 * @return 0 for success, others for failure. The return value is an 238 * error code. For details, please refer mpp_err.h. 239 */ 240 MPP_RET mpp_init(MppCtx ctx, MppCtxType type, MppCodingType coding); 241 /** 242 * @ingroup rk_mpi 243 * @brief Call after mpp_init to start mpp working. 244 * Control SET_CFG can be called both before and after mpp_start. 245 * Before mpp_start is called both global param and dynamic param can be set. 246 * After mpp_start is called only dynamic param can be set. 247 * This funciton purpose is to stop recieving global param and do 248 * preparation for processing data flow. 249 * This function will call internal context start function. 250 * @param[in] ctx The context of mpp, created by mpp_create(). 251 * @return 0 for success, others for failure. The return value is an 252 * error code. For details, please refer mpp_err.h. 253 */ 254 MPP_RET mpp_start(MppCtx ctx); 255 /** 256 * @ingroup rk_mpi 257 * @brief Call before mpp_destroy to stop mpp working. 258 * Control SET_CFG can be called after starting. 259 * Before mpp_stop is called only dynamic param can be set. 260 * After mpp_stop is called both global param and dynamic param can be set. 261 * This funciton purpose is to stop processing data and do preparation 262 * to receive global param. 263 * @param[in] ctx The context of mpp, created by mpp_create(). 264 * @return 0 for success, others for failure. The return value is an 265 * error code. For details, please refer mpp_err.h. 266 */ 267 MPP_RET mpp_stop(MppCtx ctx); 268 /** 269 * @ingroup rk_mpi 270 * @brief Destroy mpp context and free both context and mpi structure, 271 * it matches with mpp_init(). 272 * @param[in] ctx The context of mpp, created by mpp_create(). 273 * @return 0 for success, others for failure. The return value is an 274 * error code. For details, please refer mpp_err.h. 275 */ 276 MPP_RET mpp_destroy(MppCtx ctx); 277 /** 278 * @ingroup rk_mpi 279 * @brief judge given format is supported or not by MPP. 280 * @param[in] type specify decoder or encoder, refer to MppCtxType. 281 * @param[in] coding specify video compression coding, refer to MppCodingType. 282 * @return 0 for support, -1 for unsupported. 283 */ 284 MPP_RET mpp_check_support_format(MppCtxType type, MppCodingType coding); 285 /** 286 * @ingroup rk_mpi 287 * @brief List all formats supported by MPP 288 * @param NULL no need to input parameter 289 * @return No return value. This function just prints format information supported 290 * by MPP on standard output. 291 */ 292 void mpp_show_support_format(void); 293 void mpp_show_color_format(void); 294 295 #ifdef __cplusplus 296 } 297 #endif 298 299 #endif /* __RK_MPI_H__ */