YouTipCanvas Putimagedata
## HTML Canvas putImageData() Method
The `putImageData()` method of the Canvas 2D API paints data from a given `ImageData` object onto the canvas.
This is a low-level API used for direct pixel manipulation. It allows you to render pixel arrays that you have either retrieved from the canvas using `getImageData()` or created from scratch using `createImageData()`.
---
## Syntax
The `putImageData()` method can be used in two forms: a basic 3-parameter syntax and an advanced 7-parameter syntax (often referred to as the "dirty rectangle" syntax).
### Basic Syntax
```javascript
context.putImageData(imgData, dx, dy);
```
### Advanced Syntax (Dirty Rectangle)
```javascript
context.putImageData(imgData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight);
```
---
## Parameter Values
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `imgData` | `ImageData` | **Required.** An `ImageData` object containing the array of pixel values. |
| `dx` | `number` | **Required.** The X-coordinate (horizontal position) in the destination canvas at which to place the image data. |
| `dy` | `number` | **Required.** The Y-coordinate (vertical position) in the destination canvas at which to place the image data. |
| `dirtyX` | `number` | **Optional.** The X-coordinate of the top-left corner of the sub-rectangle (dirty rectangle) within the source `ImageData` to be painted. Defaults to `0`. |
| `dirtyY` | `number` | **Optional.** The Y-coordinate of the top-left corner of the sub-rectangle (dirty rectangle) within the source `ImageData` to be painted. Defaults to `0`. |
| `dirtyWidth` | `number` | **Optional.** The width of the sub-rectangle to be painted. Defaults to the width of the `ImageData`. |
| `dirtyHeight` | `number` | **Optional.** The height of the sub-rectangle to be painted. Defaults to the height of the `ImageData`. |
---
## Code Examples
### Example 1: Basic Copy and Paste
This example draws a red square on the canvas, copies its pixel data using `getImageData()`, and then pastes it to a different position on the canvas using `putImageData()`.
```html
```
### Example 2: Using the "Dirty Rectangle" Parameters
The "dirty rectangle" parameters allow you to paint only a specific sub-section of the source `ImageData` onto the canvas.
```javascript
// Copy a 100x100 pixel area
const imgData = ctx.getImageData(0, 0, 100, 100);
// Paint only a 50x50 sub-section from the center of the copied image data
// onto the canvas at coordinates (150, 150)
const dx = 150;
const dy = 150;
const dirtyX = 25;
const dirtyY = 25;
const dirtyWidth = 50;
const dirtyHeight = 50;
ctx.putImageData(imgData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight);
```
---
## Important Considerations
### 1. No Alpha Blending (Overwriting Pixels)
Unlike drawing methods like `drawImage()`, `putImageData()` **completely overwrites** existing pixels on the canvas. It ignores the canvas's global alpha, compositing rules (`globalCompositeOperation`), and any current transformations (scale, rotate, translate). If a pixel in your `ImageData` has an alpha value of `0` (fully transparent), writing it to the canvas with `putImageData()` will make that canvas pixel fully transparent, erasing whatever was underneath it.
### 2. Performance
Direct pixel manipulation can be computationally expensive. For optimal performance:
* Avoid calling `getImageData()` and `putImageData()` inside high-frequency animation loops if possible.
* Use the "dirty rectangle" parameters to update only the modified portions of the canvas instead of rewriting the entire canvas.
### 3. Security Restrictions (CORS)
If the canvas contains images loaded from a different domain without proper CORS configuration, the canvas becomes "tainted." Once tainted, calling `getImageData()` will throw a security error, preventing you from retrieving or subsequently putting back image data.
---
## Browser Compatibility
| Chrome | Edge | Firefox | Safari | Opera | Internet Explorer |
| :---: | :---: | :---: | :---: | :---: | :---: |
| Yes | Yes | Yes | Yes | Yes | IE 9+ |
*Note: Internet Explorer 8 and earlier versions do not support the `