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