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