CanvasRenderingContext2D.putImageData()

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

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

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

Синтаксис

void ctx.putImageData(imageData, dx, dy);
void ctx.putImageData(imageData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight);

Параметры

imageData

Объект ImageData, содержащий массив значений пикселей..

dx

Горизонтальная позиция (координата x), в которой необходимо разместить данные изображения на целевом холсте.

dy

Вертикальная позиция (координата y), в которой необходимо разместить данные изображения на целевом холсте.

dirtyXНеобязательный

Горизонтальная позиция (координата x) верхнего левого угла, из которого будут извлечены данные изображения. По умолчанию 0.

dirtyY Необязательный

Вертикальная позиция (координата y) верхнего левого угла, из которого будут извлечены данные изображения. По умолчанию 0.

dirtyWidth Необязательный

Ширина прямоугольника для рисования. По умолчанию ширина данных изображения.

dirtyHeight Необязательный

Высота прямоугольника для рисования. По умолчанию высота данных изображения.

Ошибки

NotSupportedError

Выбрасывается, если любой из аргументов бесконечен.

InvalidStateError

Выбрасывается, если данные объекта ImageData были отделены.

Примеры

Понимание putImageData

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

HTML

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

JavaScript

let canvas = document.getElementById('canvas');
let ctx = canvas.getContext('2d');

function putImageData(ctx, imageData, dx, dy,
    dirtyX, dirtyY, dirtyWidth, dirtyHeight) {
  let data = imageData.data;
  let height = imageData.height;
  let width = imageData.width;
  dirtyX = dirtyX || 0;
  dirtyY = dirtyY || 0;
  dirtyWidth = dirtyWidth !== undefined? dirtyWidth: width;
  dirtyHeight = dirtyHeight !== undefined? dirtyHeight: height;
  let limitBottom = dirtyY + dirtyHeight;
  let limitRight = dirtyX + dirtyWidth;
  for (let y = dirtyY; y < limitBottom; y++) {
    for (let x = dirtyX; x < limitRight; x++) {
      var pos = y * width + x;
      ctx.fillStyle = 'rgba(' + 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);
    }
  }
}

// Нарисуйте контент на холсте
ctx.fillRect(0, 0, 100, 100);
// Создайте объект ImageData из него
let imagedata = ctx.getImageData(0, 0, 100, 100);
// используйте функцию putImageData, которая иллюстрирует, как работает putImageData
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 ]

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

Specification
HTML Standard
# dom-context-2d-putimagedata-dev

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

BCD tables only load in the browser

Специфичные для Gecko заметки

  • Начиная с Gecko 10.0, нескончаемые(например, NaN или Infinity) значения любого из этих параметров приводят к тому, что вызов putImageData() будет игнорироваться, а не вызывать исключение.
  • To comply with the specification, starting with Gecko 16.0, a call with an invalid number of arguments (only 3 or 7 arguments are valid), will now throw an error (баг 762657).

Смотрите также