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
24extern "C" {
25#endif
26
27typedef struct OH_AVCapability OH_AVCapability;
28
29/**
30 * @brief The bitrate mode of encoder.
31 * @syscap SystemCapability.Multimedia.Media.CodecBase
32 * @since 10
33 */
34typedef 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 */
48typedef 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 */
58typedef 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 */
69typedef 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 */
87OH_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 */
100OH_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 */
110bool 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 */
119const 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 */
128int32_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 */
140OH_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 */
150bool 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 */
162OH_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 */
174OH_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 */
189OH_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 */
202OH_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 */
214OH_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 */
226OH_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 */
240OH_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 */
255OH_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 */
268OH_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 */
280OH_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 */
291bool 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 */
303OH_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 */
318OH_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 */
332bool 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 */
349OH_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 */
365OH_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 */
383OH_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 */
396bool 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 */
407bool 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 */
419OH_AVFormat *OH_AVCapability_GetFeatureProperties(OH_AVCapability *capability, OH_AVCapabilityFeature feature);
420
421#ifdef __cplusplus
422}
423#endif
424#endif // NATIVE_AVCAPABILITY_H