CanvasRenderingContext2D: метод putImageData()

Базовая реализация Широко поддерживается

Данная функция хорошо отработана и работает на многих устройствах и версиях браузеров. Она доступна во всех браузерах с июля 2015 года.

Метод CanvasRenderingContext2D.putImageData() API холста 2D рисует данные из переданного объекта ImageData на холст. Если указан прямоугольник с неактуальными данными, будут нарисованы только пиксели из этого прямоугольника. Этот метод не зависит от матрицы преобразования холста.

Примечание: Данные изображения могут быть извлечены с помощью метода getImageData().

Дополнительную информацию о putImageData() и общих методах манипуляции содержимым холста можно найти в статье Манипуляции с пикселями на холсте.

Синтаксис

putImageData(imageData, dx, dy)
putImageData(imageData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight)

Параметры

imageData: Объект ImageData, содержащий массив значений пикселей.
dx: Горизонтальная позиция (координата x), в которой данные изображения должны быть размещены на целевом холсте.
dy: Вертикальная позиция (координата y), в которой данные изображения должны быть размещены на целевом холсте.
dirtyX Необязательно: Горизонтальная позиция (координата x) левого верхнего угла, откуда будут извлечены данные изображения. По умолчанию 0.
dirtyY Необязательно: Вертикальная позиция (координата y) левого верхнего угла, откуда будут извлечены данные изображения. По умолчанию 0.
dirtyWidth Необязательно: Ширина прямоугольника, который будет нарисован. По умолчанию ширина данных изображения.
dirtyHeight Необязательно: Высота прямоугольника, который будет нарисован. По умолчанию высота данных изображения.

Возвращаемое значение

Ничего (undefined).

Исключения

NotSupportedError DOMException: Выбрасывается, если какой-либо из аргументов является бесконечным.
InvalidStateError DOMException: Выбрасывается, если данные объекта ImageData были откреплены.

Примеры

Понимание putImageData

Чтобы понять, как работает этот алгоритм под капотом, вот реализация на основе CanvasRenderingContext2D.fillRect().

HTML

<canvas id="canvas"></canvas>

JavaScript

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

function putImageData(
  ctx,
  imageData,
  dx,
  dy,
  dirtyX,
  dirtyY,
  dirtyWidth,
  dirtyHeight,
) {
  const data = imageData.data;
  const height = imageData.height;
  const width = imageData.width;
  dirtyX = dirtyX || 0;
  dirtyY = dirtyY || 0;
  dirtyWidth = dirtyWidth !== undefined ? dirtyWidth : width;
  dirtyHeight = dirtyHeight !== undefined ? dirtyHeight : height;
  const limitBottom = dirtyY + dirtyHeight;
  const limitRight = dirtyX + dirtyWidth;
  for (let y = dirtyY; y < limitBottom; y++) {
    for (let x = dirtyX; x < limitRight; x++) {
      const pos = y * width + x;
      ctx.fillStyle = `rgb(${data[pos * 4 + 0]} ${data[pos * 4 + 1]}
      ${data[pos * 4 + 2]} / ${data[pos * 4 + 3] / 255})`;
      ctx.fillRect(x + dx, y + dy, 1, 1);
    }
  }
}

// Draw content onto the canvas
ctx.fillRect(0, 0, 100, 100);
// Create an ImageData object from it
const imagedata = ctx.getImageData(0, 0, 100, 100);
// use the putImageData function that illustrates how putImageData works
putImageData(ctx, imagedata, 150, 0, 50, 50, 25, 25);

Результат

Потеря данных из-за оптимизации браузера

Предупреждение: Из-за потери точности при преобразовании в цветовые значения с предварительным альфа-каналом, пиксели, которые только что были установлены с помощью putImageData(), могут быть возвращены как эквивалентные getImageData() с разными значениями.

JavaScript

const canvas = document.createElement("canvas");
canvas.width = 1;
canvas.height = 1;
const context = canvas.getContext("2d");
const imgData = context.getImageData(0, 0, canvas.width, canvas.height);
const pixels = imgData.data;
pixels[0 + 0] = 1;
pixels[0 + 1] = 127;
pixels[0 + 2] = 255;
pixels[0 + 3] = 1;
console.log("before:", pixels);
context.putImageData(imgData, 0, 0);
const imgData2 = context.getImageData(0, 0, canvas.width, canvas.height);
const pixels2 = imgData2.data;
console.log("after:", pixels2);

Вывод может выглядеть следующим образом:

before: Uint8ClampedArray(4) [ 1, 127, 255, 1 ]
after: Uint8ClampedArray(4) [ 255, 255, 255, 1 ]

Спецификации

Спецификация
HTML # dom-context-2d-putimagedata-dev

Совместимость с браузерами

	Рабочие столы					Мобильные
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	WebView Android
`putImageData`	2	12	2	≤12.1	4	18	4	≤12.1	3.2	1.0	≤37

См. также

Интерфейс, определяющий этот метод: CanvasRenderingContext2D
Объект ImageData
CanvasRenderingContext2D.getImageData()
Манипуляции с пикселями на холсте

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/putImageData