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