path: root/files/ru/web/api/canvasrenderingcontext2d/putimagedata/index.html

---
title: CanvasRenderingContext2D.putImageData()
slug: Web/API/CanvasRenderingContext2D/putImageData
tags:
  - API
  - Canvas
  - CanvasRenderingContext2D
  - Method
  - Reference
translation_of: Web/API/CanvasRenderingContext2D/putImageData
---
<div>{{APIRef}}</div>



<p><code><strong>CanvasRenderingContext2D</strong></code><strong><code>.putImageData()</code></strong> метод Canvas 2D API рисует данные из заданного {{domxref("ImageData")}} объекта на холст. На этот метод не влияет матрица преобразования холста.</p>

<div class="note">
<p><strong>Примечание:</strong> Данные изображения могут быть получены с холста с помощью метода {{domxref("CanvasRenderingContext2D.getImageData()", "getImageData()")}}.</p>
</div>

<p>Вы можете найти больше информации о <code>putImageData()</code> и общих манипуляциях с содержимым холста в статье <a href="/ru/docs/Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas">Пиксельные манипуляции с холстом</a>.</p>

<h2 id="Синтаксис">Синтаксис</h2>

<pre class="syntaxbox">void <em>ctx</em>.putImageData(<em>imageData</em>, <em>dx</em>, <em>dy</em>);
void <em>ctx</em>.putImageData(<em>imageData</em>, <em>dx</em>, <em>dy</em>, <em>dirtyX</em>, <em>dirtyY</em>, <em>dirtyWidth</em>, <em>dirtyHeight</em>);
</pre>

<h3 id="Параметры">Параметры</h3>

<dl>
 <dt><code>imageData</code></dt>
 <dd>Объект {{domxref("ImageData")}}, содержащий массив значений пикселей..</dd>
 <dt><code>dx</code></dt>
 <dd>Горизонтальная позиция (координата x), в которой необходимо разместить данные изображения на целевом холсте.</dd>
 <dt><code>dy</code></dt>
 <dd>Вертикальная позиция (координата y), в которой необходимо разместить данные изображения на целевом холсте.</dd>
 <dt><code>dirtyX</code>{{optional_inline}}</dt>
 <dd>Горизонтальная позиция (координата x) верхнего левого угла, из которого будут извлечены данные изображения. По умолчанию 0.</dd>
 <dt><code>dirtyY</code> {{optional_inline}}</dt>
 <dd>Вертикальная позиция (координата y) верхнего левого угла, из которого будут извлечены данные изображения. По умолчанию 0.</dd>
 <dt><code>dirtyWidth</code> {{optional_inline}}</dt>
 <dd>Ширина прямоугольника для рисования. По умолчанию ширина данных изображения.</dd>
 <dt><code>dirtyHeight</code> {{optional_inline}}</dt>
 <dd>Высота прямоугольника для рисования. По умолчанию высота данных изображения.</dd>
</dl>

<h3 id="Ошибки">Ошибки</h3>

<dl>
 <dt><code>NotSupportedError</code></dt>
 <dd>Выбрасывается, если любой из аргументов бесконечен.</dd>
 <dt><code>InvalidStateError</code></dt>
 <dd>Выбрасывается, если данные объекта ImageData были отделены.</dd>
</dl>

<h2 id="Примеры">Примеры</h2>

<h3 id="Понимание_putImageData">Понимание putImageData</h3>

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

<h4 id="HTML">HTML</h4>

<pre class="brush: html">&lt;canvas id="canvas"&gt;&lt;/canvas&gt;
</pre>

<h4 id="JavaScript">JavaScript</h4>

<pre class="brush: js">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 &lt; limitBottom; y++) {
    for (let x = dirtyX; x &lt; 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);
</pre>

<h4 id="Результат">Результат</h4>

<p>{{ EmbedLiveSample('Понимание_putImageData', '', '', '', 'Web/API/CanvasRenderingContext2D/putImageData',800) }}</p>

<h3 id="Потеря_данных_из-за_оптимизации_браузера">Потеря данных из-за оптимизации браузера</h3>

<div class="blockIndicator warning">
<p> Из-за характера потерь при преобразовании в и из предварительно умноженных значений альфа-цвета пиксели, которые были только что установлены с помощью <code>putImageData()</code>, могут быть возвращены в эквивалентный <code>getImageData()</code> в качестве различных значений.</p>
</div>

<h4 id="JavaScript_2">JavaScript</h4>

<pre class="brush: js">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);</pre>

<p>Вывод может выглядеть так:</p>

<pre>before: Uint8ClampedArray(4) [ 1, 127, 255, 1 ]
after: Uint8ClampedArray(4) [ 255, 255, 255, 1 ]</pre>

<h2 id="Спецификации">Спецификации</h2>

{{Specifications}}

<h2 id="Совместимость_с_браузера">Совместимость с браузера</h2>



<p>{{Compat}}</p>

<h3 id="Специфичные_для_Gecko_заметки">Специфичные для Gecko заметки</h3>

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

<h2 id="Смотрите_также">Смотрите также</h2>

<ul>
 <li>Интерфейс, определяющий это свойство: {{domxref("CanvasRenderingContext2D")}}</li>
 <li>{{domxref("ImageData")}} объект</li>
 <li>{{domxref("CanvasRenderingContext2D.getImageData()")}}</li>
 <li><a href="/ru/docs/Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas">Пиксельные манипуляции с холстом</a></li>
</ul>