1 /* 2 * Copyright (c) 2020-2021 Huawei Device 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 /** 17 * @addtogroup Codec 18 * @{ 19 * 20 * @brief Defines codec-related APIs 21 * 22 * including custom data types and functions for initializing audio and video codecs, 23 * setting parameters, and controlling and transferring data. 24 * 25 * @since 1.0 26 * @version 1.0 27 */ 28 29 /** 30 * @file codec_type.h 31 * 32 * @brief Declares custom data types used in API declarations for the Codec module, 33 * including the codec types, audio and video parameters, input and output data, and callbacks. 34 * 35 * @since 1.0 36 * @version 1.0 37 */ 38 39 #ifndef CODEC_TYPE_H 40 #define CODEC_TYPE_H 41 42 #include <stdint.h> 43 #include <stdbool.h> 44 #include "codec_common_type.h" 45 #include "display_type.h" 46 47 #ifdef __cplusplus 48 #if __cplusplus 49 extern "C" { 50 #endif 51 #endif /* __cplusplus */ 52 53 /** 54 * @brief Defines the pointer to the codec handle, which is the context information for function calls. 55 */ 56 typedef void *CODEC_HANDLETYPE; 57 58 #define PARAM_COUNT_MAX 500 59 60 /** 61 * @brief Enumerates indexes of parameter types. 62 */ 63 typedef enum { 64 KEY_CODEC_START_NONE = 0, 65 KEY_MIMETYPE, /**< MIME type. For the value type, see {@link AvCodecMime}. */ 66 KEY_BUFFERSIZE, /**< Buffer size. The value type is uint32_t. */ 67 KEY_CODEC_TYPE, /**< Codec type. For the value type, see {@link CodecType}. */ 68 KEY_INIT_PARAM_KEYS, /**< Get the minimum initialization param keys, see {@link ParamKey}(read only). */ 69 KEY_INPUT_BUFFERS, /**< External input buffer in preset mode, see {@link CodecBufferInfo}. */ 70 KEY_OUTPUT_BUFFERS, /**< External output buffer in preset mode, see {@link CodecBufferInfo}. */ 71 KEY_DEVICE_ID, /**< Device ID. The value type is uint32_t. */ 72 KEY_INPUT_BUFFER_COUNT, /**< Input Buffer count. The value type is uint32_t. */ 73 KEY_OUTPUT_BUFFER_COUNT, /**< Output Buffer count. The value type is uint32_t. */ 74 KEY_BITRATE = 0x500, /**< Bit rate. The value type is uint32_t. */ 75 76 KEY_VIDEO_START_NONE = 0x1000, 77 KEY_VIDEO_WIDTH, /**< Width. The value type is uint32_t. */ 78 KEY_VIDEO_HEIGHT, /**< Hight. The value type is uint32_t. */ 79 KEY_VIDEO_STRIDE, /**< Stride. The value type is uint32_t. */ 80 KEY_VIDEO_FIELD, /**< Video field. For the value type, see {@link VideoField}. */ 81 KEY_PIXEL_FORMAT, /**< Pixel format. For the value type, see {@link CodecPixelFormat}. */ 82 KEY_VIDEO_RC_MODE, /**< Rate control mode. For the value type, see {@link VideoCodecRcMode}. */ 83 KEY_VIDEO_GOP_MODE, /**< GOP mode. For the value type, see {@link VideoCodecGopMode}. */ 84 KEY_VIDEO_PIC_SIZE, /**< Image resolution. */ 85 KEY_VIDEO_PROFILE, /**< Codec profile. The value type is uint32_t. */ 86 KEY_VIDEO_FRAME_RATE, /**< Frame rate. The value type is uint32_t. */ 87 KEY_IMAGE_Q_FACTOR, /**< Quality factor, range is [1, 99]. The value type is uint32_t */ 88 KEY_VIDEO_LEVEL, /**< Codec level. The value type is uint32_t. */ 89 90 KEY_AUDIO_START_NONE = 0x1500, 91 KEY_AUDIO_SAMPLE_RATE, /**< Sampling rate. The value type is uint32_t. */ 92 KEY_AUDIO_PROFILE, /**< Audio encoding profile. The value type is uint32_t. */ 93 KEY_AUDIO_CHANNEL_COUNT, /**< Number of channels. The value type is uint32_t. */ 94 KEY_AUDIO_SOUND_MODE, /**< Audio channel mode. For the value type, see {@link AudioSoundMode}. */ 95 KEY_AUDIO_POINTS_PER_FRAME, /**< Number of sampling points per frame. The value type is uint32_t. */ 96 KEY_AUDIO_SAMPLE_FORMAT, /**< Audio sample format. For the value type, see {@link CodecAudioSampleFormat}. */ 97 98 KEY_VENDOR_START_NONE = 0x60000000, 99 100 KEY_PARAM_MAX = 0x7FFFFFFF 101 } ParamKey; 102 103 /** 104 * @brief Enumerates control modes of the channel encoding rate. 105 */ 106 typedef enum { 107 VID_CODEC_RC_CBR = 0, /**< Fixed bit rate*/ 108 VID_CODEC_RC_VBR, /**< Variable bit rate */ 109 VID_CODEC_RC_AVBR, /**< Adaptive variable bit rate */ 110 VID_CODEC_RC_QVBR, /**< Quality-defined variable bit rate */ 111 VID_CODEC_RC_CVBR, /**< Constrained variable bit rate */ 112 VID_CODEC_RC_QPMAP, /**< Configuration-mapped quantization parameters */ 113 VID_CODEC_RC_FIXQP /**< Fixed quantization parameters */ 114 } VideoCodecRcMode; 115 116 /** 117 * @brief Enumerates types of group of pictures (GOP). 118 */ 119 typedef enum { 120 VID_CODEC_GOPMODE_NORMALP = 0, /**< P-frames using only one reference frame during encoding */ 121 VID_CODEC_GOPMODE_DUALP = 1, /**< P-frames using two reference frames during encoding */ 122 VID_CODEC_GOPMODE_SMARTP = 2, /**< Smart P-frames for encoding */ 123 VID_CODEC_GOPMODE_ADVSMARTP = 3, /**< Advanced smart P-frames for encoding */ 124 VID_CODEC_GOPMODE_BIPREDB = 4, /**< B-frames for encoding */ 125 VID_CODEC_GOPMODE_LOWDELAYB = 5, /**< B-frames using only previous frames as references during encoding. */ 126 VID_CODEC_GOPMODE_INVALID, /**< Invalid type */ 127 } VideoCodecGopMode; 128 129 /** 130 * @brief Describes the dynamic parameter structure, which is mainly used 131 * by {@link CodecCreate} and {@link CodecSetParameter}. 132 */ 133 typedef struct { 134 ParamKey key; /**< Parameter type index */ 135 void *val; /**< Pointer to the parameter value */ 136 int size; /**< Parameter value size */ 137 } Param; 138 139 /** 140 * @brief Enumerates video frame fields. 141 */ 142 typedef enum { 143 VID_FIELD_TOP = 0x1, /**< Top fields on even-number lines */ 144 VID_FIELD_BOTTOM = 0x2, /**< Bottom fields on odd-number lines */ 145 VID_FIELD_INTERLACED = 0x3, /**< Interlaced fields */ 146 VID_FIELD_FRAME = 0x4, /**< Non-interlaced frames */ 147 VID_FIELD_INVALID /**< Invalid fields */ 148 } VideoField; 149 150 /** 151 * @brief Enumerates pixel formats. 152 */ 153 typedef enum { 154 PIXEL_FORMAT_NONE, 155 PIXEL_FORMAT_YUV_422_I, /**< YUV422 interleaved format */ 156 PIXEL_FORMAT_YCBCR_422_SP, /**< YCBCR422 semi-planar format */ 157 PIXEL_FORMAT_YCRCB_422_SP, /**< YCRCB422 semi-planar format */ 158 PIXEL_FORMAT_YCBCR_420_SP, /**< YCBCR420 semi-planar format */ 159 PIXEL_FORMAT_YCRCB_420_SP, /**< YCRCB420 semi-planar format */ 160 PIXEL_FORMAT_YCBCR_422_P, /**< YCBCR422 planar format */ 161 PIXEL_FORMAT_YCRCB_422_P, /**< YCRCB422 planar format */ 162 PIXEL_FORMAT_YCBCR_420_P, /**< YCBCR420 planar format */ 163 PIXEL_FORMAT_YCRCB_420_P, /**< YCRCB420 planar format */ 164 PIXEL_FORMAT_YUYV_422_PKG, /**< YUYV422 packed format */ 165 PIXEL_FORMAT_UYVY_422_PKG, /**< UYVY422 packed format */ 166 PIXEL_FORMAT_YVYU_422_PKG, /**< YVYU422 packed format */ 167 PIXEL_FORMAT_VYUY_422_PKG, /**< VYUY422 packed format */ 168 169 PIXEL_FORMAT_VENDOR_MASK = 0x7F000000, /**< Reserved region for introducting Vendor Extensions, eg. 170 PIX_FORMAT_VENDOR_MASK | PIXEL_FORMAT_YCBCR_420_SP. */ 171 PIXEL_FORMAT_MAX = 0x7FFFFFFF, /**< Invalid format */ 172 } CodecPixelFormat; 173 174 /** 175 * @brief Enumerates audio channel modes. 176 */ 177 typedef enum { 178 AUD_CHANNEL_FRONT_LEFT = 0x1, /**< Front left channel */ 179 AUD_CHANNEL_FRONT_RIGHT = 0x2, /**< Front right channel */ 180 181 AUD_SOUND_MODE_INVALID = 0x0, /**< Invalid mode */ 182 AUD_SOUND_MODE_MONO = 0x1, /**< Mono channel */ 183 AUD_SOUND_MODE_STEREO = 0x3, /**< Stereo channel, consisting of front left and front right channels */ 184 } AudioSoundMode; 185 186 /** 187 * @brief Enumerates stream flags. 188 */ 189 typedef enum { 190 STREAM_FLAG_KEYFRAME = 0x1, /**< Keyframe */ 191 STREAM_FLAG_CODEC_SPECIFIC_INF = 0x2, /**< Codec specifications */ 192 STREAM_FLAG_EOS = 0x4, /**< End of streams */ 193 STREAM_FLAG_PART_OF_FRAME = 0x8, /**< Partial frame */ 194 STREAM_FLAG_END_OF_FRAME = 0x10, /**< End of frames, used in pair with <b> STREAM_FLAG_PART_OF_FRAME</b> */ 195 STREAM_FLAG_OUTPUT_CHANGED = 0x20, 196 } StreamFlagType; 197 198 /** 199 * @brief Enumerates buffer types. 200 */ 201 typedef enum { 202 BUFFER_TYPE_VIRTUAL = 0, /**< Data described by this buffer */ 203 BUFFER_TYPE_FD, /**< Share mem file descriptor, which can be used cross processes */ 204 BUFFER_TYPE_HANDLE, /**< Video frame buffer handle, For details, see {@link BufferHandle} */ 205 } BufferType; 206 207 /** 208 * @brief Describes buffer information. 209 */ 210 typedef struct { 211 BufferType type; /**< Buffer type */ 212 intptr_t buf; /**< A reference to a data buffer */ 213 uint32_t offset; /**< Buffer offset */ 214 uint32_t length; /**< Length of valid data */ 215 uint32_t capacity; /**< Total size of buffer blocks*/ 216 } CodecBufferInfo; 217 218 /** 219 * @brief Describes input and output codec buffer. 220 */ 221 typedef struct { 222 uint32_t bufferId; /**< Corresponding buffer index number */ 223 int64_t timeStamp; /**< buffer timestamp */ 224 uint32_t flag; /**< buffer flag. For details, see {@link StreamFlagType}. */ 225 uint32_t bufferCnt; /**< Number of buffers */ 226 CodecBufferInfo buffer[0]; /**< Pointer to the buffer description. For details, see {@link CodecBufferInfo} */ 227 } CodecBuffer; 228 229 /** 230 * @brief Enumerates MIME types. 231 */ 232 typedef enum { 233 MEDIA_MIMETYPE_IMAGE_JPEG = 0, /**< JPEG image */ 234 MEDIA_MIMETYPE_VIDEO_AVC, /**< H.264 video */ 235 MEDIA_MIMETYPE_VIDEO_HEVC, /**< H.265 video */ 236 MEDIA_MIMETYPE_VIDEO_MPEG4, /**< MPEG4 video */ 237 MEDIA_MIMETYPE_AUDIO_FIRST = 0x10000, /**< Dummy id pointing at the start of audio codecs */ 238 MEDIA_MIMETYPE_AUDIO_AAC = 0x10000, /**< AAC audio */ 239 MEDIA_MIMETYPE_AUDIO_G711A, /**< G711A audio */ 240 MEDIA_MIMETYPE_AUDIO_G711U, /**< G711U audio */ 241 MEDIA_MIMETYPE_AUDIO_G726, /**< G726 audio */ 242 MEDIA_MIMETYPE_AUDIO_PCM, /**< PCM audio */ 243 MEDIA_MIMETYPE_AUDIO_MP3, /**< MP3 audio */ 244 MEDIA_MIMETYPE_INVALID, /**< Invalid MIME type */ 245 } AvCodecMime; 246 247 /** 248 * @brief Enumerates codec levels. 249 */ 250 typedef enum { 251 INVALID_LEVEL = 0, /**< Invalid level */ 252 AVC_LEVEL_1 = 0x1000, /**< H.264 level 1 */ 253 HEVC_LEVEL_MAIN_1 = 0x2000, /**< H.265 Main level 1 */ 254 HEVC_LEVEL_MAIN_2, /**< H.265 Main level 2 */ 255 } Level; 256 257 /** 258 * @brief Enumerates allocation modes of input and output buffers. 259 */ 260 typedef enum { 261 ALLOCATE_INPUT_BUFFER_CODEC_PRESET = 0x0001, /**< Preset input buffer allocated within the Codec module */ 262 ALLOCATE_INPUT_BUFFER_CODEC_DYNAMIC = 0x0002, /**< Dynamic input buffer allocated within the Codec module */ 263 264 ALLOCATE_INPUT_BUFFER_USER_PRESET = 0x0010, /**< Preset input buffer allocated by an external user */ 265 ALLOCATE_INPUT_BUFFER_USER_DYNAMIC = 0x0020, /**< Dynamic input buffer allocated by an external user */ 266 267 ALLOCATE_OUTPUT_BUFFER_CODEC_PRESET = 0x0100, /**< Preset output buffer allocated within the Codec module */ 268 ALLOCATE_OUTPUT_BUFFER_CODEC_DYNAMIC = 0x0200, /**< Dynamic output buffer allocated within the Codec module */ 269 270 ALLOCATE_OUTPUT_BUFFER_USER_PRESET = 0x1000, /**< Preset output buffer allocated by an external user */ 271 ALLOCATE_OUTPUT_BUFFER_USER_DYNAMIC = 0x2000, /**< Dynamic output buffer allocated by an external user */ 272 } AllocateBufferMode; 273 274 /** 275 * @brief Defines the video codec capabilities. 276 */ 277 #define PIX_FMT_NUM 16 /** Size of the supported pixel format array */ 278 typedef struct { 279 Rect minSize; /** Minimum resolution supported. */ 280 Rect maxSize; /** Maximum resolution supported. */ 281 Alignment whAlignment; /** Values to align with the width and height. */ 282 int32_t supportPixFmts[PIX_FMT_NUM]; /** Supported pixel formats, array is terminated by PIXEL_FORMAT_NONE. */ 283 } VideoPortCap; 284 285 /** 286 * @brief Defines the audio codec port capabilities. 287 */ 288 #define SAMPLE_FORMAT_NUM 12 /** Size of the audio sampling format array supported. */ 289 #define SAMPLE_RATE_NUM 16 /** Size of the audio sampling rate array supported. */ 290 #define CHANNEL_NUM 16 /** Size of the audio channel array supported. */ 291 typedef struct { 292 int32_t sampleFormats[SAMPLE_FORMAT_NUM]; /** Supported audio sampling formats. For details, 293 see {@link CodecAudioSampleFormat}. */ 294 int32_t sampleRate[SAMPLE_RATE_NUM]; /** Supported audio sampling rates. For details, 295 see {@link AudioSampleRate}. */ 296 int32_t channelLayouts[CHANNEL_NUM]; /** Supported audio channel layouts. */ 297 } AudioPortCap; 298 299 /** 300 * @brief Defines the codec capability. 301 */ 302 #define PROFILE_NUM 256 /** Size of the profile array supported. */ 303 #define NAME_LENGTH 32 /** Size of the component name. */ 304 typedef struct { 305 AvCodecMime mime; /**< MIME type */ 306 CodecType type; /**< Codec type */ 307 char name[NAME_LENGTH]; /**< Codec name char string */ 308 int32_t supportProfiles[PROFILE_NUM]; /**< Supported profiles. For details, see {@link Profile}. */ 309 bool isSoftwareCodec; /**< Whether it is software codec or hardware codec. */ 310 int32_t processModeMask; /**< Codec processing mode mask. For details, 311 see {@link CodecProcessMode}. */ 312 uint32_t capsMask; /**< Capability mask. For details, see {@link CapsMask}. */ 313 uint32_t allocateMask; /**< Buffer allocation mode. For details, see {@link AllocateBufferMode}. */ 314 RangeValue inputBufferNum; /**< Range number of input buffers required for running */ 315 RangeValue outputBufferNum; /**< Range number of output buffers required for running */ 316 RangeValue bitRate; /** Supported bit rate range. */ 317 int32_t inputBufferSize; /** Min size of external input buffer. */ 318 int32_t outputBufferSize; /** Min size of external output buffer. */ 319 union { 320 VideoPortCap video; /** Video encoding and decoding capabilities */ 321 AudioPortCap audio; /** Audio encoding and decoding capabilities */ 322 } port; 323 } CodecCapability; 324 325 /** 326 * @brief Enumerates input and output types. 327 */ 328 typedef enum { 329 INPUT_TYPE, /**< Input */ 330 OUTPUT_TYPE, /**< Output */ 331 ALL_TYPE, /**< Input and output */ 332 } DirectionType; 333 334 /** 335 * @brief Enumerates event types. 336 */ 337 typedef enum { 338 EVENT_ERROR, /**< Event error */ 339 EVENT_FLUSH_COMPLETE, /**< Buffer flush completed */ 340 EVENT_STOP_COMPLETE, /**< Codec stopped */ 341 EVENT_OUT_FORMAT_CHANGED, /**< Output format changed. For details, see {@link FormatChange}. */ 342 EVENT_START_COMPLETE, /**< Codec started */ 343 EVENT_EOS_COMPLETE, 344 345 EVENT_MAX = 0x7FFFFFFF /**< Maximum event value */ 346 } EventType; 347 348 /** 349 * @brief Defines format change reporting information. 350 */ 351 typedef struct { 352 DirectionType direct; /**< Input or output type. */ 353 RangeValue bufferNum; /**< Range number of output buffers. Report when decode the first frame, 354 or report when the bit stream resolution changed. */ 355 int32_t width; /**< Width. */ 356 int32_t height; /**< Height. */ 357 int32_t widthStride; /**< Image width stride. */ 358 int32_t heightStride; /**< Image height stride. */ 359 PixelFormat format; /**< Pixel format. For details, see {@link PixelFormat}. */ 360 Rect outputRect; 361 } FormatChange; 362 363 /** 364 * @brief Redefines the unsigned pointer type, which is used for pointer conversion. 365 */ 366 typedef uintptr_t UINTPTR; 367 368 /** 369 * @brief Defines callbacks and their parameters. 370 */ 371 typedef struct { 372 /** 373 * @brief Reports an event. 374 * 375 * Reports event errors and output format changes. 376 * 377 * @param userData Indicates upper-layer data, which is generally 378 * an upper-layer instance passed when this callback is set. 379 * @param EVENTTYPE Indicates the event type. 380 * @param length Indicates the length of eventData array. 381 * @param eventData Indicates the pointer to data contained in the reported event. 382 * @return Returns <b>0</b> if the operation is successful; returns a non-zero {@link CodecResult} value otherwise. 383 */ 384 int32_t (*OnEvent)(UINTPTR userData, EventType event, uint32_t length, int32_t eventData[]); 385 386 /** 387 * @brief Reports that the input data has been used. 388 * 389 * This callback is invoked in asynchronous mode. 390 * 391 * @param userData Indicates upper-layer data, which is generally 392 * an upper-layer instance passed when this callback is set. 393 * @param inBuf Indicates the pointer to the input data that has been used. 394 * @return Returns <b>0</b> if the operation is successful; returns a non-zero {@link CodecResult} value otherwise. 395 */ 396 int32_t (*InputBufferAvailable)(UINTPTR userData, CodecBuffer *inBuf, int32_t *acquireFd); 397 398 /** 399 * @brief Reports that the output is complete. 400 * 401 * This callback is invoked in asynchronous mode. 402 * 403 * @param userData Indicates upper-layer data, which is generally 404 * an upper-layer instance passed when this callback is registered. 405 * @param pBuffer Indicates the pointer to the output data that has been generated. 406 * @return Returns <b>0</b> if the operation is successful; returns a non-zero {@link CodecResult} value otherwise. 407 */ 408 int32_t (*OutputBufferAvailable)(UINTPTR userData, CodecBuffer *outBuf, int32_t *acquireFd); 409 } CodecCallback; 410 411 /** 412 * @brief Enumerates codec result types. 413 */ 414 typedef enum { 415 CODEC_SUCCESS = 0, /**< Success */ 416 CODEC_RECEIVE_EOS, /**< End of streams */ 417 CODEC_ERR_UNKOWN = (int32_t)0x80001000, /**< Unknown error */ 418 CODEC_ERR_INVALID_NAME = (int32_t)0x80001001, /**< The codec name was not valid */ 419 CODEC_ERR_INVALID_MIME = (int32_t)0x80001002, /**< The codec mime was not valid */ 420 CODEC_ERR_INVALID_PARAM = (int32_t)0x80001003, /**< One or more parameters were not valid */ 421 CODEC_ERR_INVALID_CODEC = (int32_t)0x80001004, /**< The codec handle was not valid */ 422 CODEC_ERR_INVALID_OP = (int32_t)0x80001005, /**< Invalid operation */ 423 CODEC_ERR_UNSUPPORT_PARAM = (int32_t)0x80001006, /**< One or more parameters were not supported */ 424 CODEC_ERR_NOT_INIT = (int32_t)0x80001007, /**< The codec was not initialized */ 425 CODEC_ERR_NOT_READY = (int32_t)0x80001008, /**< The codec was not ready */ 426 CODEC_ERR_NOT_FOUND = (int32_t)0x80001009, /**< The codec was not found */ 427 CODEC_ERR_NO_MEMORY = (int32_t)0x8000100A, /**< The codec memory allocation failed */ 428 CODEC_ERR_TIMEOUT = (int32_t)0x8000100B, /**< There was a timeout that occurred */ 429 CODEC_ERR_INVALID_BUFFER = (int32_t)0x8000100C, /**< The buffer was not valid */ 430 CODEC_ERR_UNDER_FLOW = (int32_t)0x8000100D, /**< The buffer was emptied before the next buffer was ready */ 431 CODEC_ERR_OVER_FLOW = (int32_t)0x8000100E, /**< The buffer was not available when it was needed */ 432 CODEC_ERR_MAX = 0x7FFFFFFF 433 } CodecResult; 434 435 #ifdef __cplusplus 436 #if __cplusplus 437 } 438 #endif 439 #endif /* __cplusplus */ 440 441 #endif /* CODEC_TYPE_H */ 442 /** @} */ 443