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 used in video encoder and video decoder. */ 88 VIDEO_LOW_LATENCY = 2, 89 } OH_AVCapabilityFeature; 90 91 /** 92 * @brief Get a system-recommended codec's capability. 93 * @syscap SystemCapability.Multimedia.Media.CodecBase 94 * @param mime Mime type 95 * @param isEncoder True for encoder, false for decoder 96 * @return Returns a capability instance if an existing codec matches, 97 * if the specified mime type doesn't match any existing codec, returns NULL. 98 * @since 10 99 */ 100 OH_AVCapability *OH_AVCodec_GetCapability(const char *mime, bool isEncoder); 101 102 /** 103 * @brief Get a codec's capability within the specified category. By specifying the category, 104 * the matched codec is limited to either hardware codecs or software codecs. 105 * @syscap SystemCapability.Multimedia.Media.CodecBase 106 * @param mime Mime type 107 * @param isEncoder True for encoder, false for decoder 108 * @param category The codec category 109 * @return Returns a capability instance if an existing codec matches, 110 * if the specified mime type doesn't match any existing codec, returns NULL 111 * @since 10 112 */ 113 OH_AVCapability *OH_AVCodec_GetCapabilityByCategory(const char *mime, bool isEncoder, OH_AVCodecCategory category); 114 115 /** 116 * @brief Check if the capability instance is describing a hardware codec. 117 * @syscap SystemCapability.Multimedia.Media.CodecBase 118 * @param capability Codec capability pointer 119 * @return Returns true if the capability instance is describing a hardware codec, 120 * false if the capability instance is describing a software codec 121 * @since 10 122 */ 123 bool OH_AVCapability_IsHardware(OH_AVCapability *capability); 124 125 /** 126 * @brief Get the codec name. 127 * @syscap SystemCapability.Multimedia.Media.CodecBase 128 * @param capability Codec capability pointer 129 * @return Returns codec name string 130 * @since 10 131 */ 132 const char *OH_AVCapability_GetName(OH_AVCapability *capability); 133 134 /** 135 * @brief Get the supported max instance number of the codec. 136 * @syscap SystemCapability.Multimedia.Media.CodecBase 137 * @param capability Codec capability pointer 138 * @return Returns the max supported codec instance number 139 * @since 10 140 */ 141 int32_t OH_AVCapability_GetMaxSupportedInstances(OH_AVCapability *capability); 142 143 /** 144 * @brief Get the encoder's supported bitrate range. 145 * @syscap SystemCapability.Multimedia.Media.CodecBase 146 * @param capability Encoder capability pointer. If a decoder capability pointer is given, 147 * undefined behavior occurs 148 * @param bitrateRange Output parameter. Encoder bitrate range 149 * @return Returns AV_ERR_OK if the execution is successful, 150 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 151 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the bitrateRange is nullptr. 152 * @since 10 153 */ 154 OH_AVErrCode OH_AVCapability_GetEncoderBitrateRange(OH_AVCapability *capability, OH_AVRange *bitrateRange); 155 156 /** 157 * @brief Check if the encoder supports the specific bitrate mode. 158 * @syscap SystemCapability.Multimedia.Media.CodecBase 159 * @param capability Encoder capability pointer. If a decoder capability pointer is given, 160 * undefined behavior occurs 161 * @param bitrateMode Bitrate mode 162 * @return Returns true if the bitrate mode is supported, false if the bitrate mode is not supported 163 * @since 10 164 */ 165 bool OH_AVCapability_IsEncoderBitrateModeSupported(OH_AVCapability *capability, OH_BitrateMode bitrateMode); 166 167 /** 168 * @brief Get the encoder's supported quality range. 169 * @syscap SystemCapability.Multimedia.Media.CodecBase 170 * @param capability Encoder capability pointer. If a decoder capability pointer is given, 171 * undefined behavior occurs 172 * @param qualityRange Output parameter. Encoder quality range 173 * @return Returns AV_ERR_OK if the execution is successful, 174 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 175 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the qualityRange is nullptr. 176 * @since 10 177 */ 178 OH_AVErrCode OH_AVCapability_GetEncoderQualityRange(OH_AVCapability *capability, OH_AVRange *qualityRange); 179 180 /** 181 * @brief Get the encoder's supported encoder complexity range. 182 * @syscap SystemCapability.Multimedia.Media.CodecBase 183 * @param capability Encoder capability pointer. If a decoder capability pointer is given, 184 * undefined behavior occurs 185 * @param complexityRange Output parameter. Encoder complexity range 186 * @return Returns AV_ERR_OK if the execution is successful, 187 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 188 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the complexityRange is nullptr. 189 * @since 10 190 */ 191 OH_AVErrCode OH_AVCapability_GetEncoderComplexityRange(OH_AVCapability *capability, OH_AVRange *complexityRange); 192 193 /** 194 * @brief Get the audio codec's supported sample rates. 195 * @syscap SystemCapability.Multimedia.Media.CodecBase 196 * @param capability Audio codec capability pointer. If a video codec capability pointer is given, 197 * undefined behavior occurs 198 * @param sampleRates Output parameter. A pointer to the sample rates array 199 * @param sampleRateNum Output parameter. The element number of the sample rates array 200 * @return Returns AV_ERR_OK if the execution is successful, 201 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 202 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the sampleRates is nullptr, or sampleRateNum is nullptr. 203 * {@link AV_ERR_UNKNOWN}, unknown error. 204 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 205 * @since 10 206 */ 207 OH_AVErrCode OH_AVCapability_GetAudioSupportedSampleRates(OH_AVCapability *capability, const int32_t **sampleRates, 208 uint32_t *sampleRateNum); 209 210 /** 211 * @brief Get the audio codec's supported audio channel count range. 212 * @syscap SystemCapability.Multimedia.Media.CodecBase 213 * @param capability Audio codec capability pointer. If a video codec capability pointer is given, 214 * undefined behavior occurs 215 * @param channelCountRange Output parameter. Audio channel count range 216 * @return Returns AV_ERR_OK if the execution is successful, 217 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 218 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the channelCountRange is nullptr. 219 * @since 10 220 */ 221 OH_AVErrCode OH_AVCapability_GetAudioChannelCountRange(OH_AVCapability *capability, OH_AVRange *channelCountRange); 222 223 /** 224 * @brief Get the video codec's supported video width alignment. 225 * @syscap SystemCapability.Multimedia.Media.CodecBase 226 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 227 * undefined behavior occurs 228 * @param widthAlignment Output parameter. Video width alignment 229 * @return Returns AV_ERR_OK if the execution is successful, 230 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 231 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the widthAlignment is nullptr. 232 * @since 10 233 */ 234 OH_AVErrCode OH_AVCapability_GetVideoWidthAlignment(OH_AVCapability *capability, int32_t *widthAlignment); 235 236 /** 237 * @brief Get the video codec's supported video height alignment. 238 * @syscap SystemCapability.Multimedia.Media.CodecBase 239 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 240 * undefined behavior occurs 241 * @param heightAlignment Output parameter. Video height alignment 242 * @return Returns AV_ERR_OK if the execution is successful, 243 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 244 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the heightAlignment is nullptr. 245 * @since 10 246 */ 247 OH_AVErrCode OH_AVCapability_GetVideoHeightAlignment(OH_AVCapability *capability, int32_t *heightAlignment); 248 249 /** 250 * @brief Get the video codec's supported video width range for a specific height. 251 * @syscap SystemCapability.Multimedia.Media.CodecBase 252 * @param capability video codec capability pointer. If an audio codec capability pointer is given, 253 * undefined behavior occurs 254 * @param height Vertical pixel number of the video 255 * @param widthRange Output parameter. Video width range 256 * @return Returns AV_ERR_OK if the execution is successful, 257 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 258 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the height is not within the supported range 259 * obtained through {@link OH_AVCapability_GetVideoHeightRange}, or the widthRange is nullptr. 260 * @since 10 261 */ 262 OH_AVErrCode OH_AVCapability_GetVideoWidthRangeForHeight(OH_AVCapability *capability, int32_t height, 263 OH_AVRange *widthRange); 264 265 /** 266 * @brief Get the video codec's supported video height range for a specific width. 267 * @syscap SystemCapability.Multimedia.Media.CodecBase 268 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 269 * undefined behavior occurs 270 * @param width Horizontal pixel number of the video 271 * @param heightRange Output parameter. Video height range 272 * @return Returns AV_ERR_OK if the execution is successful, 273 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 274 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the width is not within the supported range 275 * obtained through {@link OH_AVCapability_GetVideoWidthRange}, or the heightRange is nullptr. 276 * @since 10 277 */ 278 OH_AVErrCode OH_AVCapability_GetVideoHeightRangeForWidth(OH_AVCapability *capability, int32_t width, 279 OH_AVRange *heightRange); 280 281 /** 282 * @brief Get the video codec's supported video width range. 283 * @syscap SystemCapability.Multimedia.Media.CodecBase 284 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 285 * undefined behavior occurs 286 * @param widthRange Output parameter. Video width range 287 * @return Returns AV_ERR_OK if the execution is successful, 288 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 289 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the widthRange is nullptr. 290 * @since 10 291 */ 292 OH_AVErrCode OH_AVCapability_GetVideoWidthRange(OH_AVCapability *capability, OH_AVRange *widthRange); 293 294 /** 295 * @brief Get the video codec's supported video height range. 296 * @syscap SystemCapability.Multimedia.Media.CodecBase 297 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 298 * undefined behavior occurs 299 * @param heightRange Output parameter. Video height range 300 * @return Returns AV_ERR_OK if the execution is successful, 301 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 302 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the heightRange is nullptr. 303 * @since 10 304 */ 305 OH_AVErrCode OH_AVCapability_GetVideoHeightRange(OH_AVCapability *capability, OH_AVRange *heightRange); 306 307 /** 308 * @brief Check if the video codec supports the specific video size. 309 * @syscap SystemCapability.Multimedia.Media.CodecBase 310 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 311 * undefined behavior occurs 312 * @param width Horizontal pixel number of the video 313 * @param height Vertical pixel number of the video 314 * @return Returns true if the video size is supported, false if the video size is not supported 315 * @since 10 316 */ 317 bool OH_AVCapability_IsVideoSizeSupported(OH_AVCapability *capability, int32_t width, int32_t height); 318 319 /** 320 * @brief Get the video codec's supported video frame rate range. 321 * @syscap SystemCapability.Multimedia.Media.CodecBase 322 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 323 * undefined behavior occurs 324 * @param frameRateRange Output parameter. Video frame rate range 325 * @return Returns AV_ERR_OK if the execution is successful, 326 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 327 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the frameRateRange is nullptr. 328 * @since 10 329 */ 330 OH_AVErrCode OH_AVCapability_GetVideoFrameRateRange(OH_AVCapability *capability, OH_AVRange *frameRateRange); 331 332 /** 333 * @brief Get the Video codec's supported video frame rate range for a specified video size. 334 * @syscap SystemCapability.Multimedia.Media.CodecBase 335 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 336 * undefined behavior occurs 337 * @param width Horizontal pixel number of the video 338 * @param height Vertical pixel number of the video 339 * @param frameRateRange Output parameter. Frame rate range 340 * @return Returns AV_ERR_OK if the execution is successful, 341 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 342 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the combination of width and height is 343 * not supported, or the frameRateRange is nullptr. 344 * @since 10 345 */ 346 OH_AVErrCode OH_AVCapability_GetVideoFrameRateRangeForSize(OH_AVCapability *capability, int32_t width, int32_t height, 347 OH_AVRange *frameRateRange); 348 349 /** 350 * @brief Check if the video codec supports the specific combination of video size and frame rate. 351 * @syscap SystemCapability.Multimedia.Media.CodecBase 352 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 353 * undefined behavior occurs 354 * @param width Horizontal pixel number of the video 355 * @param height Vertical pixel number of the video 356 * @param frameRate Frame number per second 357 * @return Returns true if the combination of video size and frame rate is supported, 358 * false if it is not supported 359 * @since 10 360 */ 361 bool OH_AVCapability_AreVideoSizeAndFrameRateSupported(OH_AVCapability *capability, int32_t width, int32_t height, 362 int32_t frameRate); 363 364 /** 365 * @brief Get the video codec's supported video pixel format. 366 * @syscap SystemCapability.Multimedia.Media.CodecBase 367 * @param capability Video codec capability pointer. If an audio codec capability pointer is given, 368 * undefined behavior occurs 369 * @param pixelFormats Output parameter. A pointer to the video pixel format array 370 * @param pixelFormatNum Output parameter. The element number of the pixel format array 371 * @return Returns AV_ERR_OK if the execution is successful, 372 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 373 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the pixelFormats is nullptr, 374 * or the pixelFormatNum is nullptr. 375 * {@link AV_ERR_UNKNOWN}, unknown error. 376 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 377 * @since 10 378 */ 379 OH_AVErrCode OH_AVCapability_GetVideoSupportedPixelFormats(OH_AVCapability *capability, const int32_t **pixelFormats, 380 uint32_t *pixelFormatNum); 381 382 /** 383 * @brief Get the codec's supported profiles. 384 * @syscap SystemCapability.Multimedia.Media.CodecBase 385 * @param capability Codec capability pointer 386 * @param profiles Output parameter. A pointer to the profile array 387 * @param profileNum Output parameter. The element number of the profile array 388 * @return Returns AV_ERR_OK if the execution is successful, 389 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 390 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the profiles is nullptr, or the profileNum is nullptr. 391 * {@link AV_ERR_UNKNOWN}, unknown error. 392 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 393 * @since 10 394 */ 395 OH_AVErrCode OH_AVCapability_GetSupportedProfiles(OH_AVCapability *capability, const int32_t **profiles, 396 uint32_t *profileNum); 397 398 /** 399 * @brief Get codec's supported levels for a specific profile. 400 * @syscap SystemCapability.Multimedia.Media.CodecBase 401 * @param capability Codec capability pointer 402 * @param profile Codec profile 403 * @param levels Output parameter. A pointer to the level array 404 * @param levelNum Output parameter. The element number of the level array 405 * @return Returns AV_ERR_OK if the execution is successful, 406 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 407 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the profile is not within the supported profile array 408 * obtained through {@link OH_AVCapability_GetSupportedProfiles}, the levels is nullptr, or the levelNum is nullptr. 409 * {@link AV_ERR_UNKNOWN}, unknown error. 410 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 411 * @since 10 412 */ 413 OH_AVErrCode OH_AVCapability_GetSupportedLevelsForProfile(OH_AVCapability *capability, int32_t profile, 414 const int32_t **levels, uint32_t *levelNum); 415 416 /** 417 * @brief Check if the codec supports the specific combination of the profile and level. 418 * @syscap SystemCapability.Multimedia.Media.CodecBase 419 * @param capability Codec capability pointer 420 * @param profile Codec profile 421 * @param level Codec level 422 * @return Returns true if the combination of profile and level is supported, 423 * false if it is not supported 424 * @since 10 425 */ 426 bool OH_AVCapability_AreProfileAndLevelSupported(OH_AVCapability *capability, int32_t profile, int32_t level); 427 428 /** 429 * @brief Check if the codec supports the specified feature. 430 * 431 * @syscap SystemCapability.Multimedia.Media.CodecBase 432 * @param capability Codec capability pointer 433 * @param feature Feature enum, refer to {@link OH_AVCapabilityFeature} for details 434 * @return Returns true if the feature is supported, false if it is not supported 435 * @since 12 436 */ 437 bool OH_AVCapability_IsFeatureSupported(OH_AVCapability *capability, OH_AVCapabilityFeature feature); 438 439 /** 440 * @brief Get the properties of the specified feature. It should be noted that the life cycle of the OH_AVFormat 441 * instance pointed to by the return value * needs to be manually released by the caller. 442 * 443 * @syscap SystemCapability.Multimedia.Media.CodecBase 444 * @param capability Codec capability pointer 445 * @param feature Feature enum, refer to {@link OH_AVCapabilityFeature} for details 446 * @return Returns a pointer to an OH_AVFormat instance 447 * @since 12 448 */ 449 OH_AVFormat *OH_AVCapability_GetFeatureProperties(OH_AVCapability *capability, OH_AVCapabilityFeature feature); 450 451 #ifdef __cplusplus 452 } 453 #endif 454 #endif // NATIVE_AVCAPABILITY_H 455 /** @} */