1/* 2* Copyright (C) 2021 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 16import { AsyncCallback } from './basic'; 17 18/** 19 * @name image 20 * @since 6 21 * @import import image from '@ohos.multimedia.image'; 22 */ 23declare namespace image { 24 25 /** 26 * Enumerates pixel map formats. 27 * @since 7 28 * @syscap SystemCapability.Multimedia.Image.Core 29 */ 30 enum PixelMapFormat { 31 /** 32 * Indicates an unknown format. 33 * @since 7 34 * @syscap SystemCapability.Multimedia.Image.Core 35 */ 36 UNKNOWN = 0, 37 38 /** 39 * Indicates that each pixel is stored on 16 bits. Only the R, G, and B components are encoded 40 * from the higher-order to the lower-order bits: red is stored with 5 bits of precision, 41 * green is stored with 6 bits of precision, and blue is stored with 5 bits of precision. 42 * @since 7 43 * @syscap SystemCapability.Multimedia.Image.Core 44 */ 45 RGB_565 = 2, 46 47 /** 48 * Indicates that each pixel is stored on 32 bits. Components R, G, B, and A each occupies 8 bits 49 * and are stored from the higher-order to the lower-order bits. 50 * @since 7 51 * @syscap SystemCapability.Multimedia.Image.Core 52 */ 53 RGBA_8888 = 3, 54 } 55 56 /** 57 * Describes the size of an image. 58 * @since 6 59 * @syscap SystemCapability.Multimedia.Image.Core 60 */ 61 interface Size { 62 /** 63 * Height 64 * @since 6 65 * @syscap SystemCapability.Multimedia.Image.Core 66 */ 67 height: number; 68 69 /** 70 * Width 71 * @since 6 72 * @syscap SystemCapability.Multimedia.Image.Core 73 */ 74 width: number; 75 } 76 77 /** 78 * Enumerates exchangeable image file format (Exif) information types of an image. 79 * @since 7 80 * @syscap SystemCapability.Multimedia.Image.Core 81 */ 82 enum PropertyKey { 83 /** 84 * Number of bits in each pixel of an image. 85 * @since 7 86 * @syscap SystemCapability.Multimedia.Image.Core 87 */ 88 BITS_PER_SAMPLE = "BitsPerSample", 89 90 /** 91 * Image rotation mode. 92 * @since 7 93 * @syscap SystemCapability.Multimedia.Image.Core 94 */ 95 ORIENTATION = "Orientation", 96 97 /** 98 * Image length. 99 * @since 7 100 * @syscap SystemCapability.Multimedia.Image.Core 101 */ 102 IMAGE_LENGTH = "ImageLength", 103 104 /** 105 * Image width. 106 * @since 7 107 * @syscap SystemCapability.Multimedia.Image.Core 108 */ 109 IMAGE_WIDTH = "ImageWidth", 110 111 /** 112 * GPS latitude. 113 * @since 7 114 * @syscap SystemCapability.Multimedia.Image.Core 115 */ 116 GPS_LATITUDE = "GPSLatitude", 117 118 /** 119 * GPS longitude. 120 * @since 7 121 * @syscap SystemCapability.Multimedia.Image.Core 122 */ 123 GPS_LONGITUDE = "GPSLongitude", 124 125 /** 126 * GPS latitude reference. For example, N indicates north latitude and S indicates south latitude. 127 * @since 7 128 * @syscap SystemCapability.Multimedia.Image.Core 129 */ 130 GPS_LATITUDE_REF = "GPSLatitudeRef", 131 132 /** 133 * GPS longitude reference. For example, E indicates east longitude and W indicates west longitude. 134 * @since 7 135 * @syscap SystemCapability.Multimedia.Image.Core 136 */ 137 GPS_LONGITUDE_REF = "GPSLongitudeRef" 138 } 139 140 /** 141 * Describes region information. 142 * @since 8 143 * @syscap SystemCapability.Multimedia.Image.Core 144 */ 145 interface Region { 146 /** 147 * Image size. 148 * @since 7 149 * @syscap SystemCapability.Multimedia.Image.Core 150 */ 151 size: Size; 152 153 /** 154 * x-coordinate at the upper left corner of the image. 155 * @since 7 156 * @syscap SystemCapability.Multimedia.Image.Core 157 */ 158 x: number; 159 160 /** 161 * y-coordinate at the upper left corner of the image. 162 * @since 7 163 * @syscap SystemCapability.Multimedia.Image.Core 164 */ 165 y: number; 166 } 167 168 /** 169 * Describes area information in an image. 170 * @since 7 171 * @syscap SystemCapability.Multimedia.Image.Core 172 */ 173 interface PositionArea { 174 /** 175 * Image data that will be read or written. 176 * @since 7 177 * @syscap SystemCapability.Multimedia.Image.Core 178 */ 179 pixels: ArrayBuffer; 180 181 /** 182 * Offset for data reading. 183 * @since 7 184 * @syscap SystemCapability.Multimedia.Image.Core 185 */ 186 offset: number; 187 188 /** 189 * Number of bytes to read. 190 * @since 7 191 * @syscap SystemCapability.Multimedia.Image.Core 192 */ 193 stride: number; 194 195 /** 196 * Region to read. 197 * @since 7 198 * @syscap SystemCapability.Multimedia.Image.Core 199 */ 200 region: Region; 201 } 202 203 /** 204 * Describes image information. 205 * @since 6 206 * @syscap SystemCapability.Multimedia.Image.Core 207 */ 208 interface ImageInfo { 209 /** 210 * Indicates image dimensions specified by a {@link Size} interface. 211 * @since 6 212 * @syscap SystemCapability.Multimedia.Image.Core 213 */ 214 size: Size; 215 } 216 217 /** 218 * Describes the option for image packing. 219 * @since 6 220 * @syscap SystemCapability.Multimedia.Image.ImagePacker 221 */ 222 interface PackingOption { 223 /** 224 * Multipurpose Internet Mail Extensions (MIME) format of the target image, for example, image/jpeg. 225 * @since 6 226 * @syscap SystemCapability.Multimedia.Image.ImagePacker 227 */ 228 format: string; 229 230 /** 231 * Quality of the target image. The value is an integer ranging from 0 to 100. A larger value indicates better 232 * image quality but larger space occupied. 233 * @since 6 234 * @syscap SystemCapability.Multimedia.Image.ImagePacker 235 */ 236 quality: number; 237 } 238 239 /** 240 * Describes image properties. 241 * @since 7 242 * @syscap SystemCapability.Multimedia.Image.ImageSource 243 */ 244 interface GetImagePropertyOptions { 245 /** 246 * Index of an image. 247 * @since 7 248 * @syscap SystemCapability.Multimedia.Image.ImageSource 249 */ 250 index?: number; 251 252 /** 253 * Default property value. 254 * @since 7 255 * @syscap SystemCapability.Multimedia.Image.ImageSource 256 */ 257 defaultValue?: string; 258 } 259 260 /** 261 * Describes image decoding parameters. 262 * @since 7 263 * @syscap SystemCapability.Multimedia.Image.ImageSource 264 */ 265 interface DecodingOptions { 266 /** 267 * Number of image frames. 268 * @since 7 269 * @syscap SystemCapability.Multimedia.Image.ImageSource 270 */ 271 index?: number; 272 273 /** 274 * Sampling ratio of the image pixel map. 275 * @since 7 276 * @syscap SystemCapability.Multimedia.Image.ImageSource 277 */ 278 sampleSize?: number; 279 280 /** 281 * Rotation angle of the image pixel map. The value ranges from 0 to 360. 282 * @since 7 283 * @syscap SystemCapability.Multimedia.Image.ImageSource 284 */ 285 rotate?: number; 286 287 /** 288 * Whether the image pixel map is editable. 289 * @since 7 290 * @syscap SystemCapability.Multimedia.Image.ImageSource 291 */ 292 editable?: boolean; 293 294 /** 295 * Width and height of the image pixel map. The value (0, 0) indicates that the pixels are decoded 296 * based on the original image size. 297 * @since 7 298 * @syscap SystemCapability.Multimedia.Image.ImageSource 299 */ 300 desiredSize?: Size; 301 302 /** 303 * Cropping region of the image pixel map. 304 * @since 7 305 * @syscap SystemCapability.Multimedia.Image.ImageSource 306 */ 307 desiredRegion?: Region; 308 309 /** 310 * Data format of the image pixel map. 311 * @since 7 312 * @syscap SystemCapability.Multimedia.Image.ImageSource 313 */ 314 desiredPixelFormat?: PixelMapFormat; 315 } 316 317 /** 318 * Initialization options for pixelmap. 319 * @since 8 320 * @syscap SystemCapability.Multimedia.Image.Core 321 */ 322 interface InitializationOptions { 323 /** 324 * PixelMap size. 325 * @since 8 326 * @syscap SystemCapability.Multimedia.Image.Core 327 */ 328 size: Size; 329 330 /** 331 * PixelMap expected format. 332 * @since 8 333 * @syscap SystemCapability.Multimedia.Image.Core 334 */ 335 pixelFormat?: PixelMapFormat; 336 337 /** 338 * Editable or not. 339 * @since 8 340 * @syscap SystemCapability.Multimedia.Image.Core 341 */ 342 editable?: boolean; 343 } 344 345 /** 346 * Create pixelmap by data buffer. 347 * @since 8 348 * @syscap SystemCapability.Multimedia.Image.Core 349 */ 350 function createPixelMap(colors: ArrayBuffer, options: InitializationOptions, callback: AsyncCallback<PixelMap>): void; 351 352 /** 353 * Create pixelmap by data buffer. 354 * @since 8 355 * @syscap SystemCapability.Multimedia.Image.Core 356 */ 357 function createPixelMap(colors: ArrayBuffer, options: InitializationOptions): Promise<PixelMap>; 358 359 /** 360 * Creates an ImageSource instance based on the URI. 361 * @since 6 362 * @syscap SystemCapability.Multimedia.Image.ImageSource 363 * @param uri Image source URI. 364 * @return Returns the ImageSource instance if the operation is successful; returns null otherwise. 365 */ 366 function createImageSource(uri: string): ImageSource; 367 368 /** 369 * Creates an ImageSource instance based on the file descriptor. 370 * @since 7 371 * @syscap SystemCapability.Multimedia.Image.ImageSource 372 * @param fd ID of a file descriptor. 373 * @return Returns the ImageSource instance if the operation is successful; returns null otherwise. 374 */ 375 function createImageSource(fd: number): ImageSource; 376 377 /** 378 * Creates an ImagePacker instance. 379 * @since 6 380 * @syscap SystemCapability.Multimedia.Image.ImagePacker 381 * @return Returns the ImagePacker instance if the operation is successful; returns null otherwise. 382 */ 383 function createImagePacker(): ImagePacker; 384 385 /** 386 * PixelMap instance. 387 * @since 7 388 * @syscap SystemCapability.Multimedia.Image.Core 389 */ 390 interface PixelMap { 391 /** 392 * Whether the image pixel map can be edited. 393 * @since 7 394 * @syscap SystemCapability.Multimedia.Image.Core 395 */ 396 readonly isEditable: boolean; 397 398 /** 399 * Reads image pixel map data and writes the data to an ArrayBuffer. This method uses 400 * a promise to return the result. 401 * @since 7 402 * @syscap SystemCapability.Multimedia.Image.Core 403 * @param dst A buffer to which the image pixel map data will be written. 404 * @return A Promise instance used to return the operation result. If the operation fails, an error message is returned. 405 */ 406 readPixelsToBuffer(dst: ArrayBuffer): Promise<void>; 407 408 /** 409 * Reads image pixel map data and writes the data to an ArrayBuffer. This method uses 410 * a callback to return the result. 411 * @since 7 412 * @syscap SystemCapability.Multimedia.Image.Core 413 * @param dst A buffer to which the image pixel map data will be written. 414 * @param callback Callback used to return the operation result. If the operation fails, an error message is returned. 415 */ 416 readPixelsToBuffer(dst: ArrayBuffer, callback: AsyncCallback<void>): void; 417 418 /** 419 * Reads image pixel map data in an area. This method uses a promise to return the data read. 420 * @since 7 421 * @syscap SystemCapability.Multimedia.Image.Core 422 * @param area Area from which the image pixel map data will be read. 423 * @return A Promise instance used to return the operation result. If the operation fails, an error message is returned. 424 */ 425 readPixels(area: PositionArea): Promise<void>; 426 427 /** 428 * Reads image pixel map data in an area. This method uses a callback to return the data read. 429 * @since 7 430 * @syscap SystemCapability.Multimedia.Image.Core 431 * @param area Area from which the image pixel map data will be read. 432 * @param callback Callback used to return the operation result. If the operation fails, an error message is returned. 433 */ 434 readPixels(area: PositionArea, callback: AsyncCallback<void>): void; 435 436 /** 437 * Writes image pixel map data to the specified area. This method uses a promise to return 438 * the operation result. 439 * @since 7 440 * @syscap SystemCapability.Multimedia.Image.Core 441 * @param area Area to which the image pixel map data will be written. 442 * @return A Promise instance used to return the operation result. If the operation fails, an error message is returned. 443 */ 444 writePixels(area: PositionArea): Promise<void>; 445 446 /** 447 * Writes image pixel map data to the specified area. This method uses a callback to return 448 * the operation result. 449 * @since 7 450 * @syscap SystemCapability.Multimedia.Image.Core 451 * @param area Area to which the image pixel map data will be written. 452 * @param callback Callback used to return the operation result. If the operation fails, an error message is returned. 453 */ 454 writePixels(area: PositionArea, callback: AsyncCallback<void>): void; 455 456 /** 457 * Reads image data in an ArrayBuffer and writes the data to a PixelMap object. This method 458 * uses a promise to return the result. 459 * @since 7 460 * @syscap SystemCapability.Multimedia.Image.Core 461 * @param src A buffer from which the image data will be read. 462 * @return A Promise instance used to return the operation result. If the operation fails, an error message is returned. 463 */ 464 writeBufferToPixels(src: ArrayBuffer): Promise<void>; 465 466 /** 467 * Reads image data in an ArrayBuffer and writes the data to a PixelMap object. This method 468 * uses a callback to return the result. 469 * @since 7 470 * @syscap SystemCapability.Multimedia.Image.Core 471 * @param src A buffer from which the image data will be read. 472 * @param callback Callback used to return the operation result. If the operation fails, an error message is returned. 473 */ 474 writeBufferToPixels(src: ArrayBuffer, callback: AsyncCallback<void>): void; 475 476 /** 477 * Obtains pixel map information about this image. This method uses a promise to return the information. 478 * @since 7 479 * @syscap SystemCapability.Multimedia.Image.Core 480 * @return A Promise instance used to return the image pixel map information. If the operation fails, an error message is returned. 481 */ 482 getImageInfo(): Promise<ImageInfo>; 483 484 /** 485 * Obtains pixel map information about this image. This method uses a callback to return the information. 486 * @since 7 487 * @syscap SystemCapability.Multimedia.Image.Core 488 * @param callback Callback used to return the image pixel map information. If the operation fails, an error message is returned. 489 */ 490 getImageInfo(callback: AsyncCallback<ImageInfo>): void; 491 492 /** 493 * Obtains the number of bytes in each line of the image pixel map. 494 * @since 7 495 * @syscap SystemCapability.Multimedia.Image.Core 496 * @return Number of bytes in each line. 497 */ 498 getBytesNumberPerRow(): number; 499 500 /** 501 * Obtains the total number of bytes of the image pixel map. 502 * @since 7 503 * @syscap SystemCapability.Multimedia.Image.Core 504 * @return Total number of bytes. 505 */ 506 getPixelBytesNumber(): number; 507 508 /** 509 * Releases this PixelMap object. This method uses a callback to return the result. 510 * @since 7 511 * @syscap SystemCapability.Multimedia.Image.Core 512 * @param callback Callback invoked for instance release. If the operation fails, an error message is returned. 513 */ 514 release(callback: AsyncCallback<void>): void; 515 516 /** 517 * Releases this PixelMap object. This method uses a promise to return the result. 518 * @since 7 519 * @syscap SystemCapability.Multimedia.Image.Core 520 * @return A Promise instance used to return the instance release result. If the operation fails, an error message is returned. 521 */ 522 release(): Promise<void>; 523 } 524 525 /** 526 * ImageSource instance. 527 * @since 6 528 * @syscap SystemCapability.Multimedia.Image.ImageSource 529 */ 530 interface ImageSource { 531 /** 532 * Obtains information about an image with the specified sequence number and uses a callback 533 * to return the result. 534 * @since 6 535 * @syscap SystemCapability.Multimedia.Image.ImageSource 536 * @param index Sequence number of an image. 537 * @param callback Callback used to return the image information. 538 */ 539 getImageInfo(index: number, callback: AsyncCallback<ImageInfo>): void; 540 541 /** 542 * Obtains information about this image and uses a callback to return the result. 543 * @since 6 544 * @syscap SystemCapability.Multimedia.Image.ImageSource 545 * @param callback Callback used to return the image information. 546 */ 547 getImageInfo(callback: AsyncCallback<ImageInfo>): void; 548 549 /** 550 * Get image information from image source. 551 * @since 6 552 * @syscap SystemCapability.Multimedia.Image.ImageSource 553 * @param index Sequence number of an image. If this parameter is not specified, the default value 0 is used. 554 * @return A Promise instance used to return the image information. 555 */ 556 getImageInfo(index?: number): Promise<ImageInfo>; 557 558 /** 559 * Creates a PixelMap object based on image decoding parameters. This method uses a promise to 560 * return the object. 561 * @since 7 562 * @syscap SystemCapability.Multimedia.Image.ImageSource 563 * @param options Image decoding parameters. 564 * @return A Promise instance used to return the PixelMap object. 565 */ 566 createPixelMap(options?: DecodingOptions): Promise<PixelMap>; 567 568 /** 569 * Creates a PixelMap object. This method uses a callback to return the object. 570 * @since 7 571 * @syscap SystemCapability.Multimedia.Image.ImageSource 572 * @param callback Callback used to return the PixelMap object. 573 */ 574 createPixelMap(callback: AsyncCallback<PixelMap>): void; 575 576 /** 577 * Creates a PixelMap object based on image decoding parameters. This method uses a callback to 578 * return the object. 579 * @since 7 580 * @syscap SystemCapability.Multimedia.Image.ImageSource 581 * @param options Image decoding parameters. 582 * @param callback Callback used to return the PixelMap object. 583 */ 584 createPixelMap(options: DecodingOptions, callback: AsyncCallback<PixelMap>): void; 585 586 /** 587 * Obtains the value of a property in an image with the specified index. This method uses a 588 * promise to return the property value in a string. 589 * @since 7 590 * @syscap SystemCapability.Multimedia.Image.ImageSource 591 * @param key Name of the property whose value is to be obtained. 592 * @param options Index of the image. 593 * @return A Promise instance used to return the property value. If the operation fails, the default value is returned. 594 */ 595 getImageProperty(key:string, options?: GetImagePropertyOptions): Promise<string>; 596 597 /** 598 * Obtains the value of a property in this image. This method uses a callback to return the 599 * property value in a string. 600 * @since 7 601 * @syscap SystemCapability.Multimedia.Image.ImageSource 602 * @param key Name of the property whose value is to be obtained. 603 * @param callback Callback used to return the property value. If the operation fails, an error message is returned. 604 */ 605 getImageProperty(key:string, callback: AsyncCallback<string>): void; 606 607 /** 608 * Obtains the value of a property in an image with the specified index. This method uses 609 * a callback to return the property value in a string. 610 * @since 7 611 * @syscap SystemCapability.Multimedia.Image.ImageSource 612 * @param key Name of the property whose value is to be obtained. 613 * @param options Index of the image. 614 * @param callback Callback used to return the property value. If the operation fails, the default value is returned. 615 */ 616 getImageProperty(key:string, options: GetImagePropertyOptions, callback: AsyncCallback<string>): void; 617 618 /** 619 * Releases an ImageSource instance and uses a callback to return the result. 620 * @since 6 621 * @syscap SystemCapability.Multimedia.Image.ImageSource 622 * @param callback Callback to return the operation result. 623 */ 624 release(callback: AsyncCallback<void>): void; 625 626 /** 627 * Releases an ImageSource instance and uses a promise to return the result. 628 * @since 6 629 * @syscap SystemCapability.Multimedia.Image.ImageSource 630 * @return A Promise instance used to return the operation result. 631 */ 632 release(): Promise<void>; 633 634 /** 635 * Supported image formats. 636 * @since 6 637 * @syscap SystemCapability.Multimedia.Image.ImageSource 638 */ 639 readonly supportedFormats: Array<string>; 640 } 641 642 /** 643 * ImagePacker instance. 644 * @since 6 645 * @syscap SystemCapability.Multimedia.Image.ImagePacker 646 */ 647 interface ImagePacker { 648 /** 649 * Compresses or packs an image and uses a callback to return the result. 650 * @since 6 651 * @syscap SystemCapability.Multimedia.Image.ImagePacker 652 * @param source Image to be processed. 653 * @param option Option for image packing. 654 * @param callback Callback used to return the packed data. 655 */ 656 packing(source: ImageSource, option: PackingOption, callback: AsyncCallback<ArrayBuffer>): void; 657 658 /** 659 * Compresses or packs an image and uses a promise to return the result. 660 * @since 6 661 * @syscap SystemCapability.Multimedia.Image.ImagePacker 662 * @param source Image to be processed. 663 * @param option Option for image packing. 664 * @return A Promise instance used to return the compressed or packed data. 665 */ 666 packing(source: ImageSource, option: PackingOption): Promise<ArrayBuffer>; 667 668 /** 669 * Compresses or packs an image and uses a callback to return the result. 670 * @since 8 671 * @syscap SystemCapability.Multimedia.Image.ImagePacker 672 * @param source PixelMap to be processed. 673 * @param option Option for image packing. 674 * @param callback Callback used to return the packed data. 675 */ 676 packing(source: PixelMap, option: PackingOption, callback: AsyncCallback<ArrayBuffer>): void; 677 678 /** 679 * Compresses or packs an image and uses a promise to return the result. 680 * @since 8 681 * @syscap SystemCapability.Multimedia.Image.ImagePacker 682 * @param source PixelMap to be processed. 683 * @param option Option for image packing. 684 * @return A Promise instance used to return the compressed or packed data. 685 */ 686 packing(source: PixelMap, option: PackingOption): Promise<ArrayBuffer>; 687 688 /** 689 * Releases an ImagePacker instance and uses a callback to return the result. 690 * @since 6 691 * @syscap SystemCapability.Multimedia.Image.ImagePacker 692 * @param callback Callback to return the operation result. 693 */ 694 release(callback: AsyncCallback<void>): void; 695 696 /** 697 * Releases an ImagePacker instance and uses a promise to return the result. 698 * @since 6 699 * @syscap SystemCapability.Multimedia.Image.ImagePacker 700 * @return A Promise instance used to return the operation result. 701 */ 702 release(): Promise<void>; 703 704 /** 705 * Supported image formats. 706 * @since 6 707 * @syscap SystemCapability.Multimedia.Image.ImagePacker 708 */ 709 readonly supportedFormats: Array<string>; 710 } 711} 712 713export default image;