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