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: Loading an Image 80 81This example demonstrates how to load a local image using the **ImageBitmap** object. 82 83 ```ts 84 // xxx.ets 85 @Entry 86 @Component 87 struct ImageExample { 88 private settings: RenderingContextSettings = new RenderingContextSettings(true) 89 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 90 private img: ImageBitmap = new ImageBitmap("common/images/example.jpg") 91 92 build() { 93 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 94 Canvas(this.context) 95 .width('100%') 96 .height('100%') 97 .backgroundColor('#ffff00') 98 .onReady(() => { 99 this.context.drawImage(this.img, 0, 0, 500, 500, 0, 0, 400, 200) 100 this.img.close() 101 }) 102 } 103 .width('100%') 104 .height('100%') 105 } 106 } 107 ``` 108 109  110 111### Example 2: Creating an ImageBitmap Object 112 113This example shows how to create an **ImageBitmap** object using a **PixelMap** object. 114 115```ts 116// xxx.ets 117@Entry 118@Component 119struct Demo { 120 private settings: RenderingContextSettings = new RenderingContextSettings(true) 121 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 122 123 build() { 124 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 125 Canvas(this.context) 126 .width('100%') 127 .height('50%') 128 .backgroundColor('#ffff00') 129 .onReady(() => { 130 this.context.fillStyle = "#00ff00" 131 this.context.fillRect(0, 0, 100, 100) 132 let pixel = this.context.getPixelMap(0, 0, 100, 100) 133 let image = new ImageBitmap(pixel) 134 this.context.drawImage(image, 100, 100) 135 }) 136 137 } 138 .width('100%') 139 .height('100%') 140 } 141} 142``` 143 144  145 146 147### Example 3: Supporting Concurrent Thread Drawing 148 149This example demonstrates how to implement concurrent thread drawing by creating a Worker thread. 150 151> **NOTE** 152> 153> The content drawn in the Worker thread cannot be previewed in DevEco Studio Previewer. 154 155```ts 156import { worker } from '@kit.ArkTS'; 157 158@Entry 159@Component 160struct imageBitmapExamplePage { 161 private settings: RenderingContextSettings = new RenderingContextSettings(true); 162 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); 163 private myWorker = new worker.ThreadWorker('entry/ets/workers/Worker.ts'); 164 private img: ImageBitmap = new ImageBitmap("common/images/example.jpg") 165 166 build() { 167 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 168 Canvas(this.context) 169 .width('100%') 170 .height('100%') 171 .backgroundColor('#ffff00') 172 .onReady(() => { 173 this.myWorker.postMessage({ myImage: this.img }); 174 this.myWorker.onmessage = (e): void => { 175 if (e.data.myImage) { 176 let image: ImageBitmap = e.data.myImage 177 this.context.transferFromImageBitmap(image) 178 } 179 } 180 }) 181 } 182 .width('100%') 183 .height('100%') 184 } 185} 186``` 187In the worker thread, the application uses **onmessage** to receive the **ImageBitmap** object sent by the main thread through **postMessage** and proceeds with rendering. 188 189```ts 190workerPort.onmessage = (e: MessageEvents) => { 191 if (e.data.myImage) { 192 let img: ImageBitmap = e.data.myImage 193 let offCanvas = new OffscreenCanvas(600, 600) 194 let offContext = offCanvas.getContext("2d") 195 offContext.drawImage(img, 0, 0, 500, 500, 0, 0, 400, 200) 196 let image = offCanvas.transferToImageBitmap() 197 workerPort.postMessage({ myImage: image }); 198 } 199} 200``` 201 202  203
