1# ImageBitmap
2
3An **ImageBitmap** object stores pixel data rendered on a canvas.
4
5>  **NOTE**
6>
7>  The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8
9## APIs
10
11### ImageBitmap<sup>12+</sup>
12
13ImageBitmap(data: PixelMap, unit?: LengthMetricsUnit)
14
15Creates an **ImageBitmap** object using a **PixelMap** object.
16
17**Atomic service API**: This API can be used in atomic services since API version 12.
18
19**System capability**: SystemCapability.ArkUI.ArkUI.Full
20
21**Parameters**
22
23| Name | Type  | Mandatory | Description                                   |
24| ---- | ------ | ---- | ---------------------------------------- |
25| data  | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) | Yes   | Image data source, which supports **PixelMap** objects.|
26| unit  | [LengthMetricsUnit](ts-canvasrenderingcontext2d.md#lengthmetricsunit12) | No|  Unit mode of the **ImageBitmap** object. The value cannot be dynamically changed once set. The configuration method is the same as that of [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md#lengthmetricsunit12).<br>Default value: **DEFAULT**|
27
28### ImageBitmap
29
30ImageBitmap(src: string, unit?: LengthMetricsUnit)
31
32Creates an **ImageBitmap** object using an **ImageSrc** object.
33
34**Widget capability**: This API can be used in ArkTS widgets since API version 9.
35
36**Atomic service API**: This API can be used in atomic services since API version 11.
37
38**System capability**: SystemCapability.ArkUI.ArkUI.Full
39
40**Parameters**
41
42| Name | Type  | Mandatory | Description                                   |
43| ---- | ------ | ---- | ---------------------------------------- |
44| src  | string | Yes | Image source. Local images are supported.<br>1. The string format is used to load local images, for example, **ImageBitmap("common/images/example.jpg")**. For entry and feature modules, the start point of the image path for loading is the **ets** folder of the module. For HAR and shared modules, the start point is the **ets** folder of the entry or feature module into which they are built.<br>For modules whose **type** is **"har"** or **"shared**", you are advised to use [ImageSource](../../../media/image/image-decoding.md) to decode resource images into a unified **PixelMap** object for loading and use.<br>2. Supported image formats: BMP, JPG, PNG, SVG, and WEBP.<br>**NOTE**<br>- ArkTS widgets do not support the strings with the **http://**, **datashare://**, or **file://data/storage**.|
45| unit<sup>12+</sup>  | [LengthMetricsUnit](../js-apis-arkui-graphics.md#lengthmetricsunit12) | No| Unit mode of the **ImageBitmap** object. The value cannot be dynamically changed once set. The configuration method is the same as that of [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md#lengthmetricsunit12).<br>Default value: **DEFAULT**|
46
47
48## Attributes
49
50**Widget capability**: This API can be used in ArkTS widgets since API version 9.
51
52**Atomic service API**: This API can be used in atomic services since API version 11.
53
54**System capability**: SystemCapability.ArkUI.ArkUI.Full
55
56| Name    | Type| Read Only| Optional| Description|
57| ------ | ------ | ----- | -------- | --------------------------- |
58| width | number | Yes| No| Pixel width of the **ImageBitmap** object.<br>Default unit: vp|
59| height | number | Yes| No| Pixel height of the **ImageBitmap** object.<br>Default unit: vp|
60
61## close
62
63close(): void
64
65Releases all graphics resources associated with this **ImageBitmap** object and sets its width and height to **0**. For the sample code, see the code for creating an **ImageBitmap** object.
66
67**Widget capability**: This API can be used in ArkTS widgets since API version 9.
68
69**Atomic service API**: This API can be used in atomic services since API version 11.
70
71**System capability**: SystemCapability.ArkUI.ArkUI.Full
72
73## Support for Concurrent Thread Drawing
74
75Since API version 11, when an application creates a [worker thread](../../../arkts-utils/worker-introduction.md), it can use **postMessage** to transfer the **ImageBitmap** instance to the worker thread for drawing, and use **onmessage** to receive the drawing results sent by the worker thread for display.
76
77## Example
78
79### Example 1
80
81  ```ts
82  // xxx.ets
83  @Entry
84  @Component
85  struct ImageExample {
86    private settings: RenderingContextSettings = new RenderingContextSettings(true)
87    private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
88    private img:ImageBitmap = new ImageBitmap("common/images/example.jpg")
89
90    build() {
91      Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
92        Canvas(this.context)
93          .width('100%')
94          .height('100%')
95          .backgroundColor('#ffff00')
96          .onReady(() => {
97            this.context.drawImage(this.img, 0, 0, 500, 500, 0, 0, 400, 200)
98            this.img.close()
99          })
100      }
101      .width('100%')
102      .height('100%')
103    }
104  }
105  ```
106
107  ![en-us_image_0000001194352442](figures/en-us_image_0000001194352442.png)
108
109### Example 2
110
111  ```ts
112// xxx.ets
113@Entry
114@Component
115struct Demo {
116  private settings: RenderingContextSettings = new RenderingContextSettings(true)
117  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
118
119  build() {
120    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
121      Canvas(this.context)
122        .width('100%')
123        .height('50%')
124        .backgroundColor('#ffff00')
125        .onReady(() => {
126          this.context.fillStyle = "#00ff00"
127          this.context.fillRect(0, 0, 100, 100)
128          let pixel = this.context.getPixelMap(0, 0, 100, 100)
129          let image = new ImageBitmap(pixel)
130          this.context.drawImage(image, 100, 100)
131        })
132
133    }
134    .width('100%')
135    .height('100%')
136  }
137}
138  ```
139
140  ![en-us_image_0000001194352442](figures/en-us_image_0000001194352444.png)
141
142
143### Example 3
144```ts
145import worker from '@ohos.worker';
146
147@Entry
148@Component
149struct imageBitmapExamplePage {
150  private settings: RenderingContextSettings = new RenderingContextSettings(true);
151  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings);
152  private myWorker = new worker.ThreadWorker('entry/ets/workers/Worker.ts');
153  private img:ImageBitmap = new ImageBitmap("common/images/example.jpg")
154
155  build() {
156    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
157      Canvas(this.context)
158        .width('100%')
159        .height('100%')
160        .backgroundColor('#ffff00')
161        .onReady(() => {
162          this.myWorker.postMessage({ myImage: this.img });
163          this.myWorker.onmessage = (e): void => {
164            if (e.data.myImage) {
165              let image: ImageBitmap = e.data.myImage
166              this.context.transferFromImageBitmap(image)
167            }
168          }
169        })
170    }
171    .width('100%')
172    .height('100%')
173  }
174}
175```
176In the worker thread, the application uses **onmessage** to receive the **ImageBitmap** instance sent by the main thread through **postMessage **and proceeds with rendering.
177
178```ts
179workerPort.onmessage = function (e: MessageEvents) {
180  if (e.data.myImage) {
181    let img = e.data.myImage
182    let offCanvas = new OffscreenCanvas(600, 600)
183    let offContext = offCanvas.getContext("2d")
184    offContext.drawImage(img, 0, 0, 500, 500, 0, 0, 400, 200)
185    let image = offCanvas.transferToImageBitmap()
186    workerPort.postMessage({ myImage: image });
187  }
188}
189```
190
191  ![en-us_image_0000001194352442](figures/en-us_image_0000001194352442.png)
192