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. Do not give a decoder capability pointer 147 * @param bitrateRange Output parameter. Encoder bitrate range 148 * @return Returns AV_ERR_OK if the execution is successful, 149 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 150 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the bitrateRange is nullptr. 151 * @since 10 152 */ 153 OH_AVErrCode OH_AVCapability_GetEncoderBitrateRange(OH_AVCapability *capability, OH_AVRange *bitrateRange); 154 155 /** 156 * @brief Check if the encoder supports the specific bitrate mode. 157 * @syscap SystemCapability.Multimedia.Media.CodecBase 158 * @param capability Encoder capability pointer. Do not give a decoder capability pointer 159 * @param bitrateMode Bitrate mode 160 * @return Returns true if the bitrate mode is supported, false if the bitrate mode is not supported 161 * @since 10 162 */ 163 bool OH_AVCapability_IsEncoderBitrateModeSupported(OH_AVCapability *capability, OH_BitrateMode bitrateMode); 164 165 /** 166 * @brief Get the encoder's supported quality range. 167 * @syscap SystemCapability.Multimedia.Media.CodecBase 168 * @param capability Encoder capability pointer. Do not give a decoder capability pointer 169 * @param qualityRange Output parameter. Encoder quality range 170 * @return Returns AV_ERR_OK if the execution is successful, 171 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 172 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the qualityRange is nullptr. 173 * @since 10 174 */ 175 OH_AVErrCode OH_AVCapability_GetEncoderQualityRange(OH_AVCapability *capability, OH_AVRange *qualityRange); 176 177 /** 178 * @brief Get the encoder's supported encoder complexity range. 179 * @syscap SystemCapability.Multimedia.Media.CodecBase 180 * @param capability Encoder capability pointer. Do not give a decoder capability pointer 181 * @param complexityRange Output parameter. Encoder complexity range 182 * @return Returns AV_ERR_OK if the execution is successful, 183 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 184 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the complexityRange is nullptr. 185 * @since 10 186 */ 187 OH_AVErrCode OH_AVCapability_GetEncoderComplexityRange(OH_AVCapability *capability, OH_AVRange *complexityRange); 188 189 /** 190 * @brief Get the audio codec's supported sample rates. 191 * @syscap SystemCapability.Multimedia.Media.CodecBase 192 * @param capability Audio codec capability pointer. Do not give a video codec capability pointer 193 * @param sampleRates Output parameter. A pointer to the sample rates array 194 * @param sampleRateNum Output parameter. The element number of the sample rates array 195 * @return Returns AV_ERR_OK if the execution is successful, 196 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 197 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the sampleRates is nullptr, or sampleRateNum is nullptr. 198 * {@link AV_ERR_UNKNOWN}, unknown error. 199 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 200 * @since 10 201 */ 202 OH_AVErrCode OH_AVCapability_GetAudioSupportedSampleRates(OH_AVCapability *capability, const int32_t **sampleRates, 203 uint32_t *sampleRateNum); 204 205 /** 206 * @brief Get the audio codec's supported audio channel count range. 207 * @syscap SystemCapability.Multimedia.Media.CodecBase 208 * @param capability Audio codec capability pointer. Do not give a video codec capability pointer 209 * @param channelCountRange Output parameter. Audio channel count range 210 * @return Returns AV_ERR_OK if the execution is successful, 211 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 212 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the channelCountRange is nullptr. 213 * @since 10 214 */ 215 OH_AVErrCode OH_AVCapability_GetAudioChannelCountRange(OH_AVCapability *capability, OH_AVRange *channelCountRange); 216 217 /** 218 * @brief Get the video codec's supported video width alignment. 219 * @syscap SystemCapability.Multimedia.Media.CodecBase 220 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 221 * @param widthAlignment Output parameter. Video width alignment 222 * @return Returns AV_ERR_OK if the execution is successful, 223 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 224 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the widthAlignment is nullptr. 225 * @since 10 226 */ 227 OH_AVErrCode OH_AVCapability_GetVideoWidthAlignment(OH_AVCapability *capability, int32_t *widthAlignment); 228 229 /** 230 * @brief Get the video codec's supported video height alignment. 231 * @syscap SystemCapability.Multimedia.Media.CodecBase 232 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 233 * @param heightAlignment Output parameter. Video height alignment 234 * @return Returns AV_ERR_OK if the execution is successful, 235 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 236 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the heightAlignment is nullptr. 237 * @since 10 238 */ 239 OH_AVErrCode OH_AVCapability_GetVideoHeightAlignment(OH_AVCapability *capability, int32_t *heightAlignment); 240 241 /** 242 * @brief Get the video codec's supported video width range for a specific height. 243 * @syscap SystemCapability.Multimedia.Media.CodecBase 244 * @param capability video codec capability pointer. Do not give an audio codec capability pointer 245 * @param height Vertical pixel number of the video 246 * @param widthRange Output parameter. Video width range 247 * @return Returns AV_ERR_OK if the execution is successful, 248 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 249 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the height is not within the supported range 250 * obtained through {@link OH_AVCapability_GetVideoHeightRange}, or the widthRange is nullptr. 251 * @since 10 252 */ 253 OH_AVErrCode OH_AVCapability_GetVideoWidthRangeForHeight(OH_AVCapability *capability, int32_t height, 254 OH_AVRange *widthRange); 255 256 /** 257 * @brief Get the video codec's supported video height range for a specific width. 258 * @syscap SystemCapability.Multimedia.Media.CodecBase 259 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 260 * @param width Horizontal pixel number of the video 261 * @param heightRange Output parameter. Video height range 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, the width is not within the supported range 265 * obtained through {@link OH_AVCapability_GetVideoWidthRange}, or the heightRange is nullptr. 266 * @since 10 267 */ 268 OH_AVErrCode OH_AVCapability_GetVideoHeightRangeForWidth(OH_AVCapability *capability, int32_t width, 269 OH_AVRange *heightRange); 270 271 /** 272 * @brief Get the video codec's supported video width range. 273 * @syscap SystemCapability.Multimedia.Media.CodecBase 274 * @param capability Video codec capability pointer. DO not give an audio codec capability pointer 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, or the widthRange is nullptr. 279 * @since 10 280 */ 281 OH_AVErrCode OH_AVCapability_GetVideoWidthRange(OH_AVCapability *capability, OH_AVRange *widthRange); 282 283 /** 284 * @brief Get the video codec's supported video height range. 285 * @syscap SystemCapability.Multimedia.Media.CodecBase 286 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 287 * @param heightRange Output parameter. Video height range 288 * @return Returns AV_ERR_OK if the execution is successful, 289 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 290 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the heightRange is nullptr. 291 * @since 10 292 */ 293 OH_AVErrCode OH_AVCapability_GetVideoHeightRange(OH_AVCapability *capability, OH_AVRange *heightRange); 294 295 /** 296 * @brief Check if the video codec supports the specific video size. 297 * @syscap SystemCapability.Multimedia.Media.CodecBase 298 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 299 * @param width Horizontal pixel number of the video 300 * @param height Vertical pixel number of the video 301 * @return Returns true if the video size is supported, false if the video size is not supported 302 * @since 10 303 */ 304 bool OH_AVCapability_IsVideoSizeSupported(OH_AVCapability *capability, int32_t width, int32_t height); 305 306 /** 307 * @brief Get the video codec's supported video frame rate range. 308 * @syscap SystemCapability.Multimedia.Media.CodecBase 309 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 310 * @param frameRateRange Output parameter. Video frame rate range 311 * @return Returns AV_ERR_OK if the execution is successful, 312 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 313 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, or the frameRateRange is nullptr. 314 * @since 10 315 */ 316 OH_AVErrCode OH_AVCapability_GetVideoFrameRateRange(OH_AVCapability *capability, OH_AVRange *frameRateRange); 317 318 /** 319 * @brief Get the Video codec's supported video frame rate range for a specified video size. 320 * @syscap SystemCapability.Multimedia.Media.CodecBase 321 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 322 * @param width Horizontal pixel number of the video 323 * @param height Vertical pixel number of the video 324 * @param frameRateRange Output parameter. 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, the combination of width and height is 328 * not supported, or the frameRateRange is nullptr. 329 * @since 10 330 */ 331 OH_AVErrCode OH_AVCapability_GetVideoFrameRateRangeForSize(OH_AVCapability *capability, int32_t width, int32_t height, 332 OH_AVRange *frameRateRange); 333 334 /** 335 * @brief Check if the video codec supports the specific combination of video size and frame rate. 336 * @syscap SystemCapability.Multimedia.Media.CodecBase 337 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 338 * @param width Horizontal pixel number of the video 339 * @param height Vertical pixel number of the video 340 * @param frameRate Frame number per second 341 * @return Returns true if the combination of video size and frame rate is supported, 342 * false if it is not supported 343 * @since 10 344 */ 345 bool OH_AVCapability_AreVideoSizeAndFrameRateSupported(OH_AVCapability *capability, int32_t width, int32_t height, 346 int32_t frameRate); 347 348 /** 349 * @brief Get the video codec's supported video pixel format. 350 * @syscap SystemCapability.Multimedia.Media.CodecBase 351 * @param capability Video codec capability pointer. Do not give an audio codec capability pointer 352 * @param pixelFormats Output parameter. A pointer to the video pixel format array 353 * @param pixelFormatNum Output parameter. The element number of the pixel format array 354 * @return Returns AV_ERR_OK if the execution is successful, 355 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 356 * {@link AV_ERR_INVALID_VAL}, the capability is invalid, the pixelFormats is nullptr, 357 * or the pixelFormatNum is nullptr. 358 * {@link AV_ERR_UNKNOWN}, unknown error. 359 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 360 * @since 10 361 */ 362 OH_AVErrCode OH_AVCapability_GetVideoSupportedPixelFormats(OH_AVCapability *capability, const int32_t **pixelFormats, 363 uint32_t *pixelFormatNum); 364 365 /** 366 * @brief Get the codec's supported profiles. 367 * @syscap SystemCapability.Multimedia.Media.CodecBase 368 * @param capability Codec capability pointer 369 * @param profiles Output parameter. A pointer to the profile array 370 * @param profileNum Output parameter. The element number of the profile 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 profiles is nullptr, or the profileNum is nullptr. 374 * {@link AV_ERR_UNKNOWN}, unknown error. 375 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 376 * @since 10 377 */ 378 OH_AVErrCode OH_AVCapability_GetSupportedProfiles(OH_AVCapability *capability, const int32_t **profiles, 379 uint32_t *profileNum); 380 381 /** 382 * @brief Get codec's supported levels for a specific profile. 383 * @syscap SystemCapability.Multimedia.Media.CodecBase 384 * @param capability Codec capability pointer 385 * @param profile Codec profile 386 * @param levels Output parameter. A pointer to the level array 387 * @param levelNum Output parameter. The element number of the level 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 profile is not within the supported profile array 391 * obtained through {@link OH_AVCapability_GetSupportedProfiles}, the levels is nullptr, or the levelNum is nullptr. 392 * {@link AV_ERR_UNKNOWN}, unknown error. 393 * {@link AV_ERR_NO_MEMORY}, internal use memory malloc failed. 394 * @since 10 395 */ 396 OH_AVErrCode OH_AVCapability_GetSupportedLevelsForProfile(OH_AVCapability *capability, int32_t profile, 397 const int32_t **levels, uint32_t *levelNum); 398 399 /** 400 * @brief Check if the codec supports the specific combination of the profile and level. 401 * @syscap SystemCapability.Multimedia.Media.CodecBase 402 * @param capability Codec capability pointer 403 * @param profile Codec profile 404 * @param level Codec level 405 * @return Returns true if the combination of profile and level is supported, 406 * false if it is not supported 407 * @since 10 408 */ 409 bool OH_AVCapability_AreProfileAndLevelSupported(OH_AVCapability *capability, int32_t profile, int32_t level); 410 411 /** 412 * @brief Check if the codec supports the specified feature. 413 * 414 * @syscap SystemCapability.Multimedia.Media.CodecBase 415 * @param capability Codec capability pointer 416 * @param feature Feature enum, refer to {@link OH_AVCapabilityFeature} for details 417 * @return Returns true if the feature is supported, false if it is not supported 418 * @since 12 419 */ 420 bool OH_AVCapability_IsFeatureSupported(OH_AVCapability *capability, OH_AVCapabilityFeature feature); 421 422 /** 423 * @brief Get the properties of the specified feature. It should be noted that the life cycle of the OH_AVFormat 424 * instance pointed to by the return value * needs to be manually released by the caller. 425 * 426 * @syscap SystemCapability.Multimedia.Media.CodecBase 427 * @param capability Codec capability pointer 428 * @param feature Feature enum, refer to {@link OH_AVCapabilityFeature} for details 429 * @return Returns a pointer to an OH_AVFormat instance 430 * @since 12 431 */ 432 OH_AVFormat *OH_AVCapability_GetFeatureProperties(OH_AVCapability *capability, OH_AVCapabilityFeature feature); 433 434 #ifdef __cplusplus 435 } 436 #endif 437 #endif // NATIVE_AVCAPABILITY_H 438 /** @} */