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 ]

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

Спецификация Статус Комментарий
HTML Living Standard
Определение 'CanvasRenderingContext2D.putImageData' в этой спецификации.
Живой стандарт

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

BCD tables only load in the browser

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

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

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