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 Core 18 * @{ 19 * 20 * @brief The Core module provides basic backbone capabilities for media frameworks, 21 * including functions such as memory, error codes, and media data structures. 22 * 23 * @syscap SystemCapability.Multimedia.Media.Core 24 * @since 9 25 */ 26 27 /** 28 * @file native_avformat.h 29 * 30 * @brief Declared functions and enumerations related to OH_AVFormat. 31 * 32 * @kit AVCodecKit 33 * @library libnative_media_core.so 34 * @syscap SystemCapability.Multimedia.Media.Core 35 * @since 9 36 */ 37 38 #ifndef NATIVE_AVFORMAT_H 39 #define NATIVE_AVFORMAT_H 40 41 #include <stdint.h> 42 #include <stdbool.h> 43 #include <stdio.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Forward declaration of OH_AVFormat. 51 * 52 * @since 9 53 */ 54 typedef struct OH_AVFormat OH_AVFormat; 55 56 /** 57 * @brief Enumerates AVPixel Format. 58 * @syscap SystemCapability.Multimedia.Media.Core 59 * @since 9 60 * @version 1.0 61 */ 62 typedef enum OH_AVPixelFormat { 63 /** 64 * yuv 420 planar. 65 */ 66 AV_PIXEL_FORMAT_YUVI420 = 1, 67 /** 68 * NV12. yuv 420 semiplanar. 69 */ 70 AV_PIXEL_FORMAT_NV12 = 2, 71 /** 72 * NV21. yvu 420 semiplanar. 73 */ 74 AV_PIXEL_FORMAT_NV21 = 3, 75 /** 76 * format from surface. 77 */ 78 AV_PIXEL_FORMAT_SURFACE_FORMAT = 4, 79 /** 80 * RGBA8888 81 */ 82 AV_PIXEL_FORMAT_RGBA = 5, 83 /** RGBA1010102 84 * @since 20 85 */ 86 AV_PIXEL_FORMAT_RGBA1010102 = 6, 87 } OH_AVPixelFormat; 88 89 /** 90 * @briefCreate an OH_AVFormat handle pointer to read and write data 91 * @syscap SystemCapability.Multimedia.Media.Core 92 * @return Returns a pointer to an OH_AVFormat instance 93 * @since 9 94 * @version 1.0 95 */ 96 struct OH_AVFormat *OH_AVFormat_Create(void); 97 98 /** 99 * @briefCreate an audio OH_AVFormat handle pointer to read and write data 100 * @syscap SystemCapability.Multimedia.Media.Core 101 * @param mimeType mime type 102 * @param sampleRate sample rate 103 * @param channelCount channel count 104 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr 105 * Possible failure causes: 1. mimeType is nullptr. 2. new format is nullptr. 106 * @since 10 107 * @version 1.0 108 */ 109 struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType, 110 int32_t sampleRate, 111 int32_t channelCount); 112 113 /** 114 * @briefCreate an video OH_AVFormat handle pointer to read and write data 115 * @syscap SystemCapability.Multimedia.Media.Core 116 * @param mimeType mime type 117 * @param width width 118 * @param height height 119 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr 120 * Possible failure causes: 1. mimeType is nullptr. 2. new format is nullptr. 121 * @since 10 122 * @version 1.0 123 */ 124 struct OH_AVFormat *OH_AVFormat_CreateVideoFormat(const char *mimeType, 125 int32_t width, 126 int32_t height); 127 128 /** 129 * @brief Destroy the specified OH_AVFormat handle resource 130 * @syscap SystemCapability.Multimedia.Media.Core 131 * @param format pointer to an OH_AVFormat instance 132 * @return void 133 * @since 9 134 * @version 1.0 135 */ 136 void OH_AVFormat_Destroy(struct OH_AVFormat *format); 137 138 /** 139 * @brief Copy OH_AVFormat handle resource 140 * @syscap SystemCapability.Multimedia.Media.Core 141 * @param to OH_AVFormat handle pointer to receive data 142 * @param from pointer to the OH_AVFormat handle of the copied data 143 * @return The return value is TRUE for success, FALSE for failure 144 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 145 * @since 9 146 * @version 1.0 147 */ 148 bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); 149 150 /** 151 * @brief Write Int data to OH_AVFormat 152 * @syscap SystemCapability.Multimedia.Media.Core 153 * @param format pointer to an OH_AVFormat instance 154 * @param key key to write data 155 * @param value written data 156 * @return The return value is TRUE for success, FALSE for failure 157 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 158 * @since 9 159 * @version 1.0 160 */ 161 bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_t value); 162 163 /** 164 * @brief Write Long data to OH_AVFormat 165 * @syscap SystemCapability.Multimedia.Media.Core 166 * @param format pointer to an OH_AVFormat instance 167 * @param key key to write data 168 * @param value written data 169 * @return The return value is TRUE for success, FALSE for failure 170 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 171 * @since 9 172 * @version 1.0 173 */ 174 bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64_t value); 175 176 /** 177 * @brief Write Float data to OH_AVFormat 178 * @syscap SystemCapability.Multimedia.Media.Core 179 * @param format pointer to an OH_AVFormat instance 180 * @param key key to write data 181 * @param value written data 182 * @return The return value is TRUE for success, FALSE for failure 183 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 184 * @since 9 185 * @version 1.0 186 */ 187 bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, float value); 188 189 /** 190 * @brief Write Double data to OH_AVFormat 191 * @syscap SystemCapability.Multimedia.Media.Core 192 * @param format pointer to an OH_AVFormat instance 193 * @param key key to write data 194 * @param value written data 195 * @return The return value is TRUE for success, FALSE for failure 196 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 197 * @since 9 198 * @version 1.0 199 */ 200 bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, double value); 201 202 /** 203 * @brief Write String data to OH_AVFormat 204 * @syscap SystemCapability.Multimedia.Media.Core 205 * @param format pointer to an OH_AVFormat instance 206 * @param key key to write data 207 * @param value written data 208 * @return The return value is TRUE for success, FALSE for failure 209 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 210 * 4. value is nullptr. 211 * @since 9 212 * @version 1.0 213 */ 214 bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, const char *value); 215 216 /** 217 * @brief Write a block of data of a specified length to OH_AVFormat 218 * @syscap SystemCapability.Multimedia.Media.Core 219 * @param format pointer to an OH_AVFormat instance 220 * @param key key to write data 221 * @param addr written data addr 222 * @param size written data length 223 * @return The return value is TRUE for success, FALSE for failure 224 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 225 * 4. addr is nullptr. 5. size is zero. 226 * @since 9 227 * @version 1.0 228 */ 229 bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const uint8_t *addr, size_t size); 230 231 /** 232 * @brief Read Int data from OH_AVFormat 233 * @syscap SystemCapability.Multimedia.Media.Core 234 * @param format pointer to an OH_AVFormat instance 235 * @param key read key value 236 * @param out read data 237 * @return The return value is TRUE for success, FALSE for failure 238 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 239 * 4. out is nullptr. 240 * @since 9 241 * @version 1.0 242 */ 243 bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_t *out); 244 245 /** 246 * @brief Read Long data from OH_AVFormat 247 * @syscap SystemCapability.Multimedia.Media.Core 248 * @param format pointer to an OH_AVFormat instance 249 * @param key read key value 250 * @param out read data 251 * @return The return value is TRUE for success, FALSE for failure 252 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 253 * 4. out is nullptr. 254 * @since 9 255 * @version 1.0 256 */ 257 bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64_t *out); 258 259 /** 260 * @brief Read Float data from OH_AVFormat 261 * @syscap SystemCapability.Multimedia.Media.Core 262 * @param format pointer to an OH_AVFormat instance 263 * @param key read key value 264 * @param out read data 265 * @return The return value is TRUE for success, FALSE for failure 266 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 267 * 4. out is nullptr. 268 * @since 9 269 * @version 1.0 270 */ 271 bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, float *out); 272 273 /** 274 * @brief Read Double data from OH_AVFormat 275 * @syscap SystemCapability.Multimedia.Media.Core 276 * @param format pointer to an OH_AVFormat instance 277 * @param key read key value 278 * @param out read data 279 * @return The return value is TRUE for success, FALSE for failure 280 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 281 * 4. out is nullptr. 282 * @since 9 283 * @version 1.0 284 */ 285 bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, double *out); 286 287 /** 288 * @brief Read String data from OH_AVFormat 289 * @syscap SystemCapability.Multimedia.Media.Core 290 * @param format pointer to an OH_AVFormat instance 291 * @param key read key value 292 * @param out The read string pointer, the data life cycle pointed to is updated with GetString, 293 * and Format is destroyed. If the caller needs to hold it for a long time, it must copy the memory 294 * @return The return value is TRUE for success, FALSE for failure 295 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 296 * 4. out is nullptr. 5. malloc out string nullptr. 297 * @since 9 298 * @version 1.0 299 */ 300 bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, const char **out); 301 302 /** 303 * @brief Read a block of data of specified length from OH_AVFormat 304 * @syscap SystemCapability.Multimedia.Media.Core 305 * @param format pointer to an OH_AVFormat instance 306 * @param key Key value for reading and writing data 307 * @param addr The life cycle is held by the format, with the destruction of the format, 308 * if the caller needs to hold it for a long time, it must copy the memory 309 * @param size Length of read and write data 310 * @return The return value is TRUE for success, FALSE for failure 311 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 312 * 4. addr is nullptr. 5. size is nullptr. 313 * @since 9 314 * @version 1.0 315 */ 316 bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size); 317 318 /** 319 * @brief Output the information contained in OH_AVFormat as a string. 320 * @syscap SystemCapability.Multimedia.Media.Core 321 * @param format pointer to an OH_AVFormat instance 322 * @return Returns a string consisting of key and data for success, nullptr for failure 323 * Possible failure causes: 1. input format is nullptr. 2. malloc dump info nullptr. 324 * @since 9 325 * @version 1.0 326 */ 327 const char *OH_AVFormat_DumpInfo(struct OH_AVFormat *format); 328 329 /** 330 * @brief Read an array of int32_t values from an OH_AVFormat object. 331 * 332 * Note that the obtained buffer's lifetime bound to the OH_AVFormat object, 333 * it's automatically invalidated when the format object is destroyed.\n 334 * Applications must explicitly copy the data to newly allocated memory if 335 * the data needs to outlive the OH_AVFormat instance.\n 336 * 337 * @syscap SystemCapability.Multimedia.Media.Core 338 * @param format pointer to an OH_AVFormat instance 339 * @param key Data identifier key 340 * @param addr Pointer to receive the data buffer reference 341 * @param size Pointer to receive the element count 342 * @return The return value is TRUE for success, FALSE for failure 343 * Possible failure causes: 344 * 1. input format is nullptr. 345 * 2. input format's magic error. 346 * 3. key is nullptr. 347 * 4. addr is nullptr. 348 * 5. size is nullptr. 349 * @since 20 350 */ 351 bool OH_AVFormat_GetIntBuffer(struct OH_AVFormat *format, const char *key, int32_t **addr, size_t *size); 352 353 /** 354 * @brief Write an array of int32_t values to an OH_AVFormat object. 355 * 356 * @syscap SystemCapability.Multimedia.Media.Core 357 * @param format pointer to an OH_AVFormat instance 358 * @param key Data identifier key 359 * @param addr Pointer to the source data buffer 360 * @param size Number of elements to write (in elements, not bytes) 361 * @return The return value is TRUE for success, FALSE for failure 362 * Possible failure causes: 363 * 1. input format is nullptr. 364 * 2. input format's magic error. 365 * 3. key is nullptr. 366 * 4. addr is nullptr. 367 * 5. size is zero. 368 * @since 20 369 */ 370 bool OH_AVFormat_SetIntBuffer(struct OH_AVFormat *format, const char *key, const int32_t *addr, size_t size); 371 372 #ifdef __cplusplus 373 } 374 #endif 375 376 #endif // NATIVE_AVFORMAT_H 377 /** @} */