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_avformat.h 18 * 19 * @brief Provides audio and video format. 20 * 21 * @kit AVCodecKit 22 * @library libnative_media_core.so 23 * @syscap SystemCapability.Multimedia.Media.Core 24 * @since 9 25 */ 26 27 #ifndef NATIVE_AVFORMAT_H 28 #define NATIVE_AVFORMAT_H 29 30 #include <stdint.h> 31 #include <stdbool.h> 32 #include <stdio.h> 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * @brief Forward declaration of OH_AVFormat. 40 * 41 * @since 9 42 */ 43 typedef struct OH_AVFormat OH_AVFormat; 44 45 /** 46 * @brief Enumerates AVPixel Format. 47 * @syscap SystemCapability.Multimedia.Media.Core 48 * @since 9 49 * @version 1.0 50 */ 51 typedef enum OH_AVPixelFormat { 52 /** 53 * yuv 420 planar. 54 */ 55 AV_PIXEL_FORMAT_YUVI420 = 1, 56 /** 57 * NV12. yuv 420 semiplanar. 58 */ 59 AV_PIXEL_FORMAT_NV12 = 2, 60 /** 61 * NV21. yvu 420 semiplanar. 62 */ 63 AV_PIXEL_FORMAT_NV21 = 3, 64 /** 65 * format from surface. 66 */ 67 AV_PIXEL_FORMAT_SURFACE_FORMAT = 4, 68 /** 69 * RGBA8888 70 */ 71 AV_PIXEL_FORMAT_RGBA = 5, 72 } OH_AVPixelFormat; 73 74 /** 75 * @briefCreate an OH_AVFormat handle pointer to read and write data 76 * @syscap SystemCapability.Multimedia.Media.Core 77 * @return Returns a pointer to an OH_AVFormat instance 78 * @since 9 79 * @version 1.0 80 */ 81 struct OH_AVFormat *OH_AVFormat_Create(void); 82 83 /** 84 * @briefCreate an audio OH_AVFormat handle pointer to read and write data 85 * @syscap SystemCapability.Multimedia.Media.Core 86 * @param mimeType mime type 87 * @param sampleRate sample rate 88 * @param channelCount channel count 89 * @return Returns a pointer to an OH_AVFormat instance if the execution is successful, otherwise nullptr 90 * Possible failure causes: 1. mimeType is nullptr. 2. new format is nullptr. 91 * @since 10 92 * @version 1.0 93 */ 94 struct OH_AVFormat *OH_AVFormat_CreateAudioFormat(const char *mimeType, 95 int32_t sampleRate, 96 int32_t channelCount); 97 98 /** 99 * @briefCreate an video OH_AVFormat handle pointer to read and write data 100 * @syscap SystemCapability.Multimedia.Media.Core 101 * @param mimeType mime type 102 * @param width width 103 * @param height height 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_CreateVideoFormat(const char *mimeType, 110 int32_t width, 111 int32_t height); 112 113 /** 114 * @brief Destroy the specified OH_AVFormat handle resource 115 * @syscap SystemCapability.Multimedia.Media.Core 116 * @param format pointer to an OH_AVFormat instance 117 * @return void 118 * @since 9 119 * @version 1.0 120 */ 121 void OH_AVFormat_Destroy(struct OH_AVFormat *format); 122 123 /** 124 * @brief Copy OH_AVFormat handle resource 125 * @syscap SystemCapability.Multimedia.Media.Core 126 * @param to OH_AVFormat handle pointer to receive data 127 * @param from pointer to the OH_AVFormat handle of the copied data 128 * @return The return value is TRUE for success, FALSE for failure 129 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 130 * @since 9 131 * @version 1.0 132 */ 133 bool OH_AVFormat_Copy(struct OH_AVFormat *to, struct OH_AVFormat *from); 134 135 /** 136 * @brief Write Int data to OH_AVFormat 137 * @syscap SystemCapability.Multimedia.Media.Core 138 * @param format pointer to an OH_AVFormat instance 139 * @param key key to write data 140 * @param value written data 141 * @return The return value is TRUE for success, FALSE for failure 142 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 143 * @since 9 144 * @version 1.0 145 */ 146 bool OH_AVFormat_SetIntValue(struct OH_AVFormat *format, const char *key, int32_t value); 147 148 /** 149 * @brief Write Long data to OH_AVFormat 150 * @syscap SystemCapability.Multimedia.Media.Core 151 * @param format pointer to an OH_AVFormat instance 152 * @param key key to write data 153 * @param value written data 154 * @return The return value is TRUE for success, FALSE for failure 155 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 156 * @since 9 157 * @version 1.0 158 */ 159 bool OH_AVFormat_SetLongValue(struct OH_AVFormat *format, const char *key, int64_t value); 160 161 /** 162 * @brief Write Float data to OH_AVFormat 163 * @syscap SystemCapability.Multimedia.Media.Core 164 * @param format pointer to an OH_AVFormat instance 165 * @param key key to write data 166 * @param value written data 167 * @return The return value is TRUE for success, FALSE for failure 168 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 169 * @since 9 170 * @version 1.0 171 */ 172 bool OH_AVFormat_SetFloatValue(struct OH_AVFormat *format, const char *key, float value); 173 174 /** 175 * @brief Write Double data to OH_AVFormat 176 * @syscap SystemCapability.Multimedia.Media.Core 177 * @param format pointer to an OH_AVFormat instance 178 * @param key key to write data 179 * @param value written data 180 * @return The return value is TRUE for success, FALSE for failure 181 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 182 * @since 9 183 * @version 1.0 184 */ 185 bool OH_AVFormat_SetDoubleValue(struct OH_AVFormat *format, const char *key, double value); 186 187 /** 188 * @brief Write String data to OH_AVFormat 189 * @syscap SystemCapability.Multimedia.Media.Core 190 * @param format pointer to an OH_AVFormat instance 191 * @param key key to write data 192 * @param value written data 193 * @return The return value is TRUE for success, FALSE for failure 194 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 195 * 4. value is nullptr. 196 * @since 9 197 * @version 1.0 198 */ 199 bool OH_AVFormat_SetStringValue(struct OH_AVFormat *format, const char *key, const char *value); 200 201 /** 202 * @brief Write a block of data of a specified length to OH_AVFormat 203 * @syscap SystemCapability.Multimedia.Media.Core 204 * @param format pointer to an OH_AVFormat instance 205 * @param key key to write data 206 * @param addr written data addr 207 * @param size written data length 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. addr is nullptr. 5. size is zero. 211 * @since 9 212 * @version 1.0 213 */ 214 bool OH_AVFormat_SetBuffer(struct OH_AVFormat *format, const char *key, const uint8_t *addr, size_t size); 215 216 /** 217 * @brief Read Int data from OH_AVFormat 218 * @syscap SystemCapability.Multimedia.Media.Core 219 * @param format pointer to an OH_AVFormat instance 220 * @param key read key value 221 * @param out read data 222 * @return The return value is TRUE for success, FALSE for failure 223 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 224 * 4. out is nullptr. 225 * @since 9 226 * @version 1.0 227 */ 228 bool OH_AVFormat_GetIntValue(struct OH_AVFormat *format, const char *key, int32_t *out); 229 230 /** 231 * @brief Read Long data from OH_AVFormat 232 * @syscap SystemCapability.Multimedia.Media.Core 233 * @param format pointer to an OH_AVFormat instance 234 * @param key read key value 235 * @param out read data 236 * @return The return value is TRUE for success, FALSE for failure 237 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 238 * 4. out is nullptr. 239 * @since 9 240 * @version 1.0 241 */ 242 bool OH_AVFormat_GetLongValue(struct OH_AVFormat *format, const char *key, int64_t *out); 243 244 /** 245 * @brief Read Float data from OH_AVFormat 246 * @syscap SystemCapability.Multimedia.Media.Core 247 * @param format pointer to an OH_AVFormat instance 248 * @param key read key value 249 * @param out read data 250 * @return The return value is TRUE for success, FALSE for failure 251 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 252 * 4. out is nullptr. 253 * @since 9 254 * @version 1.0 255 */ 256 bool OH_AVFormat_GetFloatValue(struct OH_AVFormat *format, const char *key, float *out); 257 258 /** 259 * @brief Read Double data from OH_AVFormat 260 * @syscap SystemCapability.Multimedia.Media.Core 261 * @param format pointer to an OH_AVFormat instance 262 * @param key read key value 263 * @param out read data 264 * @return The return value is TRUE for success, FALSE for failure 265 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 266 * 4. out is nullptr. 267 * @since 9 268 * @version 1.0 269 */ 270 bool OH_AVFormat_GetDoubleValue(struct OH_AVFormat *format, const char *key, double *out); 271 272 /** 273 * @brief Read String data from OH_AVFormat 274 * @syscap SystemCapability.Multimedia.Media.Core 275 * @param format pointer to an OH_AVFormat instance 276 * @param key read key value 277 * @param out The read string pointer, the data life cycle pointed to is updated with GetString, 278 * and Format is destroyed. If the caller needs to hold it for a long time, it must copy the memory 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. 5. malloc out string nullptr. 282 * @since 9 283 * @version 1.0 284 */ 285 bool OH_AVFormat_GetStringValue(struct OH_AVFormat *format, const char *key, const char **out); 286 287 /** 288 * @brief Read a block of data of specified length from OH_AVFormat 289 * @syscap SystemCapability.Multimedia.Media.Core 290 * @param format pointer to an OH_AVFormat instance 291 * @param key Key value for reading and writing data 292 * @param addr The life cycle is held by the format, with the destruction of the format, 293 * if the caller needs to hold it for a long time, it must copy the memory 294 * @param size Length of read and write data 295 * @return The return value is TRUE for success, FALSE for failure 296 * Possible failure causes: 1. input format is nullptr. 2. input format's magic error. 3. key is nullptr. 297 * 4. addr is nullptr. 5. size is nullptr. 298 * @since 9 299 * @version 1.0 300 */ 301 bool OH_AVFormat_GetBuffer(struct OH_AVFormat *format, const char *key, uint8_t **addr, size_t *size); 302 303 /** 304 * @brief Output the information contained in OH_AVFormat as a string. 305 * @syscap SystemCapability.Multimedia.Media.Core 306 * @param format pointer to an OH_AVFormat instance 307 * @return Returns a string consisting of key and data for success, nullptr for failure 308 * Possible failure causes: 1. input format is nullptr. 2. malloc dump info nullptr. 309 * @since 9 310 * @version 1.0 311 */ 312 const char *OH_AVFormat_DumpInfo(struct OH_AVFormat *format); 313 314 #ifdef __cplusplus 315 } 316 #endif 317 318 #endif // NATIVE_AVFORMAT_H