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