1 /* 2 * Copyright (C) 2023 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 AVCapability 18 * @{ 19 * 20 * @brief The AVCapability module provides functions for querying encoding and decoding capabilities. 21 * 22 * @syscap SystemCapability.Multimedia.Media.CodecBase 23 * @since 10 24 */ 25 26 /** 27 * @file native_avcapability.h 28 * 29 * @brief Declare the Native API used for querying encoding and decoding capabilities. 30 * 31 * @kit AVCodecKit 32 * @library libnative_media_codecbase.so 33 * @syscap SystemCapability.Multimedia.Media.CodecBase 34 * @since 10 35 */ 36 37 #ifndef NATIVE_AVCAPABILITY_H 38 #define NATIVE_AVCAPABILITY_H 39 40 #include <stdint.h> 41 #include "native_averrors.h" 42 #include "native_avformat.h" 43 #include "native_avcodec_base.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Forward declaration of OH_AVCapability. 51 * 52 * @since 10 53 */ 54 typedef struct OH_AVCapability OH_AVCapability; 55 56 /** 57 * @brief Range contain min and max value 58 * @syscap SystemCapability.Multimedia.Media.CodecBase 59 * @since 10 60 */ 61 typedef struct OH_AVRange { 62 int32_t minVal; 63 int32_t maxVal; 64 } OH_AVRange; 65 66 /** 67 * @brief The codec category 68 * @syscap SystemCapability.Multimedia.Media.CodecBase 69 * @since 10 70 */ 71 typedef enum OH_AVCodecCategory { 72 HARDWARE = 0, 73 SOFTWARE 74 } OH_AVCodecCategory; 75 76 /** 77 * @brief The enum of optional features that can be used in specific codec seenarios. 78 * 79 * @syscap SystemCapability.Multimedia.Media.CodecBase 80 * @since 12 81 */ 82 typedef enum OH_AVCapabilityFeature { 83 /** Feature for codec supports temporal scalability. It is only used in video encoder. */ 84 VIDEO_ENCODER_TEMPORAL_SCALABILITY = 0, 85 /** Feature for codec supports long-term reference. It is only used in video encoder. */ 86 VIDEO_ENCODER_LONG_TERM_REFERENCE = 1, 87 /** Feature for codec supports low latency. It is only used in video decoder. */ 88 VIDEO_LOW_LATENCY = 2, 89 /** Feature for codec supports B-frame encoding. It is only used in video encoder. 90 * @since 20 91 */ 92 VIDEO_ENCODER_B_FRAME = 7, 93 } OH_AVCapabilityFeature; 94 95 /** 96 * @brief Get a system-recommended codec's capability. 97 * @syscap SystemCapability.Multimedia.Media.CodecBase 98 * @param mime Mime type 99 * @param isEncoder True for encoder, false for decoder 100 * @return Returns a capability instance if an existing codec matches, 101 * if the specified mime type doesn't match any existing codec, returns NULL. 102 * @since 10 103 */ 104 OH_AVCapability *OH_AVCodec_GetCapability(const char *mime, bool isEncoder); 105 106 /** 107 * @brief Get a codec's capability within the specified category. By specifying the category, 108 * the matched codec is limited to either hardware codecs or software codecs. 109 * @syscap SystemCapability.Multimedia.Media.CodecBase 110 * @param mime Mime type 111 * @param isEncoder True for encoder, false for decoder 112 * @param category The codec category 113 * @return Returns a capability instance if an existing codec matches, 114 * if the specified mime type doesn't match any existing codec, returns NULL 115 * @since 10 116 */ 117 OH_AVCapability *OH_AVCodec_GetCapabilityByCategory(const char *mime, bool isEncoder, OH_AVCodecCategory category); 118 119 /** 120 * @brief Check if the capability instance is describing a hardware codec. 121 * @syscap SystemCapability.Multimedia.Media.CodecBase 122 * @param capability Codec capability pointer 123 * @return Returns true if the capability instance is describing a hardware codec, 124 * false if the capability instance is describing a software codec 125 * @since 10 126 */ 127 bool OH_AVCapability_IsHardware(OH_AVCapability *capability); 128 129 /** 130 * @brief Get the codec name. 131 * @syscap SystemCapability.Multimedia.Media.CodecBase 132 * @param capability Codec capability pointer 133 * @return Returns codec name string 134 * @since 10 135 */ 136 const char *OH_AVCapability_GetName(OH_AVCapability *capability); 137 138 /** 139 * @brief Get the supported max instance number of the codec. 140 * @syscap SystemCapability.Multimedia.Media.CodecBase 141 * @param capability Codec capability pointer 142 * @return Returns the max supported codec instance number 143 * @since 10 144 */ 145 int32_t OH_AVCapability_GetMaxSupportedInstances(OH_AVCapability *capability); 146 147 /** 148 * @brief Get the encoder's supported bitrate range. 149 * @syscap SystemCapability.Multimedia.Media.CodecBase 150 * @param capability Encoder capability pointer. If a decoder capability pointer is given, 151 * undefined behavior occurs 152 * @param bitrateRange Output parameter. Encoder bitrate range 153 * @return Returns AV_ERR_OK if the execution is successful, 154 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 155 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the bitrateRange is nullptr. 156 * @since 10 157 */ 158 OH_AVErrCode OH_AVCapability_GetEncoderBitrateRange(OH_AVCapability *capability, OH_AVRange *bitrateRange); 159 160 /** 161 * @brief Check if the encoder supports the specific bitrate mode. 162 * @syscap SystemCapability.Multimedia.Media.CodecBase 163 * @param capability Encoder capability pointer. If a decoder capability pointer is given, 164 * undefined behavior occurs 165 * @param bitrateMode Bitrate mode 166 * @return Returns true if the bitrate mode is supported, false if the bitrate mode is not supported 167 * @since 10 168 */ 169 bool OH_AVCapability_IsEncoderBitrateModeSupported(OH_AVCapability *capability, OH_BitrateMode bitrateMode); 170 171 /** 172 * @brief Get the encoder's supported quality range. 173 * @syscap SystemCapability.Multimedia.Media.CodecBase 174 * @param capability Encoder capability pointer. If a decoder capability pointer is given, 175 * undefined behavior occurs 176 * @param qualityRange Output parameter. Encoder quality range 177 * @return Returns AV_ERR_OK if the execution is successful, 178 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 179 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the qualityRange is nullptr. 180 * @since 10 181 */ 182 OH_AVErrCode OH_AVCapability_GetEncoderQualityRange(OH_AVCapability *capability, OH_AVRange *qualityRange); 183 184 /** 185 * @brief Get the encoder's supported encoder complexity range. 186 * @syscap SystemCapability.Multimedia.Media.CodecBase 187 * @param capability Encoder capability pointer. If a decoder capability pointer is given, 188 * undefined behavior occurs 189 * @param complexityRange Output parameter. Encoder complexity range 190 * @return Returns AV_ERR_OK if the execution is successful, 191 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 192 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the complexityRange is nullptr. 193 * @since 10 194 */ 195 OH_AVErrCode OH_AVCapability_GetEncoderComplexityRange(OH_AVCapability *capability, OH_AVRange *complexityRange); 196 197 /** 198 * @brief Get the audio codec's supported sample rates. 199 * @syscap SystemCapability.Multimedia.Media.CodecBase 200 * @param capability Audio codec capability pointer. If a video codec capability pointer is given, 201 * undefined behavior occurs 202 * @param sampleRates Output parameter. A pointer to the sample rates array 203 * @param sampleRateNum Output parameter. The element number of the sample rates array 204 * @return Returns AV_ERR_OK if the execution is successful, 205 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 206 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the sampleRates is nullptr, or sampleRateNum is nullptr. 207 * {@link AV_ERR_UNKNOWN}, unknown error. 208 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 209 * @since 10 210 */ 211 OH_AVErrCode OH_AVCapability_GetAudioSupportedSampleRates(OH_AVCapability *capability, const int32_t **sampleRates, 212 uint32_t *sampleRateNum); 213 214 /** 215 * @brief Get the audio codec's supported sample rate ranges. 216 * @syscap SystemCapability.Multimedia.Media.CodecBase 217 * @param capability Audio codec capability pointer. Do not give a video codec capability pointer 218 * @param sampleRateRanges Output parameter. A pointer to the sample rate ranges array 219 * @param rangesNum Output parameter. The element number of the sample rate ranges array 220 * @return Returns AV_ERR_OK if the execution is successful, 221 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 222 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the sampleRateRanges is nullptr, or rangesNum is nullptr. 223 * {@link AV_ERR_UNKNOWN}, unknown error. 224 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 225 * @since 20 226 */ 227 OH_AVErrCode OH_AVCapability_GetAudioSupportedSampleRateRanges(OH_AVCapability *capability, 228 OH_AVRange **sampleRateRanges, uint32_t *rangesNum); 229 230 /** 231 * @brief Get the audio codec's supported audio channel count range. 232 * @syscap SystemCapability.Multimedia.Media.CodecBase 233 * @param capability Audio codec capability pointer. If a video codec capability pointer is given, 234 * undefined behavior occurs 235 * @param channelCountRange Output parameter. Audio channel count range 236 * @return Returns AV_ERR_OK if the execution is successful, 237 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 238 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the channelCountRange is nullptr. 239 * @since 10 240 */ 241 OH_AVErrCode OH_AVCapability_GetAudioChannelCountRange(OH_AVCapability *capability, OH_AVRange *channelCountRange); 242 243 /** 244 * @brief Get the video codec's supported video width alignment. 245 * @syscap SystemCapability.Multimedia.Media.CodecBase 246 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 247 * undefined behavior occurs 248 * @param widthAlignment Output parameter. Video width alignment 249 * @return Returns AV_ERR_OK if the execution is successful, 250 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 251 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the widthAlignment is nullptr. 252 * @since 10 253 */ 254 OH_AVErrCode OH_AVCapability_GetVideoWidthAlignment(OH_AVCapability *capability, int32_t *widthAlignment); 255 256 /** 257 * @brief Get the video codec's supported video height alignment. 258 * @syscap SystemCapability.Multimedia.Media.CodecBase 259 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 260 * undefined behavior occurs 261 * @param heightAlignment Output parameter. Video height alignment 262 * @return Returns AV_ERR_OK if the execution is successful, 263 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 264 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the heightAlignment is nullptr. 265 * @since 10 266 */ 267 OH_AVErrCode OH_AVCapability_GetVideoHeightAlignment(OH_AVCapability *capability, int32_t *heightAlignment); 268 269 /** 270 * @brief Get the video codec's supported video width range for a specific height. 271 * @syscap SystemCapability.Multimedia.Media.CodecBase 272 * @param capability video codec capability pointer. If an audio codec capability pointer is given, 273 * undefined behavior occurs 274 * @param height Vertical pixel number of the video 275 * @param widthRange Output parameter. Video width range 276 * @return Returns AV_ERR_OK if the execution is successful, 277 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 278 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the height is not within the supported range 279 * obtained through {@link OH_AVCapability_GetVideoHeightRange}, or the widthRange is nullptr. 280 * @since 10 281 */ 282 OH_AVErrCode OH_AVCapability_GetVideoWidthRangeForHeight(OH_AVCapability *capability, int32_t height, 283 OH_AVRange *widthRange); 284 285 /** 286 * @brief Get the video codec's supported video height range for a specific width. 287 * @syscap SystemCapability.Multimedia.Media.CodecBase 288 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 289 * undefined behavior occurs 290 * @param width Horizontal pixel number of the video 291 * @param heightRange Output parameter. Video height range 292 * @return Returns AV_ERR_OK if the execution is successful, 293 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 294 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the width is not within the supported range 295 * obtained through {@link OH_AVCapability_GetVideoWidthRange}, or the heightRange is nullptr. 296 * @since 10 297 */ 298 OH_AVErrCode OH_AVCapability_GetVideoHeightRangeForWidth(OH_AVCapability *capability, int32_t width, 299 OH_AVRange *heightRange); 300 301 /** 302 * @brief Get the video codec's supported video width range. 303 * @syscap SystemCapability.Multimedia.Media.CodecBase 304 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 305 * undefined behavior occurs 306 * @param widthRange Output parameter. Video width range 307 * @return Returns AV_ERR_OK if the execution is successful, 308 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 309 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the widthRange is nullptr. 310 * @since 10 311 */ 312 OH_AVErrCode OH_AVCapability_GetVideoWidthRange(OH_AVCapability *capability, OH_AVRange *widthRange); 313 314 /** 315 * @brief Get the video codec's supported video height range. 316 * @syscap SystemCapability.Multimedia.Media.CodecBase 317 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 318 * undefined behavior occurs 319 * @param heightRange Output parameter. Video height range 320 * @return Returns AV_ERR_OK if the execution is successful, 321 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 322 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the heightRange is nullptr. 323 * @since 10 324 */ 325 OH_AVErrCode OH_AVCapability_GetVideoHeightRange(OH_AVCapability *capability, OH_AVRange *heightRange); 326 327 /** 328 * @brief Check if the video codec supports the specific video size. 329 * @syscap SystemCapability.Multimedia.Media.CodecBase 330 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 331 * undefined behavior occurs 332 * @param width Horizontal pixel number of the video 333 * @param height Vertical pixel number of the video 334 * @return Returns true if the video size is supported, false if the video size is not supported 335 * @since 10 336 */ 337 bool OH_AVCapability_IsVideoSizeSupported(OH_AVCapability *capability, int32_t width, int32_t height); 338 339 /** 340 * @brief Get the video codec's supported video frame rate range. 341 * @syscap SystemCapability.Multimedia.Media.CodecBase 342 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 343 * undefined behavior occurs 344 * @param frameRateRange Output parameter. Video frame rate range 345 * @return Returns AV_ERR_OK if the execution is successful, 346 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 347 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the frameRateRange is nullptr. 348 * @since 10 349 */ 350 OH_AVErrCode OH_AVCapability_GetVideoFrameRateRange(OH_AVCapability *capability, OH_AVRange *frameRateRange); 351 352 /** 353 * @brief Get the Video codec's supported video frame rate range for a specified video size. 354 * @syscap SystemCapability.Multimedia.Media.CodecBase 355 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 356 * undefined behavior occurs 357 * @param width Horizontal pixel number of the video 358 * @param height Vertical pixel number of the video 359 * @param frameRateRange Output parameter. Frame rate range 360 * @return Returns AV_ERR_OK if the execution is successful, 361 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 362 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the combination of width and height is 363 * not supported, or the frameRateRange is nullptr. 364 * @since 10 365 */ 366 OH_AVErrCode OH_AVCapability_GetVideoFrameRateRangeForSize(OH_AVCapability *capability, int32_t width, int32_t height, 367 OH_AVRange *frameRateRange); 368 369 /** 370 * @brief Check if the video codec supports the specific combination of video size and frame rate. 371 * @syscap SystemCapability.Multimedia.Media.CodecBase 372 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 373 * undefined behavior occurs 374 * @param width Horizontal pixel number of the video 375 * @param height Vertical pixel number of the video 376 * @param frameRate Frame number per second 377 * @return Returns true if the combination of video size and frame rate is supported, 378 * false if it is not supported 379 * @since 10 380 */ 381 bool OH_AVCapability_AreVideoSizeAndFrameRateSupported(OH_AVCapability *capability, int32_t width, int32_t height, 382 int32_t frameRate); 383 384 /** 385 * @brief Get the video codec's supported video pixel format. 386 * @syscap SystemCapability.Multimedia.Media.CodecBase 387 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 388 * undefined behavior occurs 389 * @param pixelFormats Output parameter. A pointer to the video pixel format array 390 * @param pixelFormatNum Output parameter. The element number of the pixel format array 391 * @return Returns AV_ERR_OK if the execution is successful, 392 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 393 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the pixelFormats is nullptr, 394 * or the pixelFormatNum is nullptr. 395 * {@link AV_ERR_UNKNOWN}, unknown error. 396 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 397 * @since 10 398 */ 399 OH_AVErrCode OH_AVCapability_GetVideoSupportedPixelFormats(OH_AVCapability *capability, const int32_t **pixelFormats, 400 uint32_t *pixelFormatNum); 401 402 /** 403 * @brief Get the codec's supported profiles. 404 * @syscap SystemCapability.Multimedia.Media.CodecBase 405 * @param capability Codec capability pointer 406 * @param profiles Output parameter. A pointer to the profile array 407 * @param profileNum Output parameter. The element number of the profile array 408 * @return Returns AV_ERR_OK if the execution is successful, 409 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 410 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the profiles is nullptr, or the profileNum is nullptr. 411 * {@link AV_ERR_UNKNOWN}, unknown error. 412 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 413 * @since 10 414 */ 415 OH_AVErrCode OH_AVCapability_GetSupportedProfiles(OH_AVCapability *capability, const int32_t **profiles, 416 uint32_t *profileNum); 417 418 /** 419 * @brief Get codec's supported levels for a specific profile. 420 * @syscap SystemCapability.Multimedia.Media.CodecBase 421 * @param capability Codec capability pointer 422 * @param profile Codec profile 423 * @param levels Output parameter. A pointer to the level array 424 * @param levelNum Output parameter. The element number of the level array 425 * @return Returns AV_ERR_OK if the execution is successful, 426 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 427 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the profile is not within the supported profile array 428 * obtained through {@link OH_AVCapability_GetSupportedProfiles}, the levels is nullptr, or the levelNum is nullptr. 429 * {@link AV_ERR_UNKNOWN}, unknown error. 430 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 431 * @since 10 432 */ 433 OH_AVErrCode OH_AVCapability_GetSupportedLevelsForProfile(OH_AVCapability *capability, int32_t profile, 434 const int32_t **levels, uint32_t *levelNum); 435 436 /** 437 * @brief Check if the codec supports the specific combination of the profile and level. 438 * @syscap SystemCapability.Multimedia.Media.CodecBase 439 * @param capability Codec capability pointer 440 * @param profile Codec profile 441 * @param level Codec level 442 * @return Returns true if the combination of profile and level is supported, 443 * false if it is not supported 444 * @since 10 445 */ 446 bool OH_AVCapability_AreProfileAndLevelSupported(OH_AVCapability *capability, int32_t profile, int32_t level); 447 448 /** 449 * @brief Check if the codec supports the specified feature. 450 * 451 * @syscap SystemCapability.Multimedia.Media.CodecBase 452 * @param capability Codec capability pointer 453 * @param feature Feature enum, refer to {@link OH_AVCapabilityFeature} for details 454 * @return Returns true if the feature is supported, false if it is not supported 455 * @since 12 456 */ 457 bool OH_AVCapability_IsFeatureSupported(OH_AVCapability *capability, OH_AVCapabilityFeature feature); 458 459 /** 460 * @brief Get the properties of the specified feature. It should be noted that the life cycle of the OH_AVFormat 461 * instance pointed to by the return value * needs to be manually released by the caller. 462 * 463 * @syscap SystemCapability.Multimedia.Media.CodecBase 464 * @param capability Codec capability pointer 465 * @param feature Feature enum, refer to {@link OH_AVCapabilityFeature} for details 466 * @return Returns a pointer to an OH_AVFormat instance 467 * @since 12 468 */ 469 OH_AVFormat *OH_AVCapability_GetFeatureProperties(OH_AVCapability *capability, OH_AVCapabilityFeature feature); 470 471 #ifdef __cplusplus 472 } 473 #endif 474 #endif // NATIVE_AVCAPABILITY_H 475 /** @} */