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 45 #ifdef __cplusplus 46 #if __cplusplus 47 extern "C" { 48 #endif 49 #endif /* __cplusplus */ 50 51 /** 52 * @brief Defines the pointer to the codec handle, which is the context information for function calls. 53 */ 54 typedef void *CODEC_HANDLETYPE; 55 56 /** 57 * @brief Enumerates codec types. 58 */ 59 typedef enum { 60 VIDEO_DECODER, /**< Video decoding */ 61 VIDEO_ENCODER, /**< Video encoding */ 62 AUDIO_DECODER, /**< Audio decoding */ 63 AUDIO_ENCODER, /**< Audio encoding */ 64 INVALID_TYPE /**< Invalid type */ 65 } CodecType; 66 67 /** 68 * @brief Enumerates indexes of parameter types. 69 */ 70 typedef enum { 71 KEY_MIMETYPE = 0x01, /**< MIME type. For the value type, see {@link AvCodecMime}. */ 72 KEY_BUFFERSIZE, /**< Buffer size. The value type is uint32_t. */ 73 KEY_LEFT_STREAM_FRAMES, /**< Number of frames in the remaining data streams. The value type is uint32_t. */ 74 KEY_CODEC_TYPE, /**< Codec type. For the value type, see {@link CodecType}. */ 75 KEY_DIRECTION_TYPE, /**< Input/Output type. For the value type, see {@link DirectionType}. */ 76 77 KEY_BITRATE = 0x500, /**< Bit rate. The value type is uint32_t. */ 78 KEY_WIDTH = 0x1000, /**< Width. The value type is uint32_t. */ 79 KEY_HEIGHT, /**< Hight. The value type is uint32_t. */ 80 KEY_STRIDE, /**< Stride. The value type is uint32_t. */ 81 KEY_VIDEO_FIELD, /**< Video field. For the value type, see {@link VideoField}. */ 82 KEY_PIXEL_FORMAT, /**< Pixel format. For the value type, see {@link PixelFormat}. */ 83 KEY_VIDEO_RC_MODE, /**< Rate control mode. For the value type, see {@link VenCodeRcMode}. */ 84 KEY_VIDEO_GOP_MODE, /**< GOP mode. For the value type, see {@link VenCodeGopMode}. */ 85 KEY_VIDEO_PIC_SIZE, /**< Image resolution. For the value type, see {@link PicSize}. */ 86 KEY_VIDEO_PROFILE, /**< Codec profile. The value type is uint32_t. */ 87 KEY_VIDEO_FRAME_RATE, /**< Frame rate. The value type is uint32_t. */ 88 KEY_IMAGE_Q_FACTOR, /**< Quality factor, range is [1, 99]. The value type is uint32_t */ 89 90 KEY_SAMPLE_RATE = 0x1500, /**< Sampling rate. The value type is uint32_t. */ 91 KEY_AUDIO_PROFILE, /**< Audio encoding profile. The value type is uint32_t. */ 92 KEY_CHANNEL_COUNT, /**< Number of channels. The value type is uint32_t. */ 93 KEY_BITWITH, /**< Bit width. For the value type, see {@link AudioBitWidth}. */ 94 KEY_SOUND_MODE, /**< Audio channel mode. For the value type, see {@link AudioSoundMode}. */ 95 KEY_POINT_NUM_PER_FRAME, /**< Number of sampling points per frame. The value type is uint32_t. */ 96 KEY_DEVICE_ID, /**< Device ID. The value type is uint32_t. */ 97 } ParamKey; 98 99 /** 100 * @brief Enumerates control modes of the channel encoding rate. 101 */ 102 typedef enum { 103 VENCOD_RC_CBR = 0, /**< Fixed bit rate*/ 104 VENCOD_RC_VBR, /**< Variable bit rate */ 105 VENCOD_RC_AVBR, /**< Adaptive variable bit rate */ 106 VENCOD_RC_QVBR, /**< Quality-defined variable bit rate */ 107 VENCOD_RC_CVBR, /**< Constrained variable bit rate */ 108 VENCOD_RC_QPMAP, /**< Configuration-mapped quantization parameters */ 109 VENCOD_RC_FIXQP /**< Fixed quantization parameters */ 110 } VenCodeRcMode; 111 112 /** 113 * @brief Enumerates resolutions. 114 */ 115 typedef enum { 116 RESOLUTION_CIF, /**< 352x288 */ 117 RESOLUTION_360P, /**< 640x360 */ 118 RESOLUTION_D1_PAL, /**< 720x576 */ 119 RESOLUTION_D1_NTSC, /**< 720x480 */ 120 RESOLUTION_720P, /**< 1280x720 */ 121 RESOLUTION_1080P, /**< 1920x1080 */ 122 RESOLUTION_2560X1440, /**< 2560x1440 */ 123 RESOLUTION_2592X1520, /**< 2592x1520 */ 124 RESOLUTION_2592X1536, /**< 2592x1536 */ 125 RESOLUTION_2592X1944, /**< 2592x1944 */ 126 RESOLUTION_2688X1536, /**< 2688x1536 */ 127 RESOLUTION_2716X1524, /**< 2716x1524 */ 128 RESOLUTION_3840X2160, /**< 3840x2160 */ 129 RESOLUTION_4096X2160, /**< 4096x2160 */ 130 RESOLUTION_3000X3000, /**< 3000x3000 */ 131 RESOLUTION_4000X3000, /**< 4000x3000 */ 132 RESOLUTION_7680X4320, /**< 7680x4320 */ 133 RESOLUTION_3840X8640, /**< 3840x8640 */ 134 RESOLUTION_INVALID /**< Invalid resolution */ 135 } PicSize; 136 137 /** 138 * @brief Enumerates types of group of pictures (GOP). 139 */ 140 typedef enum { 141 VENCOD_GOPMODE_NORMALP = 0, /**< P-frames using only one reference frame during encoding */ 142 VENCOD_GOPMODE_DUALP = 1, /**< P-frames using two reference frames during encoding */ 143 VENCOD_GOPMODE_SMARTP = 2, /**< Smart P-frames for encoding */ 144 VENCOD_GOPMODE_ADVSMARTP = 3, /**< Advanced smart P-frames for encoding */ 145 VENCOD_GOPMODE_BIPREDB = 4, /**< B-frames for encoding */ 146 VENCOD_GOPMODE_LOWDELAYB = 5, /**< B-frames using only previous frames as references during encoding. */ 147 VENCOD_GOPMODE_INVALID, /**< Invalid type */ 148 } VenCodeGopMode; 149 150 /** 151 * @brief Defines the pointer to the type of the dynamic parameter value. 152 */ 153 typedef void *ValueType; 154 155 /** 156 * @brief Describes the dynamic parameter structure, which is mainly used 157 * by {@link CodecCreate} and {@link CodecSetParameter}. 158 */ 159 typedef struct { 160 ParamKey key; /**< Parameter type index */ 161 void *val; /**< Pointer to the parameter value */ 162 int size; /**< Parameter value size */ 163 } Param; 164 165 /** 166 * @brief Enumerates video frame fields. 167 */ 168 typedef enum { 169 VID_FIELD_TOP = 0x1, /**< Top fields on even-number lines */ 170 VID_FIELD_BOTTOM = 0x2, /**< Bottom fields on odd-number lines */ 171 VID_FIELD_INTERLACED = 0x3, /**< Interlaced fields */ 172 VID_FIELD_FRAME = 0x4, /**< Non-interlaced frames */ 173 VID_FIELD_INVALID /**< Invalid fields */ 174 } VideoField; 175 176 /** 177 * @brief Enumerates pixel formats. 178 */ 179 typedef enum { 180 YVU_SEMIPLANAR_420 = 0, /**< YUV 420 SP */ 181 YVU_SEMIPLANAR_420_TILE, /**< YUV SP 420 TILE */ 182 PIX_FORMAT_INVALID /**< Invalid format */ 183 } CodecPixelFormat; 184 185 /** 186 * @brief Enumerates audio channel modes. 187 */ 188 typedef enum { 189 AUD_SOUND_MODE_MONO = 0, /**< Mono channel */ 190 AUD_SOUND_MODE_STEREO = 1, /**< Stereo mode*/ 191 AUD_SOUND_MODE_INVALID /**< Invalid mode */ 192 } AudioSoundMode; 193 194 /** 195 * @brief Enumerates audio sampling rates. 196 */ 197 typedef enum { 198 AUD_SAMPLE_RATE_8000 = 8000, /**< 8 KHz */ 199 AUD_SAMPLE_RATE_12000 = 12000, /**< 12 KHz */ 200 AUD_SAMPLE_RATE_11025 = 11025, /**< 11.025 KHz */ 201 AUD_SAMPLE_RATE_16000 = 16000, /**< 16 KHz */ 202 AUD_SAMPLE_RATE_22050 = 22050, /**< 22.050 KHz */ 203 AUD_SAMPLE_RATE_24000 = 24000, /**< 24 KHz */ 204 AUD_SAMPLE_RATE_32000 = 32000, /**< 32 KHz */ 205 AUD_SAMPLE_RATE_44100 = 44100, /**< 44.1 KHz */ 206 AUD_SAMPLE_RATE_48000 = 48000, /**< 48 KHz */ 207 AUD_SAMPLE_RATE_64000 = 64000, /**< 64 KHz */ 208 AUD_SAMPLE_RATE_96000 = 96000, /**< 96 KHz */ 209 AUD_SAMPLE_RATE_INVALID, /**< Invalid sampling rate */ 210 } AudioSampleRate; 211 212 /** 213 * @brief Enumerates audio bit rates. 214 */ 215 typedef enum { 216 AUD_BITRATE_8K = 8000, /**< 8 kbit/s */ 217 AUD_BITRATE_16K = 16000, /**< 16 kbit/s */ 218 AUD_BITRATE_22K = 22000, /**< 22 kbit/s */ 219 AUD_BITRATE_24K = 24000, /**< 24 kbit/s */ 220 AUD_BITRATE_32K = 32000, /**< 32 kbit/s */ 221 AUD_BITRATE_40K = 40000, /**< 40 kbit/s */ 222 AUD_BITRATE_48K = 48000, /**< 48 kbit/s */ 223 AUD_BITRATE_64K = 64000, /**< 64 kbit/s */ 224 AUD_BITRATE_96K = 96000, /**< 96 kbit/s */ 225 AUD_BITRATE_128K = 128000, /**< 128 kbit/s */ 226 AUD_BITRATE_132K = 132000, /**< 132 kbit/s */ 227 AUD_BITRATE_144K = 144000, /**< 144 kbit/s */ 228 AUD_BITRATE_192K = 192000, /**< 192 kbit/s */ 229 AUD_BITRATE_256K = 256000, /**< 256 kbit/s */ 230 AUD_BITRATE_265K = 265000, /**< 265 kbit/s */ 231 AUD_BITRATE_288K = 288000, /**< 288 kbit/s */ 232 AUD_BITRATE_320K = 320000, /**< 320 kbit/s */ 233 } AudioBitRate; 234 235 /** 236 * @brief Enumerates stream flags. 237 */ 238 typedef enum { 239 STREAM_FLAG_KEYFRAME = 1, /**< Keyframe */ 240 STREAM_FLAG_CODEC_SPECIFIC_INF = 2, /**< Codec specifications */ 241 STREAM_FLAG_EOS = 4, /**< End of streams */ 242 STREAM_FLAG_PART_OF_FRAME = 8, /**< Partial frame */ 243 STREAM_FLAG_END_OF_FRAME = 16, /**< End of frames, used in pair with <b> STREAM_FLAG_PART_OF_FRAME</b> */ 244 } StreamFlagType; 245 246 /** 247 * @brief Defines the codec buffer handle type. The virtual address of a handle maps to its physical address. 248 */ 249 typedef struct { 250 uint8_t *virAddr; /**< Virtual address */ 251 uintptr_t handle; /**< Physical address */ 252 } CodecBufferHandle; 253 254 /** 255 * @brief Enumerates buffer types. 256 */ 257 typedef enum { 258 BUFFER_TYPE_VIRTUAL = 0, /**< Virtual memory */ 259 BUFFER_TYPE_FD, /**< File descriptor, which can be used cross processes */ 260 BUFFER_TYPE_HANDLE, /**< Handle, which can be used cross processes */ 261 } BufferType; 262 263 /** 264 * @brief Describes buffer information. 265 */ 266 typedef struct { 267 BufferType type; /**< Buffer type */ 268 /** 269 * @brief Describes the buffer address. 270 */ 271 union { 272 uint8_t *addr; /**< Virtual address */ 273 int32_t fd; /**< File descriptor */ 274 CodecBufferHandle handle; /**< Data handle. For details, see {@link CodecBufferHandle} */ 275 }; 276 uint32_t offset; /**< Buffer offset */ 277 uint32_t length; /**< Length of valid data */ 278 uint32_t size; /**< Total size of buffer blocks*/ 279 } CodecBufferInfo; 280 281 /** 282 * @brief Describes input information. 283 */ 284 typedef struct { 285 uint32_t bufferCnt; /**< Number of buffers */ 286 CodecBufferInfo *buffers; /**< Pointer to the buffer description. For details, see {@link CodecBufferInfo}. */ 287 int64_t pts; /**< Input timestamp */ 288 int32_t flag; /**< Input flag. For details, see {@link StreamFlagType}. */ 289 } InputInfo; 290 291 /** 292 * @brief Describes output information. 293 */ 294 typedef struct { 295 uint32_t bufferCnt; /**< Number of buffers */ 296 CodecBufferInfo *buffers; /**< Pointer to the buffer description. For details, see {@link CodecBufferInfo}. */ 297 int64_t timeStamp; /**< Output timestamp */ 298 uint32_t sequence; /**< Corresponding input sequence number */ 299 uint32_t flag; /**< Output flag */ 300 CodecType type; /**< Codec type */ 301 void *vendorPrivate; /**< Private information about a device vendor */ 302 } OutputInfo; 303 304 /** 305 * @brief Enumerates MIME types. 306 */ 307 typedef enum { 308 MEDIA_MIMETYPE_IMAGE_JPEG = 0, /**< JPEG image */ 309 MEDIA_MIMETYPE_VIDEO_AVC, /**< H.264 video */ 310 MEDIA_MIMETYPE_VIDEO_HEVC, /**< H.265 video */ 311 MEDIA_MIMETYPE_AUDIO_AAC, /**< AAC audio */ 312 MEDIA_MIMETYPE_AUDIO_G711A, /**< G711A audio */ 313 MEDIA_MIMETYPE_AUDIO_G711U, /**< G711U audio */ 314 MEDIA_MIMETYPE_AUDIO_G726, /**< G726 audio */ 315 MEDIA_MIMETYPE_AUDIO_PCM, /**< PCM audio */ 316 MEDIA_MIMETYPE_AUDIO_MP3, /**< MP3 audio */ 317 MEDIA_MIMETYPE_INVALID, /**< Invalid MIME type */ 318 } AvCodecMime; 319 320 /** 321 * @brief Enumerates codec profiles. 322 */ 323 typedef enum { 324 INVALID_PROFILE = 0, /**< Invalid profile */ 325 AAC_LC_PROFILE = 0x1000, /**< AAC-Low Complex */ 326 AAC_MAIN_PROFILE, /**< AAC-Main */ 327 AAC_HE_V1_PROFILE, /**< HEAAC, AAC+, or AACPlusV1 */ 328 AAC_HE_V2_PROFILE, /**< AAC++ or AACPlusV2 */ 329 AAC_LD_PROFILE, /**< AAC-Low Delay */ 330 AAC_ELD_PROFILE, /**< AAC-Enhanced Low Delay */ 331 AVC_BASELINE_PROFILE = 0x2000, /**< H.264 Baseline */ 332 AVC_MAIN_PROFILE, /**< H.264 Main */ 333 AVC_HIGH_PROFILE, /**< H.264 High */ 334 HEVC_MAIN_PROFILE = 0x3000, /**< H.265 Main */ 335 HEVC_MAIN_10_PROFILE, /**< H.265 Main 10 */ 336 } Profile; 337 338 /** 339 * @brief Enumerates codec levels. 340 */ 341 typedef enum { 342 INVALID_LEVEL = 0, /**< Invalid level */ 343 AVC_LEVEL_1 = 0x1000, /**< H.264 level 1 */ 344 HEVC_LEVEL_MAIN_1 = 0x2000, /**< H.265 Main level 1 */ 345 HEVC_LEVEL_MAIN_2, /**< H.265 Main level 2 */ 346 } Level; 347 348 /** 349 * @brief Indicates the maximum number of reserved parameters in the array. 350 */ 351 #define ELEMENT_MAX_LEN 50 352 353 /** 354 * @brief Defines a variable-length queue. 355 */ 356 typedef struct { 357 uint32_t element[ELEMENT_MAX_LEN]; /**< Array of reserved parameters */ 358 uint32_t actualLen; /**< Number of actual parameters */ 359 } ResizableArray; 360 361 /** 362 * @brief Defines the alignment. 363 */ 364 typedef struct { 365 int widthAlginment; /**< Value to align with the width */ 366 int heightAlginment; /**< Value to align with the height */ 367 } Alginment; 368 369 /** 370 * @brief Defines a rectangle. 371 */ 372 typedef struct { 373 int32_t width; /**< Width */ 374 int32_t height; /**< Height */ 375 } Rect; 376 377 /** 378 * @brief Enumerates allocation modes of input and output buffers. 379 */ 380 typedef enum { 381 ALLOCATE_INPUT_BUFFER_CODEC = 0x1, /**< Input buffer allocated within the Codec module */ 382 ALLOCATE_INPUT_BUFFER_USER = 0x2, /**< Input buffer allocated by an external user */ 383 ALLOCATE_OUTPUT_BUFFER_CODEC = 0x4, /**< Output buffer allocated within the Codec module */ 384 ALLOCATE_OUTPUT_BUFFER_USER = 0x8, /**< Output buffer allocated by an external user */ 385 } AllocateBufferMode; 386 387 /** 388 * @brief Enumerates playback capabilities. 389 */ 390 typedef enum { 391 ADAPTIVE_PLAYBACK = 0x1, /**< Adaptive playback */ 392 SECURE_PLAYBACK = 0x2, /**< Secure playback */ 393 } CapsMask; 394 395 /** 396 * @brief Defines the codec capability. 397 */ 398 typedef struct { 399 AvCodecMime mime; /**< MIME type */ 400 CodecType type; /**< Codec type */ 401 Alginment whAlignment; /**< Value to align with the width and height */ 402 Rect minSize; /**< Minimum resolution supported */ 403 Rect maxSize; /**< Maximum resolution supported */ 404 uint64_t minBitRate; /**< Minimum bit rate supported */ 405 uint64_t maxBitRate; /**< Maximum bit rate supported */ 406 ResizableArray supportProfiles; /**< Supported profiles */ 407 ResizableArray supportLevels; /**< Supported levels */ 408 ResizableArray supportPixelFormats; /**< Supported pixel formats */ 409 uint32_t minInputBufferNum; /**< Minimum number of input buffers required for running */ 410 uint32_t minOutputBufferNum; /**< Minimum number of output buffers required for running */ 411 uint32_t allocateMask; /**< Buffer allocation mode. For details, see {@link AllocateBufferMode}. */ 412 uint32_t capsMask; /**< Capability mask. For details, see {@link CapsMask}. */ 413 } CodecCapbility; 414 415 /** 416 * @brief Enumerates event types. 417 */ 418 typedef enum { 419 EVENT_ERROR, /**< Event error */ 420 EVENT_FLUSH_COMPLETE, /**< Buffer flush completed */ 421 EVENT_STOP_COMPLETE, /**< Codec stopped */ 422 EVENT_OUT_FORMAT_CHANGED, /**< Output format changed */ 423 EVENT_MAX = 0x1FFFFFFF /**< Maximum event value */ 424 } EventType; 425 426 /** 427 * @brief Redefines the unsigned pointer type, which is used for pointer conversion. 428 */ 429 typedef uintptr_t UINTPTR; 430 431 /** 432 * @brief Defines callbacks and their parameters. 433 */ 434 typedef struct { 435 /** 436 * @brief Reports an event. 437 * 438 * Reports event errors and output format changes. 439 * 440 * @param hComponent Indicates the handle of the codec component. 441 * @param pAppData Indicates upper-layer data, which is generally 442 * an upper-layer instance passed when this callback is set. 443 * @param EVENTTYPE Indicates the event type. 444 * @param nData1 Indicates the first value contained in the reported event. This parameter is optional. 445 * @param nData2 Indicates the second value contained in the reported event. This parameter is optional. 446 * @param pEventData Indicates the pointer to data contained in the reported event. This parameter is optional. 447 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 448 */ 449 int (*OnEvent)(UINTPTR comp, UINTPTR appData, EventType event, 450 uint32_t data1, uint32_t data2, UINTPTR eventData); 451 452 /** 453 * @brief Reports that the input data has been used. 454 * 455 * This callback is invoked in asynchronous mode. 456 * 457 * @param hComponent Indicates the handle of the codec component. 458 * @param pAppData Indicates upper-layer data, which is generally 459 * an upper-layer instance passed when this callback is set. 460 * @param pBuffer Indicates the pointer to the input data that has been used. 461 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 462 */ 463 int (*InputBufferAvailable)(UINTPTR comp, UINTPTR appData, InputInfo *inBuf); 464 465 /** 466 * @brief Reports that the output is complete. 467 * 468 * This callback is invoked in asynchronous mode. 469 * 470 * @param hComponent Indicates the handle of the codec component. 471 * @param pAppData Indicates upper-layer data, which is generally 472 * an upper-layer instance passed when this callback is registered. 473 * @param pBuffer Indicates the pointer to the output data that has been generated. 474 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 475 */ 476 int (*OutputBufferAvailable)(UINTPTR comp, UINTPTR appData, OutputInfo *outBuf); 477 } CodecCallback; 478 479 /** 480 * @brief Enumerates input and output types. 481 */ 482 typedef enum { 483 INPUT_TYPE, /**< Input */ 484 OUTPUT_TYPE, /**< Output */ 485 ALL_TYPE, /**< Input and output */ 486 } DirectionType; 487 488 /** 489 * @brief Enumerates allocation types. 490 */ 491 typedef enum { 492 INTERNAL, /**< Internal */ 493 EXTERNAL, /**< External */ 494 } BufferMode; 495 496 /** 497 * @brief Enumerates codec error types. 498 */ 499 enum { 500 CODEC_SUCCESS = 0, /**< success */ 501 CODEC_ERR_STREAM_BUF_FULL = 100, /**< Elementary stream buffer queue is full. */ 502 CODEC_ERR_FRAME_BUF_EMPTY, /**< Frame buffer queue is empty. */ 503 CODEC_RECEIVE_EOS, /**< End of streams */ 504 CODEC_ERR_INVALID_OP, /**< Invalid operation */ 505 CODEC_ERR_UNKOWN /**< unknown error */ 506 }; 507 508 #ifdef __cplusplus 509 #if __cplusplus 510 } 511 #endif 512 #endif /* __cplusplus */ 513 514 #endif /* CODEC_TYPE_H */ 515 /** @} */