1 /* 2 * Copyright (C) 2024 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 image 18 * @{ 19 * 20 * @brief Provides APIs for obtaining picture data and information. 21 * 22 * @Syscap SystemCapability.Multimedia.Image.Core 23 * @since 13 24 */ 25 26 /** 27 * @file picture_native.h 28 * 29 * @brief Declares the APIs that can access a picture. 30 * 31 * @library libpicture.so 32 * @kit ImageKit 33 * @Syscap SystemCapability.Multimedia.Image.Core 34 * @since 13 35 */ 36 #ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_PICTURE_NATIVE_H_ 37 #define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_PICTURE_NATIVE_H_ 38 #include "image_common.h" 39 #include "pixelmap_native.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Define a Picture struct type, used for picture pointer controls. 47 * 48 * @since 13 49 */ 50 struct OH_PictureNative; 51 52 /** 53 * @brief Define a Picture struct type, used for picture pointer controls. 54 * 55 * @since 13 56 */ 57 typedef struct OH_PictureNative OH_PictureNative; 58 59 /** 60 * @brief Define a AuxiliaryPicture struct type, used for auxiliary 61 * picture pointer controls. 62 * 63 * @since 13 64 */ 65 struct OH_AuxiliaryPictureNative; 66 67 /** 68 * @brief Define a AuxiliaryPicture struct type, used for auxiliary 69 * picture pointer controls. 70 * 71 * @since 13 72 */ 73 typedef struct OH_AuxiliaryPictureNative OH_AuxiliaryPictureNative; 74 75 /** 76 * @brief Define a AuxiliaryPictureInfo struct type, used for auxiliary 77 * picture info controls. 78 * 79 * @since 13 80 */ 81 struct OH_AuxiliaryPictureInfo; 82 83 /** 84 * @brief Define a AuxiliaryPictureInfo struct type, used for auxiliary 85 * picture info controls. 86 * 87 * @since 13 88 */ 89 typedef struct OH_AuxiliaryPictureInfo OH_AuxiliaryPictureInfo; 90 91 /** 92 * @brief Define a auxiliary picture type. 93 * 94 * @since 13 95 */ 96 typedef enum { 97 /* 98 * Gainmap 99 */ 100 AUXILIARY_PICTURE_TYPE_GAINMAP = 1, 101 /* 102 * Depth map 103 */ 104 AUXILIARY_PICTURE_TYPE_DEPTH_MAP = 2, 105 /* 106 * Unrefocus map 107 */ 108 AUXILIARY_PICTURE_TYPE_UNREFOCUS_MAP = 3, 109 /* 110 * Linear map 111 */ 112 AUXILIARY_PICTURE_TYPE_LINEAR_MAP = 4, 113 /* 114 * Fragment map 115 */ 116 AUXILIARY_PICTURE_TYPE_FRAGMENT_MAP = 5, 117 } Image_AuxiliaryPictureType; 118 119 /** 120 * @brief Create a <b>Picture</b> object. 121 * 122 * @param mainPixelmap The pixel map of the main image. 123 * @param picture Picture pointer for created. 124 * @return Image functions result code. 125 * {@link IMAGE_SUCCESS} if the execution is successful. 126 * {@link IMAGE_BAD_PARAMETER} mainPixelmap is nullptr, or picture is nullptr. 127 * @since 13 128 */ 129 Image_ErrorCode OH_PictureNative_CreatePicture(OH_PixelmapNative *mainPixelmap, OH_PictureNative **picture); 130 131 /** 132 * @brief Obtains the pixel map of the main image. 133 * 134 * @param picture The Picture pointer will be operated. 135 * @param mainPixelmap Main pixel map pointer for obtained. 136 * @return Image functions result code. 137 * {@link IMAGE_SUCCESS} if the execution is successful. 138 * {@link IMAGE_BAD_PARAMETER} picture is nullptr, or mainPixelmap is nullptr. 139 * @since 13 140 */ 141 Image_ErrorCode OH_PictureNative_GetMainPixelmap(OH_PictureNative *picture, OH_PixelmapNative **mainPixelmap); 142 143 /** 144 * @brief Obtains the hdr pixel map. 145 * 146 * @param picture The Picture pointer will be operated. 147 * @param hdrPixelmap Hdr pixel map pointer for obtained. 148 * @return Image functions result code. 149 * {@link IMAGE_SUCCESS} if the execution is successful. 150 * {@link IMAGE_BAD_PARAMETER} picture is nullptr, or hdrPixelmap is nullptr. 151 * {@link IMAGE_UNSUPPORTED_OPERATION} Unsupported operation, e.g. the picture does not has a gainmap 152 * @since 13 153 */ 154 Image_ErrorCode OH_PictureNative_GetHdrComposedPixelmap(OH_PictureNative *picture, OH_PixelmapNative **hdrPixelmap); 155 156 /** 157 * @brief Obtains the gainmap pixel map. 158 * 159 * @param picture The Picture pointer will be operated. 160 * @param gainmapPixelmap Gainmap pointer for obtained. 161 * @return Image functions result code. 162 * {@link IMAGE_SUCCESS} if the execution is successful. 163 * {@link IMAGE_BAD_PARAMETER} picture is nullptr, or gainmapPixelmap is nullptr. 164 * @since 13 165 */ 166 Image_ErrorCode OH_PictureNative_GetGainmapPixelmap(OH_PictureNative *picture, OH_PixelmapNative **gainmapPixelmap); 167 168 /** 169 * @brief Set auxiliary picture. 170 * 171 * @param picture The Picture pointer will be operated. 172 * @param type The type of auxiliary picture. 173 * @param auxiliaryPicture AuxiliaryPicture object. 174 * @return Image functions result code. 175 * {@link IMAGE_SUCCESS} if the execution is successful. 176 * {@link IMAGE_BAD_PARAMETER} picture is nullptr, or auxiliaryPicture is nullptr, or the type is invalid. 177 * @since 13 178 */ 179 Image_ErrorCode OH_PictureNative_SetAuxiliaryPicture(OH_PictureNative *picture, Image_AuxiliaryPictureType type, 180 OH_AuxiliaryPictureNative *auxiliaryPicture); 181 182 /** 183 * @brief Obtains the auxiliary picture based on type. 184 * 185 * @param picture The Picture pointer will be operated. 186 * @param type The type of auxiliary picture. 187 * @param auxiliaryPicture AuxiliaryPicture pointer for obtained. 188 * @return Image functions result code. 189 * {@link IMAGE_SUCCESS} if the execution is successful. 190 * {@link IMAGE_BAD_PARAMETER} picture is nullptr, or auxiliaryPicture is nullptr, or the type is invalid. 191 * @since 13 192 */ 193 Image_ErrorCode OH_PictureNative_GetAuxiliaryPicture(OH_PictureNative *picture, Image_AuxiliaryPictureType type, 194 OH_AuxiliaryPictureNative **auxiliaryPicture); 195 196 /** 197 * @brief Obtains the metadata of main picture. 198 * 199 * @param picture The Picture pointer will be operated. 200 * @param metadataType The type of metadata. 201 * @param metadata The metadata of main picture. 202 * @return Image functions result code. 203 * {@link IMAGE_SUCCESS} if the execution is successful. 204 * {@link IMAGE_BAD_PARAMETER} picture is nullptr, or metadata is nullptr. 205 * {@link IMAGE_UNSUPPORTED_METADATA} unsupported metadata type. 206 * @since 13 207 */ 208 Image_ErrorCode OH_PictureNative_GetMetadata(OH_PictureNative *picture, Image_MetadataType metadataType, 209 OH_PictureMetadata **metadata); 210 211 /** 212 * @brief Set main picture metadata. 213 * 214 * @param picture The Picture pointer will be operated. 215 * @param metadataType The type of metadata. 216 * @param metadata The metadata will be set. 217 * @return Image functions result code. 218 * {@link IMAGE_SUCCESS} if the execution is successful. 219 * {@link IMAGE_BAD_PARAMETER} picture is nullptr, or metadata is nullptr. 220 * {@link IMAGE_UNSUPPORTED_METADATA} unsupported metadata type. 221 * @since 13 222 */ 223 Image_ErrorCode OH_PictureNative_SetMetadata(OH_PictureNative *picture, Image_MetadataType metadataType, 224 OH_PictureMetadata *metadata); 225 226 /** 227 * @brief Releases this Picture object. 228 * 229 * @param picture The Picture pointer will be operated. 230 * @return Image functions result code. 231 * {@link IMAGE_SUCCESS} if the execution is successful. 232 * {@link IMAGE_BAD_PARAMETER} picture is nullptr. 233 * @since 13 234 */ 235 Image_ErrorCode OH_PictureNative_Release(OH_PictureNative *picture); 236 237 /** 238 * @brief Create a <b>AuxiliaryPicture</b> object. 239 * 240 * @param data The image data buffer. 241 * @param dataLength The length of data. 242 * @param size The size of auxiliary picture. 243 * @param type The type of auxiliary picture. 244 * @param auxiliaryPicture AuxiliaryPicture pointer for created. 245 * @return Image functions result code. 246 * {@link IMAGE_SUCCESS} if the execution is successful. 247 * {@link IMAGE_BAD_PARAMETER} data is nullptr, or dataLength is invalid, or size is nullptr, or the type 248 * is invalid, or auxiliaryPicture is nullptr. 249 * @since 13 250 */ 251 Image_ErrorCode OH_AuxiliaryPictureNative_Create(uint8_t *data, size_t dataLength, Image_Size *size, 252 Image_AuxiliaryPictureType type, OH_AuxiliaryPictureNative **auxiliaryPicture); 253 254 /** 255 * @brief Write pixels to auxiliary picture. 256 * 257 * @param auxiliaryPicture The AuxiliaryPicture pointer will be operated. 258 * @param source The pixels will be written. 259 * @param bufferSize The size of pixels. 260 * @return Image functions result code. 261 * {@link IMAGE_SUCCESS} if the execution is successful. 262 * {@link IMAGE_BAD_PARAMETER} auxiliaryPicture is nullptr, or source is nullptr, or the bufferSize is invalid. 263 * {@link IMAGE_ALLOC_FAILED} memory alloc failed. 264 * {@link IMAGE_COPY_FAILED} memory copy failed. 265 * @since 13 266 */ 267 Image_ErrorCode OH_AuxiliaryPictureNative_WritePixels(OH_AuxiliaryPictureNative *auxiliaryPicture, uint8_t *source, 268 size_t bufferSize); 269 270 /** 271 * @brief Read pixels from auxiliary picture. 272 * 273 * @param auxiliaryPicture The AuxiliaryPicture pointer will be operated. 274 * @param destination The pixels will be read. 275 * @param bufferSize The size of pixels for reading. 276 * @return Image functions result code. 277 * {@link IMAGE_SUCCESS} if the execution is successful. 278 * {@link IMAGE_BAD_PARAMETER} auxiliaryPicture is nullptr, or destination is nullptr, 279 * or the bufferSize is invalid. 280 * {@link IMAGE_ALLOC_FAILED} memory alloc failed. 281 * {@link IMAGE_COPY_FAILED} memory copy failed. 282 * @since 13 283 */ 284 Image_ErrorCode OH_AuxiliaryPictureNative_ReadPixels(OH_AuxiliaryPictureNative *auxiliaryPicture, uint8_t *destination, 285 size_t *bufferSize); 286 287 /** 288 * @brief Obtains the type of auxiliary picture. 289 * 290 * @param auxiliaryPicture The AuxiliaryPicture pointer will be operated. 291 * @param type The type of auxiliary picture. 292 * @return Image functions result code. 293 * {@link IMAGE_SUCCESS} if the execution is successful. 294 * {@link IMAGE_BAD_PARAMETER} auxiliaryPicture is nullptr, or type is nullptr. 295 * @since 13 296 */ 297 Image_ErrorCode OH_AuxiliaryPictureNative_GetType(OH_AuxiliaryPictureNative *auxiliaryPicture, 298 Image_AuxiliaryPictureType *type); 299 300 /** 301 * @brief Obtains the info of auxiliary picture. 302 * 303 * @param auxiliaryPicture The AuxiliaryPicture pointer will be operated. 304 * @param info The info of auxiliary picture. 305 * @return Image functions result code. 306 * {@link IMAGE_SUCCESS} if the execution is successful. 307 * {@link IMAGE_BAD_PARAMETER} auxiliaryPicture is nullptr, or info is nullptr. 308 * @since 13 309 */ 310 Image_ErrorCode OH_AuxiliaryPictureNative_GetInfo(OH_AuxiliaryPictureNative *auxiliaryPicture, 311 OH_AuxiliaryPictureInfo **info); 312 313 /** 314 * @brief Set auxiliary picture info. 315 * 316 * @param auxiliaryPicture The AuxiliaryPicture pointer will be operated. 317 * @param info The info will be set. 318 * @return Image functions result code. 319 * {@link IMAGE_SUCCESS} if the execution is successful. 320 * {@link IMAGE_BAD_PARAMETER} auxiliaryPicture is nullptr, or info is nullptr. 321 * @since 13 322 */ 323 Image_ErrorCode OH_AuxiliaryPictureNative_SetInfo(OH_AuxiliaryPictureNative *auxiliaryPicture, 324 OH_AuxiliaryPictureInfo *info); 325 326 /** 327 * @brief Obtains the metadata of auxiliary picture. 328 * 329 * @param auxiliaryPicture The AuxiliaryPicture pointer will be operated. 330 * @param metadataType The type of metadata. 331 * @param metadata The metadata of auxiliary picture. 332 * @return Image functions result code. 333 * {@link IMAGE_SUCCESS} if the execution is successful. 334 * {@link IMAGE_BAD_PARAMETER} auxiliaryPicture is nullptr, or metadata is nullptr. 335 * {@link IMAGE_UNSUPPORTED_METADATA} unsupported metadata type, or the metadata type does not match the 336 * auxiliary picture type. 337 * @since 13 338 */ 339 Image_ErrorCode OH_AuxiliaryPictureNative_GetMetadata(OH_AuxiliaryPictureNative *auxiliaryPicture, 340 Image_MetadataType metadataType, OH_PictureMetadata **metadata); 341 342 /** 343 * @brief Set auxiliary picture metadata. 344 * 345 * @param auxiliaryPicture The AuxiliaryPicture pointer will be operated. 346 * @param metadataType The type of metadata. 347 * @param metadata The metadata will be set. 348 * @return Image functions result code. 349 * {@link IMAGE_SUCCESS} if the execution is successful. 350 * {@link IMAGE_BAD_PARAMETER} auxiliaryPicture is nullptr, or metadata is nullptr. 351 * {@link IMAGE_UNSUPPORTED_METADATA} unsupported metadata type, or the metadata type does not match the 352 * auxiliary picture type. 353 * @since 13 354 */ 355 Image_ErrorCode OH_AuxiliaryPictureNative_SetMetadata(OH_AuxiliaryPictureNative *auxiliaryPicture, 356 Image_MetadataType metadataType, OH_PictureMetadata *metadata); 357 358 /** 359 * @brief Releases this AuxiliaryPicture object. 360 * 361 * @param picture The Picture pointer will be operated. 362 * @return Image functions result code. 363 * {@link IMAGE_SUCCESS} if the execution is successful. 364 * {@link IMAGE_BAD_PARAMETER} picture is nullptr. 365 * @since 13 366 */ 367 Image_ErrorCode OH_AuxiliaryPictureNative_Release(OH_AuxiliaryPictureNative *picture); 368 369 /** 370 * @brief Create a <b>AuxiliaryPictureInfo</b> object. 371 * 372 * @param info The AuxiliaryPictureInfo pointer will be operated. 373 * @return Image functions result code. 374 * {@link IMAGE_SUCCESS} if the execution is successful. 375 * {@link IMAGE_BAD_PARAMETER} info is nullptr. 376 * @since 13 377 */ 378 Image_ErrorCode OH_AuxiliaryPictureInfo_Create(OH_AuxiliaryPictureInfo **info); 379 380 /** 381 * @brief Obtains the type of auxiliary picture info. 382 * 383 * @param info The AuxiliaryPictureInfo pointer will be operated. 384 * @param type The type of auxiliary picture info. 385 * @return Image functions result code. 386 * {@link IMAGE_SUCCESS} if the execution is successful. 387 * {@link IMAGE_BAD_PARAMETER} info is nullptr, or type is nullptr. 388 * @since 13 389 */ 390 Image_ErrorCode OH_AuxiliaryPictureInfo_GetType(OH_AuxiliaryPictureInfo *info, Image_AuxiliaryPictureType *type); 391 392 /** 393 * @brief Set auxiliary picture info type. 394 * 395 * @param info The AuxiliaryPictureInfo pointer will be operated. 396 * @param type The type will be set. 397 * @return Image functions result code. 398 * {@link IMAGE_SUCCESS} if the execution is successful. 399 * {@link IMAGE_BAD_PARAMETER} info is nullptr, or type is invalid. 400 * @since 13 401 */ 402 Image_ErrorCode OH_AuxiliaryPictureInfo_SetType(OH_AuxiliaryPictureInfo *info, Image_AuxiliaryPictureType type); 403 404 /** 405 * @brief Obtains the size of auxiliary picture info. 406 * 407 * @param info The AuxiliaryPictureInfo pointer will be operated. 408 * @param size The size of auxiliary picture info. 409 * @return Image functions result code. 410 * {@link IMAGE_SUCCESS} if the execution is successful. 411 * {@link IMAGE_BAD_PARAMETER} info is nullptr, or size is nullptr. 412 * @since 13 413 */ 414 Image_ErrorCode OH_AuxiliaryPictureInfo_GetSize(OH_AuxiliaryPictureInfo *info, Image_Size *size); 415 416 /** 417 * @brief Set auxiliary picture info size. 418 * 419 * @param info The AuxiliaryPictureInfo pointer will be operated. 420 * @param size The size will be set. 421 * @return Image functions result code. 422 * {@link IMAGE_SUCCESS} if the execution is successful. 423 * {@link IMAGE_BAD_PARAMETER} info is nullptr, or size is nullptr. 424 * @since 13 425 */ 426 Image_ErrorCode OH_AuxiliaryPictureInfo_SetSize(OH_AuxiliaryPictureInfo *info, Image_Size *size); 427 428 /** 429 * @brief Obtains the rowStride of auxiliary picture info. 430 * 431 * @param info The AuxiliaryPictureInfo pointer will be operated. 432 * @param rowStride The rowStride of auxiliary picture info. 433 * @return Image functions result code. 434 * {@link IMAGE_SUCCESS} if the execution is successful. 435 * {@link IMAGE_BAD_PARAMETER} info is nullptr, or rowStride is nullptr. 436 * @since 13 437 */ 438 Image_ErrorCode OH_AuxiliaryPictureInfo_GetRowStride(OH_AuxiliaryPictureInfo *info, uint32_t *rowStride); 439 440 /** 441 * @brief Set auxiliary picture info rowStride. 442 * 443 * @param info The AuxiliaryPictureInfo pointer will be operated. 444 * @param rowStride The rowStride will be set. 445 * @return Image functions result code. 446 * {@link IMAGE_SUCCESS} if the execution is successful. 447 * {@link IMAGE_BAD_PARAMETER} info is nullptr, or rowStride is nullptr. 448 * @since 13 449 */ 450 Image_ErrorCode OH_AuxiliaryPictureInfo_SetRowStride(OH_AuxiliaryPictureInfo *info, uint32_t rowStride); 451 452 /** 453 * @brief Obtains the pixelFormat of auxiliary picture info. 454 * 455 * @param info The AuxiliaryPictureInfo pointer will be operated. 456 * @param pixelFormat The pixelFormat will be get. 457 * @return Image functions result code. 458 * {@link IMAGE_SUCCESS} if the execution is successful. 459 * {@link IMAGE_BAD_PARAMETER} info is nullptr, or pixelFormat is nullptr. 460 * @since 13 461 */ 462 Image_ErrorCode OH_AuxiliaryPictureInfo_GetPixelFormat(OH_AuxiliaryPictureInfo *info, PIXEL_FORMAT *pixelFormat); 463 464 /** 465 * @brief Set auxiliary picture info pixelFormat. 466 * 467 * @param info The AuxiliaryPictureInfo pointer will be operated. 468 * @param pixelFormat The pixelFormat will be set. 469 * @return Image functions result code. 470 * {@link IMAGE_SUCCESS} if the execution is successful. 471 * {@link IMAGE_BAD_PARAMETER} info is nullptr. 472 * @since 13 473 */ 474 Image_ErrorCode OH_AuxiliaryPictureInfo_SetPixelFormat(OH_AuxiliaryPictureInfo *info, PIXEL_FORMAT pixelFormat); 475 476 /** 477 * @brief Releases this AuxiliaryPictureInfo object. 478 * 479 * @param info The AuxiliaryPictureInfo pointer will be operated. 480 * @return Image functions result code. 481 * {@link IMAGE_SUCCESS} if the execution is successful. 482 * {@link IMAGE_BAD_PARAMETER} info is nullptr. 483 * @since 13 484 */ 485 Image_ErrorCode OH_AuxiliaryPictureInfo_Release(OH_AuxiliaryPictureInfo *info); 486 487 #ifdef __cplusplus 488 }; 489 #endif 490 /** @} */ 491 #endif //INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_PICTURE_NATIVE_H_