Этот документ является неофициальным переводом исходной английской версии HTML Canvas 2D Context. Обратите внимание на то, что оригинальная версия документа существует только на английском языке. Данный перевод может содержать неточности и ошибки. Перевод выполнил Кирилл Топольян, 2016.


Аннотация

Эта спецификация определяет 2D Context для HTML элемента canvas. 2D Context предоставляет объекты, методы и свойства для рисования и управления графиками на поверхности рисования canvas.

Статус этого документа

Этот раздел описывает статус данного документа на момент его публикации. Другие документы могут заменять этот документ. Со списком текущих публикаций W3C и последней ревизией этого технического доклада можно ознакомиться в индексе технических отчетов W3C, http://www.w3.org/TR/.

Эта спецификация для 2D Context для HTML элемента canvas опубликована Рабочей группой HTML.

Если вы хотите оставить комментарии к этому документу в порядке который отслеживается W3C, пожалуйста добавьте их с помощью нашего публичного списка вопросов. Если вы не можете сделать это, вы можете отправить e-mail на public-canvas-api@w3.org (подписка, архивы), и мы примем меры чтобы перенести комментарии в нашу публичную базу данных багов. Любая обратная связь приветствуется.

Публикуя эту рекомендацию, W3C ожидает что функциональность описанная в этой рекомендации не будет зависеть от изменений Web IDL, CSS Object Model, CSS Images Values, или CSS Fonts так как эти спецификации прошли Рекомендацию.

Работа по расширению этой спецификации, как правило, проходит через расширение спецификаций к которым следует обращаться, чтобы увидеть, какие новые возможности будут рассмотрены.

Основная часть текста данной спецификации также доступна в WHATWG HTML Living Standard, в соответствии с лицензией, которая разрешает повторное использование текста спецификации.

Работа по данной спецификации также сделана в WHATWG. Рабочая группа W3C HTML активно следит за сходимостью HTML спецификации с рабочими стандартами WHATWG, в рамках устава рабочей группы W3C HTML. Есть разные способы следить за этой работой в WHATWG:

Этот документ был рассмотрен членами W3C, разработчиками программного обеспечения, а также другими группами W3C и заинтересованными лицами, и одобрен Директором в качестве Рекомендации W3C. Это стабильный документ и может быть использован в качестве справочного материала или цитироваться из другого документа. Цель W3C в создании Рекомендации заключается в привлечении внимания к спецификации и способствовании ее широкому распространению. Это повышает функциональность и совместимость Сети.

Старый список багов по-прежнему доступен. Никаких изменений не было сделано с момента предыдущей публикации.

В период рассмотрения в Рекомендации, группа сделала доступный отчет о реализации, также как и дополнительный отчет для drawFocusIfNeeded и addHitRegion.

Эта спецификация является расширением для языка HTML5. Все нормативное содержание в спецификации HTML5, если оно не было перезаписано в данной спецификации, предназначено стать основой для нее.

Этот документ был подготовлен группой действующей под Патентной политикой W3C от 5 февраля 2004. W3C поддерживает публичный список открытых патентов, сделанных в связи с результатами деятельности группы; эта страница также включает в себя инструкции по раскрытию патента. Человек, который имеет фактическое знание патента, который удовлетворяет основным требованиям, должен раскрывать информацию в соответствии с разделом 6 патентной политики W3C.

Этот документ регулируется W3C Process Document от 14 октября 2005.

Содержание

  1. 1 Требования к соответствию
  2. 2 Состояние canvas
  3. 3 Стили линий
  4. 4 Стили текста
  5. 5 Построение пути
  6. 6 Преобразования
  7. 7 Источники изображений для 2D рендеринга
  8. 8 Стили заполнения и обводки
  9. 9 Рисование прямоугольников на холсте
  10. 10 Рисование текста на холсте
  11. 11 Рисование пути на холсте
  12. 12 Рисование изображений на холсте
  13. 13 Hit области
  14. 14 Пиксельная манипуляция
  15. 15 Композиция
  16. 16 Тени
  17. 17 Модель рисования
  18. 18 Советы
  19. 19 Примеры
  20. Ссылки

1 Требования к соответствию

Эта спецификация является спецификацией HTML. Все требования на соответствие, соответствие классов, определения, зависимости, терминология и типографские конвенции, описанные в спецификации ядра HTML5, применимы к данной спецификации. [HTML]

Интерфейсы определяются в терминах Web IDL. [WEBIDL]

Эта спецификация определяет тип 2d context, чей API реализован с использованием интерфейса CanvasRenderingContext2D.

Когда метод getContext() элемента canvas возвращает новый объект для contextId 2d, агент пользователя должен вернуть новый объект CanvasRenderingContext2D. Любые дополнительные аргументы игнорируются.

2D context представляет собой прямоугольную систему координат, начало которой (0,0) находится в верхнем левом углу, с координатами пространства, где значения x идут вправо и значения y идут вниз.

typedef (HTMLImageElement or
         HTMLVideoElement or
         HTMLCanvasElement) CanvasImageSource;

interface CanvasRenderingContext2D {

  // back-reference to the canvas
  readonly attribute HTMLCanvasElement canvas;

  // state
  void save(); // push state on state stack
  void restore(); // pop state stack and restore state

  // transformations (default: transform is the identity matrix)
  void scale(unrestricted double x, unrestricted double y);
  void rotate(unrestricted double angle);
  void translate(unrestricted double x, unrestricted double y);
  void transform(unrestricted double a, unrestricted double b, unrestricted double c, unrestricted double d, unrestricted double e, unrestricted double f);
  void setTransform(unrestricted double a, unrestricted double b, unrestricted double c, unrestricted double d, unrestricted double e, unrestricted double f);

  // compositing
           attribute unrestricted double globalAlpha; // (default: 1.0)
           attribute DOMString globalCompositeOperation; // (default: "source-over")

  // colors and styles (see also the CanvasDrawingStyles interface)
           attribute (DOMString or CanvasGradient or CanvasPattern) strokeStyle; // (default: "black")
           attribute (DOMString or CanvasGradient or CanvasPattern) fillStyle; // (default: "black")
  CanvasGradient createLinearGradient(double x0, double y0, double x1, double y1);
  CanvasGradient createRadialGradient(double x0, double y0, double r0, double x1, double y1, double r1);
  CanvasPattern createPattern(CanvasImageSource image, [TreatNullAs=EmptyString] DOMString repetition);

  // shadows
           attribute unrestricted double shadowOffsetX; // (default: 0)
           attribute unrestricted double shadowOffsetY; // (default: 0)
           attribute unrestricted double shadowBlur; // (default: 0)
           attribute DOMString shadowColor; // (default: "transparent black")

  // rects
  void clearRect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
  void fillRect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
  void strokeRect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);

  // path API (see also CanvasPathMethods)
  void beginPath();
  void fill();
  void stroke();
  void drawFocusIfNeeded(Element element);
  void clip();
  boolean isPointInPath(unrestricted double x, unrestricted double y);

  // text (see also the CanvasDrawingStyles interface)
  void fillText(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
  void strokeText(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
  TextMetrics measureText(DOMString text);

  // drawing images
  void drawImage(CanvasImageSource image, unrestricted double dx, unrestricted double dy);
  void drawImage(CanvasImageSource image, unrestricted double dx, unrestricted double dy, unrestricted double dw, unrestricted double dh);
  void drawImage(CanvasImageSource image, unrestricted double sx, unrestricted double sy, unrestricted double sw, unrestricted double sh, unrestricted double dx, unrestricted double dy, unrestricted double dw, unrestricted double dh);

  // hit regions
  void addHitRegion(HitRegionOptions options);
  void removeHitRegion(DOMString id);
  void clearHitRegions();

  // pixel manipulation
  ImageData createImageData(unrestricted double sw, unrestricted double sh);
  ImageData createImageData(ImageData imagedata);
  ImageData getImageData(double sx, double sy, double sw, double sh);
  void putImageData(ImageData imagedata, double dx, double dy);
  void putImageData(ImageData imagedata, double dx, double dy, double dirtyX, double dirtyY, double dirtyWidth, double dirtyHeight);
};
CanvasRenderingContext2D implements CanvasDrawingStyles;
CanvasRenderingContext2D implements CanvasPathMethods;

[NoInterfaceObject]
interface CanvasDrawingStyles {
  // line caps/joins
           attribute unrestricted double lineWidth; // (default: 1)
           attribute DOMString lineCap; // "butt", "round", "square" (default: "butt")
           attribute DOMString lineJoin; // "round", "bevel", "miter" (default: "miter")
           attribute unrestricted double miterLimit; // (default: 10)

  // dashed lines
  void setLineDash(sequence<unrestricted double> segments); // (default: empty)
  sequence<unrestricted double> getLineDash();
           attribute unrestricted double lineDashOffset;


  // text
           attribute DOMString font; // (default: "10px sans-serif")
           attribute DOMString textAlign; // "start", "end", "left", "right", "center" (default: "start")
           attribute DOMString textBaseline; // "top", "hanging", "middle", "alphabetic", "ideographic", "bottom" (default: "alphabetic")
};

[NoInterfaceObject]
interface CanvasPathMethods {
  // shared path API methods
  void closePath();
  void moveTo(unrestricted double x, unrestricted double y);
  void lineTo(unrestricted double x, unrestricted double y);
  void quadraticCurveTo(unrestricted double cpx, unrestricted double cpy, unrestricted double x, unrestricted double y);
  void bezierCurveTo(unrestricted double cp1x, unrestricted double cp1y, unrestricted double cp2x, unrestricted double cp2y, unrestricted double x, unrestricted double y);
  void arcTo(unrestricted double x1, unrestricted double y1, unrestricted double x2, unrestricted double y2, unrestricted double radius); 
  void rect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
  void arc(unrestricted double x, unrestricted double y, unrestricted double radius, unrestricted double startAngle, unrestricted double endAngle, optional boolean counterclockwise = false); 

  };

interface CanvasGradient {
  // opaque object
  void addColorStop(double offset, DOMString color);
};

interface CanvasPattern {
  // opaque object
};

interface TextMetrics {
  readonly attribute double width;
};

dictionary HitRegionOptions {
  // dictionary to allow expansion on Hit Regions in Canvas Context 2D Level 2
  DOMString id = "";
  // for control-backed regions:
  Element? control = null;
};

interface ImageData {
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;
  readonly attribute Uint8ClampedArray data;
};

context . canvas

Возвращает элемент canvas.

Атрибут canvas должен возвращать элемент canvas, нарисованный контекстом.

За исключением случаев когда указано иное, для 2D context интерфейса, любой вызов метода с числовым аргументом, значение которого бесконечно либо NaN, должен быть проигнорирован.

Всякий раз, когда значение CSS currentColor используется в качестве цвета в этом API, вычисленное значения свойства 'color' для целей определения вычисленного значения currentColor, ключевым словом является вычисленное значение 'color' элемента о котором идет речь, когда цвет задан (например когда соответствующий атрибут установлен или когда вызван метод; не тогда когда цвет визуализируется или в другом случае). Если вычисленное значение свойства 'color' не определено для конкретного случая (например, потому что элемент находится не в Document), то для определения вычисленного значения свойства 'color' определяется значением currentColor, ключевое слово полностью непрозрачный черный. [CSSCOLOR]

В случае с addColorStop() на CanvasGradient, для целей определения вычисленного значения currentColor ключевое слово всегда полностью непрозрачный черный (нет связанного с ним элемента). [CSSCOLOR]

Это потому что объекты CanvasGradient canvas-нейтральные — объект CanvasGradient созданный одним canvas может использоваться другим, и поэтому нет способа узнать "элемент в деле" в то время как цвет определен.

Это касается также шрифтов, правила для них подробно описаны в разделе ниже.

2 Состояние canvas

Каждый контекст поддерживает стек из состояний рисования. Состояние рисования состоит из:

Текущий путь и текущий битмап не являются частью состояния рисования. Текущий путь постоянен и может быть сброшен только с помощью метода beginPath(). Текущий битмап является свойством холста, а не контекста.

context . save()

Сохраняет текущее состояние в стек.

context . restore()

Сбрасывает верхнее состояние в стеке, восстанавливая контекст к этому состоянию.

Метод save() должен поместить копию текущего состояния на стек состояния рисования.

Метод restore() должен взять верхний элемент в стеке состояния, и сбросить состояние которое он описывает. Если нет сохраненного состояния, метод не должен делать ничего.

3 Стили линий

context . lineWidth [ = value ]

Возвращает текущую ширину линии.

Может быть установлен, чтобы изменить ширину линии. Дробные значения больше нуля игнорируются.

context . lineCap [ = value ]

Возвращает стиль окончания линии.

Может быть установлен для изменения стиля окончания.

Возможные значения: "butt", "round", и "square". Другие значения игнорируются.

context . lineJoin [ = value ]

Возвращает текущий стиль соединения линии.

Может быть установлен для изменения стиля соединения.

Возможные стили "bevel", "round", и "miter". Другие значения игнорируются.

context . miterLimit [ = value ]

Возвращает текущее значение miter limit.

Может быть установлен для изменения значения miter limit. Дробные значения кроме нуля игнорируются.

context . setLineDash(segments)

Устанавливает текущий шаблон пунктирной линии (используется при сглаживании). Аргумент представляет собой массив расстояний.

segments = context . getLineDash()

Возвращает копию текущего шаблона пунктирной линии. Возвращаемый массив всегда будет иметь четное количество записей (т.е. оно нормализуется).

context . lineDashOffset [ = value ]

Возвращает смещение фазы (в тех же единицах, что и пунктирная линия).

Может быть установлен для изменения смещения фазы. Дробные значения игнорируются.

Объекты, которые реализуют интерфейс CanvasDrawingStyles имеют атрибуты и методы (определенные в этом разделе), которые контролируют как линии обрабатываются объектом.

Атрибут lineWidth задает ширину линий в координатном пространстве единиц. При получении, он должен вернуть текущее значение. При установке нулевого, негативного, бесконечного и NaN, значения должны быть проигнорированы, оставляя значение без изменений; другие значения должны изменить его на текущее значение.

Когда объект реализующий интерфейс CanvasDrawingStyles создан, атрибут lineWidth должен изначально иметь значение 1.0.


Атрибут lineCap определяет тип окончаний которые агент пользователя поместит на конец линий. Три валидных значения: "butt", "round", и "square".

При получении, он должен вернуть текущее значение. При настройке, если новое значение является одной из строк "butt", "round", и "square", текущее значение должно быть изменено на новое значение; другие значения должны игнорироваться и ничего не менять.

Когда объект реализующий интерфейс CanvasDrawingStyles создан, атрибут lineCap должен изначально иметь значение "butt".


Атрибут lineJoin определяет тип соединения, которое агент пользователя поместит туда где две линии встречаются. Есть три валидных значения: "bevel", "round", и "miter".

При получении, он должен вернуть текущее значение. При настройке, если новое значение одно из "bevel", "round" или "miter", текущее значение изменится на новое; другие значения будут проигнорированы и ничего не изменят.

Когда объект реализующий интерфейс CanvasDrawingStyles создан, атрибут lineJoin должен изначально иметь значение "miter".


Когда атрибут lineJoin имеет значение "miter", штрихи используют значение miter limit чтобы решить как соединиться. Значение miter limit ratio может быть задано атрибутом miterLimit. При получении, он должен вернуть текущее значение. При настройке, нулевые, отрицательные, бесконечные и NaN значения должны игнорироваться, не меняя значение; другие значения должны изменять текущее на новое значение.

Когда объект, реализующий интерфейс CanvasDrawingStyles создан, атрибут miterLimit должен изначально иметь значение 10.0.



Каждый объект CanvasDrawingStyles имеет dash list, который либо пуст, либо состоит из четного числа и положительных ненулевых чисел. Изначально dash list должен быть пуст.

Когда вызывается метод setLineDash() он должен выполнить следующие шаги:

  1. Сделать a копией массива предоставленного в качестве аргумента.

  2. Если какое-либо значение в массиве не является конечным числом (например бесконечное или NaN), или значение негативное (меньше ноля), то прервать эти шаги (без исключений; пользовательский агент может показать сообщение на консоли разработчика, это может помочь для отладки).

  3. Если число элементов в a нечетное, то сделать a результатом сложения двух копий a.

  4. Позволить объекту dash list быть a.

Когда вызывается метод getLineDash(), он должен вернуть созданный массив, значения которого являются значениями объекта dash list, в том же порядке.

Иногда полезно изменить "фазу" паттерна пунктира, например для достижения эффекта "бегущих муравьев". Фаза может быть установлена с помощью атрибута lineDashOffset. При получении, он должен возвратить текущее значение. При настройке, бесконечные и NaN значения должны быть проигнорированы, оставив значение без изменений; другие значения должны изменить текущее значение на новое.

Когда объект реализующий интерфейс CanvasDrawingStyles создан, атрибут lineDashOffset должен изначально иметь значение 0.0.


Когда пользовательский агент чертит путь, заданный объектом style, который реализует интерфейс CanvasDrawingStyles, он должен выполнить следующий алгоритм. Этот алгоритм возвращает новый путь.

  1. Сделать path копией пути который чертится.

  2. Сократить все элементы нулевой длины строки с path.

  3. Удалить с path любые подпути без линий (т.е. подпути только с одной точкой).

  4. Заменить каждую точку в каждом подпути path, кроме первой и последней точки каждого подпути с помощью join, который соединяет линию ведущую к этой точке на линии ведущей из этой точки, таким образом все подпути состоят из двух точек (стартовая и конечная), одной или более линий (соединяющих точки), и ноля или более соединений (каждое соединяет одну линию с другой), соединенных друг с другом таким образом, что каждый подпуть представляет собой серию из одной или нескольких линий с соединениями между каждой из точек на каждом конце.

  5. Добавить прямую линию закрытия каждого замкнутого подпути в path соединяющую последнюю точку и первую точку этого подпути; изменить последнюю точку в соединение (от предыдущей последней строки к новой добавленной закрывающей линии), и изменить первую точку в соединение (от предыдущей последней строки к новой добавленной закрывающей линии).

  6. Если styles dash list пуст, перейти к шагу помеченному как convert.

  7. Сделать pattern width суммой всех записей styles dash list, в координатном пространстве единиц.

  8. Для каждого подпути subpath в path, запустить следующие подэтапы. Эти подэтапы превратятся в подпути path сами собой.

    1. Сделать subpath width длиной всех линий от subpath, в координатном пространстве единиц.

    2. Сделать offset значением styles lineDashOffset, в координатном пространстве единиц.

    3. Если offset больше чем pattern width, уменьшить его до pattern width.

      Если offset меньше ноля, реализовать его с помощью pattern width.

    4. Определить L линией в линейных координатах в subpath, таким образом, что начало первой строки подпути определяется как координата 0, и конец последней строки в подпути определяется как координата subpath width.

    5. Сделать position нулем минус offset.

    6. Сделать index равным 0.

    7. Сделать current state равным off (другие состояния являются on и zero-on).

    8. Dash on: Сделать segment length значением стилей styles списка тире dash list записью номер index.

    9. Увеличить position на segment length.

    10. Если position больше чем subpath width, тогда закончить эти подэтапы для этих подпутей и начать их снова для следующего подпути; если больше нет подпутей, тогда перейти к шагу помеченному как convert.

    11. Если segment length не нулевая, сделать current state равной on.

    12. Увеличить index на единицу.

    13. Dash off: Сделать segment length значением styles dash list index-й записи.

    14. Сделать start смещением position на L.

    15. Увеличить position на segment length.

    16. Если position меньше ноля, тогда перейти к шагу помеченному как post-cut.

    17. Если start меньше ноля, тогда сделать start равным нолю.

    18. Если position больше чем subpath width, тогда сделать end смещением subpath width на L. В другом случае, сделать end смещением position на L.

    19. Выполнить один из следующих подэтапов, в зависимости от обстоятельств:

      Если segment length равен нулю и current state равно off

      Ничего не делать, перейти к следующему шагу.

      Если current state равен off

      Обрезать линию на которой end оказывается коротким end и поместить точку там, сокращая ее содержащий подпуть до двух; удалить все сегменты линий, соединения, точки и подпути которые между start и end; и наконец-то разместить одну точку на start без линий соединенных с ней.

      Точка имеет направленность для целей рисования шапки линии (смотрите ниже). Направленность является направлением, которое исходная линия имела в этой точке (т.е. когда L был определен выше).

      В другом случае

      Обрезать линию на которой start находят себя в двух на start и поместить точку там, обрезать подпуть в котором их было двое, а также обрезать линию на которой end оказывается коротким на end и поместить точку там, обрезать подпуть в котором их было двое, и затем удалить все отрезки, соединения, точки и подпути которые были между start и end.

      Если start и end в одной точке, в результате линии сокращаются и две точки вставляется там без удаления чего-либо, если только соединение не происходит в этой точке, тогда соединение тоже удаляется.

    20. Post-cut: Если position больше чем subpath width, тогда перейти к шагу помеченному как convert.

    21. Если segment length больше нуля, определить positioned-at-on-dash как false.

    22. Увеличить index на единицу. Если он равен количеству записей в styles dash list, тогда определить index как 0.

    23. Перейти к шагу помеченному как dash on.

  9. Convert: Это шаг, который преобразует путь к новому пути, который представляет свой ход.

    Создается новый path, который описывает края областей которые будут покрыты, если прямая линия длиной равная styles lineWidth была охвачена вдоль каждого пути в path в то время как была под углом таким образом, что линия перпендикулярна к пути была охвачена, заменив каждую точку с end cap, необходимой для удовлетворения атрибута styles lineCap, как описано выше и подробно рассмотрена ниже, и замена каждого соединения на соединение необходимое, чтобы удовлетворить тип styles lineJoin, как определено ниже.

    Окончания: Каждая точка имеет плоский край, перпендикулярной к направлению линии выходящей из нее. Это их дополнение в соответствии со значением из styles lineCap. Значение "butt" означает, что никакое дополнительное окончание не задано. Значение "round" означает что полукруг с диаметром, равным styles lineWidth, ширина должна быть дополнительно размещена на линии, выходящей из каждой точки. Значение "square" означает что прямоугольник с длинной с styles lineWidth и шириной половины styles lineWidth, поверхностью плотно прилегает к краю, перпендикулярной к направлению линии, выходящей из точки, должен быть добавлен в каждой точке.

    Точки без линий выходящих из них должны иметь два окончания расположенные спина-к-спине как если бы это были две точки соединенные друг с другом бесконечно короткой прямой линией.

    Соединения: В дополнение к точке где происходит соединение, две дополнительные точки присоединяются к каждой, одна для каждой линии: одна перпендикулярная для каждой линии, линия на каждой стороне наиболее удаленной от другой линии.

    Значение "bevel" означает что это всё что отображено в соединениях.

    Значение "round" означает, что заполненная дуга, соединяющая два вышеупомянутых угла соединения, примыкает (а не перекрывает) к вышеупомянутому треугольнику, с диаметром, равным ширине линии и началом координат в точке соединения, должна быть добавлена в соединения.

    Значение "miter" означает что второй заполненный треугольник должен (если он может с учетом длины скоса) быть добавлен в соединение, с одной линией, будучи линией между двумя вышеупомянутыми углами.


    Ниже неплохой пример miter:

      c.clearRect(0, 0, 640, 480);
      c.beginPath();
    
      c.moveTo((new Date()/100) % 600, 100);
      c.lineTo(300, 300);
      c.lineTo(500, 300);
    
      c.lineWidth = 50;
      c.miterLimit = 10000;
      c.strokeStyle = 'silver'
      c.stroke();
    
      c.miterLimit = 0.0001;
      c.strokeStyle = 'black'
      c.stroke();
    
      c.lineWidth = 1;
      c.strokeStyle = 'red'
      c.stroke();
    

    Подпути во созданном пути должны проходить по часовой стрелке, независимо от направления путей в path.

  10. Вернуть созданный путь.

4 Стили текста

context . font [ = value ]

Возвращает текущие настройки шрифта.

Может быть настроен, чтобы изменить шрифт. Синтаксис тот же как и для свойства 'font' в CSS; значения которые не могут прочитаться как значения шрифта в CSS, игнорируются.

Относящиеся ключевые слова и размеры вычисляются относящимися к шрифту элемента canvas.

context . textAlign [ = value ]

Возвращает текущие параметры выравнивания текста.

Может быть настроен, чтобы изменить выравнивание. Возможные значения: "start", "end", "left", "right", и "center". Другие значения игнорируются. По умолчанию: "start".

context . textBaseline [ = value ]

Возвращает текущие настройки выравнивания базовой линии.

Может быть настроен, чтобы изменить выравнивание базовой линии. Возможные значения и что они означают - написано ниже. Другие значения игнорируются. По умолчанию: "alphabetic".

Атрибут font IDL, при настройке, должен читаться тем же образом что и свойство 'font' в CSS (но без поддержки синтаксиса независимых свойств стилей типа 'inherit'), и полученный шрифт должен быть назначен к контексту, с компонентом 'line-height' принужденным к 'normal', с компонентом 'font-size' конвертированным в пиксели CSS, и с системными шрифтами вычисляемыми до явных значений. Если новое значение синтаксически некорректно (включая использование синтаксиса независимых свойств стилей типа 'inherit' или 'initial'), они должны быть игнорированы, без назначения нового значения шрифта. [CSS]

Имена шрифтов должны интерпретироваться в контексте font style source node таблицы стилей, когда шрифт будет использовать @font-face, поэтому таким образом шрифты должны быть доступны после того как однажды загружены. (Если отсылка к шрифту используется раньше чем он полностью загрузился, либо если font style source node не имеет данного шрифта, то он должен рассматриваться как если бы это был неизвестный шрифт, как это описано в соответствующих спецификациях CSS.) [CSSFONTS]

Только векторные шрифты должны использоваться агентом пользователя; если бы пользовательский агент использовал растровые шрифты, после преобразования, скорее всего, шрифты выглядели бы очень некрасиво.

При получении, атрибут font должен возвращать последовательную форму текущего шрифта контекста (без компонента 'line-height'). [CSSOM]

Например, после следующего утверждения:

context.font = 'italic 400 12px/2 Unknown Font, sans-serif';

...выражение context.font будет оценивать строку "italic 12px "Unknown Font", sans-serif". Значение "400" font-weight не появляется, потому что это значение по умолчанию. Высота линии не появляется, потому что она приравнивается к "normal" по умолчанию.

Когда контекст создается, шрифт контекста должен быть установлен в 10px sans-serif. Когда компонент 'font-size' установлен в длину с помощью процентов, 'em' или 'ex' единицами, или ключевыми словами 'larger' / 'smaller', они должны быть интерпретированы по отношению к расчетному значению свойства 'font-size' от font style source node в то время как атрибут установлен, если это элемент. Когда компонент 'font-weight' установлен на относительные значение 'bolder' и 'lighter', они должны быть интерпретированы по отношению к вычисленному значению значению свойства 'font-weight' от font style source node в то время как атрибут установлен, если это элемент. Если вычисленные значения не определены для конкретного случая (например потому что font style source node не элемент или он не в Документе), тогда относящиеся ключевые слова должны быть интерпретированы по отношению к normal-weight 10px sans-serif по умолчанию.

Атрибут IDL textAlign, при получении, должен возвращать текущее значение. При настройке, если значение одно из "start", "end", "left", "right", или "center", то значение должно быть изменено на новое значение. В другом случае, новое значение должно быть проигнорировано. Когда контекст создан, атрибут textAlign должен изначально иметь значение "start".

Атрибут IDL textBaseline, при получении, должен возвращать текущее значение. При настройке, если значение одно из "top", "hanging", "middle", "alphabetic", "ideographic", или "bottom", то значение должно быть изменено на новое значение. В другом случае, новое значение должно быть проигнорировано. Когда объект реализующий интерфейс CanvasDrawingStyles создан, атрибут textBaseline должен изначально иметь значение "alphabetic".

Атрибут textBaseline дает ключевым словам соответствие точкам выравнивания шрифта:

The top of the em square is roughly at the top of the glyphs in a font, the hanging baseline is where some glyphs like आ are anchored, the middle is half-way between the top of the em square and the bottom of the em square, the alphabetic baseline is where characters like Á, ÿ, f, and Ω are anchored, the ideographic baseline is where glyphs like 私 and 達 are anchored, and the bottom of the em square is roughly at the bottom of the glyphs in a font. The top and bottom of the bounding box can be far from these baselines, due to glyphs extending far outside the em square.

Ключевые слова карты по этим точкам выравнивания следующие:

top
Верх от em square
hanging
Висящий на baseline
middle
Середина от em square
alphabetic
Базовая линия alphabetic
ideographic
Базовая линия ideographic
bottom
Низ от em square

Алгоритм подготовки текста выглядит следующим образом. Он принимает в качестве входной строки text, объект CanvasDrawingStyles target, и опционально длину maxWidth. Он возвращает массив форм глифов, каждый из которых расположен на общем координатном пространстве, и physical alignment который имеет значение из: left, right и center. (Большинство вызывающих этот алгоритм игнорируют physical alignment.)

  1. Если maxWidth был предоставлен, но равен нулю или меньше него, возвращается пустой массив.

  2. Заменить все символы пробела в text на U+0020 символы.

  3. Сделать font текущим шрифтом target, как дано для объекта атрибута font.

  4. Применить соответствующий пункт из следующего списка, чтобы определить значение direction:

    Если target объекта font style source node является элементом
    Сделать direction направленным от target объекта font style source node.
    Если target объекта font style source node является Document и этот Документ является корневым элементом вложенного
    Сделать direction направленным от вложенного корневого элемента target объекта font style source node.
    Если target объект font style source node является Document и этот Документ не имеет вложенного элемента корневого
    Сделать direction 'ltr'.
  5. Форма гипотетического бесконечно широкого CSS лайн-бокса, содержащая единственный инлайн-блок, содержащий текст text, со всеми свойствами в их изначальных значениях кроме свойства 'font', в инлайн-боксе устанавливается font, свойство 'direction' инлайн-бокса устанавливается direction, и свойство 'white-space' устанавливается к 'pre'. [CSS]

  6. Если maxWidth предоставлено и гипотетическая ширина инлайн-бокса в гипотетическом лайн-боксе больше чем maxWidth CSS пикселей, тогда изменить font чтобы иметь более обобщенный шрифт (если он доступен или достаточно читаемый, можно синтезировать с помощью горизонтального коэффициента для шрифта) или меньший шрифт, и вернуться к предыдущему шагу.

  7. anchor point является точкой на инлайн-боксе, а physical alignment является одним из значений left, right, and center. Эти вариации значений textAlign и textBaseline определяются как следующие:

    Горизонтальная позиция:

    Если textAlign равняется left
    Если textAlign равняется start и direction равняется 'ltr'
    Если textAlign равняется end и direction равняется 'rtl'
    Сделать горизонтальную позицию anchor point левым краем от инлайн-бокса, и сделать physical alignment равным left.
    Если textAlign равняется right
    Если textAlign равняется end и direction равняется 'ltr'
    Если textAlign равняется start и direction равняется 'rtl'
    Сделать горизонтальную позицию anchor point правым краем инлайн-бокса, и сделать physical alignment равным right.
    Если textAlign равняется center
    Сделать горизонтальную позицию anchor point ровно посередине между левым и правым краями инлайн-бокса, и сделать physical alignment равной center.

    Вертикальная позиция:

    Если textBaseline равняется top
    Сделать вертикальную позицию anchor point верхом от em box первого доступного шрифта в инлайн-боксе.
    Если textBaseline равняется hanging
    Сделать вертикальную позицию anchor point висящей на baseline первого доступного шрифта в инлайн-боксе.
    Если textBaseline равняется middle
    Сделать вертикальную позицию anchor point ровно посередине верха и низа от em box первого доступного шрифта в инлайн-боксе.
    Если textBaseline равняется alphabetic
    Сделать вертикальную позицию anchor point the alphabetic baseline первого доступного шрифта в инлайн-боксе.
    Если textBaseline равняется ideographic
    Сделать вертикальную позицию anchor point ideographic baseline первого доступного шрифта в инлайн-боксе.
    Если textBaseline равняется bottom
    Сделать вертикальную позицию anchor pointнизом от em box первого доступного шрифта в инлайн-боксе.
  8. Сделать result массивом построенным перебиранием каждого глифа в инлайн-боксе от левого до правого (если есть), добавить в массив, для каждого глифа, форму глифа как в инлайн-боксе, расположенную в координатном пространстве с помощью CSS пикселей с его началом в anchor point.

  9. Возвратить result и, для тех кто вызывает его, physical alignment как значение выравнивания.

5 Построение пути

Каждый объект реализующий интерфейс CanvasPathMethods имеет путь (path). Путь имеет список из нуля или больше подпутей. Каждый подпуть содержит список из одной или более точек, соединенных прямыми или изогнутыми линиями, и флаг-индикатор является ли подпуть закрытым или нет. Закрытый путь это когда последняя точка подпути соединена с первой точкой подпути прямой линией. Подпути с меньше чем двумя точками игнорируются при рисовании пути.

Когда объект реализующий интерфейс CanvasPathMethods создан, его path должен быть инициализирован в ноль подпутей.

context . moveTo(x, y)

Создает новый подпуть с заданной точкой.

context . closePath()

Помечает текущий подпуть как закрытый, и начинает новый подпуть с той же точки что начало и конец только что закрытого подпути.

context . lineTo(x, y)

Добавляет заданную точку в текущий подпуть, соединенную с предыдущей прямой линией.

context . quadraticCurveTo(cpx, cpy, x, y)

Добавляет заданную точку в текущий подпуть, с помощью одной квадратичной кривой Безье с заданной контрольной точкой.

context . bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)

Добавляет заданную точку в текущий подпуть, соединенную с предыдущей с помощью кубической кривой Безье с заданными контрольными точками.

context . arcTo(x1, y1, x2, y2, radius)

Добавляет дугу с заданными контрольными точками и радиусом к текущему подпути, соединенную с прошлой точкой прямой линией.

Выдает исключение IndexSizeError если заданный радиус является отрицательным.

context . arc(x, y, radius, startAngle, endAngle [, counterclockwise ] )

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

Выдает исключение IndexSizeError если заданный радиус является отрицательным.

context . rect(x, y, w, h)

Добавляет новый закрытый подпуть в путь, представляющий заданный прямоугольник.

Следующие методы позволяют авторам манипулировать путями объектов, реализующих интерфейс CanvasPathMethods.

Для объектов CanvasRenderingContext2D, точки и линии добавленные к current default path с помощью этих методов должны быть преобразованы в соответствии с текущей матрицей трансформации перед тем как быть добавлены к пути.

Метод moveTo(x, y) должен создать новый подпуть с заданной точкой в качестве первой (и единственной) точки.

Когда пользовательский агент должен обеспечить там подпуть для координат (x, y) на path, агент пользователя должен проверить, чтобы убедиться, что path имеет любые подпути, и если нет, пользовательский агент должен создать новый подпуть с точкой (x, y) как его первой (и единственной) точкой, как если метод moveTo() был вызван.

Метод closePath() не должен ничего делать если путь объекта не имеет подпутей. В другом случае, он должен пометить последний подпуть как закрытый, создать новый подпуть первая точка которого та же что и первая точка предыдущего подпути, и наконец добавить этот подпуть к path.

Если последний подпуть имел больше чем одну точку в своем списке точек, то это эквивалентно добавлению прямой линии, соединяющей последнюю точку с первой точкой, таким образом "закрывает" форму, и потом повторяет последний (возможно подразумеваемый) вызов moveTo().

Новые точки и линии соединяющие их добавлены в подпути, с помощью методов описанных ниже. Во всех случаях, методы изменяют только последний подпуть в пути объекта.

Метод lineTo(x, y) должен обеспечить там подпуть для (x, y) если путь объекта не имеет подпутей. В другом случае, он должен соединить последнюю точку в подпути с заданной точкой (x, y) используя прямую линию, и должен затем добавить заданную точку (x, y) в подпуть.

Метод quadraticCurveTo(cpx, cpy, x, y) должен обеспечить там подпуть для (cpx, cpy), и затем должен соединить последнюю точку в подпути с заданной точной (x, y) используя квадратичную кривую Безье с контрольной точкой (cpx, cpy), и должен затем добавить заданную точку (x, y) в подпуть. [BEZIER]

Метод bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) должен обеспечить там подпуть для (cp1x, cp1y), и затем должен соединить последнюю точку в подпути с заданной точкой (x, y) используя кубическую кривую Безье с контрольными точками (cp1x, cp1y) и (cp2x, cp2y). Затем, он должен добавить точку (x, y) в подпуть. [BEZIER]


Метод arcTo(x1, y1, x2, y2, radius) должен сначала обеспечить там подпуть для (x1, y1). Затем поведение основывается на аргументах и последней точке подпути, как указано ниже.

Отрицательные значения для radius должны вызвать показ IndexSizeError исключения.

Сделать точку (x0, y0) последней точкой в подпути.

Если точка (x0, y0) равняется точке (x1, y1) или если точка (x1, y1) равняется точке (x2, y2), или если радиус radius равен нолю, тогда метод должен добавить точку (x1, y1) в подпуть и соединить эту точку с предыдущей точкой (x0, y0) прямой линией.

В другом случае, если точки (x0, y0), (x1, y1), и (x2, y2) все лежат на одной прямой линии, метод должен добавить точку (x1, y1) в подпуть и соединить эту точку с предыдущей точкой (x0, y0) прямой линией.

В другом случае, сделать The Arc самой короткой дугой заданной окружностью имеющей радиус radius и которая имеет одну точку касательной к полубесконечной линии, которая пересекает точку (x0, y0) и заканчивает в точке (x1, y1), и которая имеет другую точку касательную к полубесконечной линии, которая заканчивается в точке (x1, y1), и пересекает точку (x2, y2). В точках, в которых этот круг прикасается, эти две называются началом и концом точки касания соответственно. Метод должен соединять точку (x0, y0) с точкой касательной старта по прямой линии, добавляя начальную касательную точку в подпуть, затем должен соединить начальную касательную линию с конечной касательной линией к The Arc, добавляя конечную касательную точку в подпуть.


Метод arc(x, y, radius, startAngle, endAngle, counterclockwise) рисует дугу.

Если контекст имеет какие-либо подпути, то этот метод должен добавить прямую линию от последней точки в подпути к начальной точке дуги. В любом случае, он должен нарисовать дугу между начальной точкой дуги и конечной точкой дуги, и добавить эти точки в подпуть. Дуга и ее начальная/конечная точки определяются как следующие:

Рассмотрим круг, который имеет свое происхождение в (x, y) и его радиус radius. Точки в startAngle и endAngle окружности этого круга, измеренные в радианах по часовой стрелке от положительной оси х, являются начальной и конечной точкой соответственно.

Если аргумент counterclockwise ложный и endAngle-startAngle равняются или более чем , или если аргумент counterclockwise является true и startAngle-endAngle равняются или более чем , то дуга это вся окружность этого круга.

В другом случае, дуга это путь по окружности круга от начальной до конечной точки, идущая против часовой стрелки если аргумент counterclockwise равен true, и по часовой стрелке если нет. Так как точки на окружности, а не просто углы от нуля, дуга никогда не может покрыть угол больше чем радиус. Если две точки одинаковы или радиус равен нулю, то дуга определяется нулевой длины в обоих направлениях.

Негативные значение для radius должны вызывать показ IndexSizeError исключения.


Метод rect(x, y, w, h) должен создавать новый подпуть содержащий только 4 точки (x, y), (x+w, y), (x+w, y+h), (x, y+h), с этими четырьмя точками соединенными прямыми линиями, и затем должен пометить подпуть закрытым. Затем он должен создать новый подпуть с точкой (x, y) как единственной.

6 Преобразования

Каждый объект CanvasRenderingContext2D имеет текущую матрицу преобразования, как и методы (описанные в этом разделе) для управления им. Когда объект CanvasRenderingContext2D создан, его матрица преобразования должна быть инициализирована к идентичности преобразования.

Матрица преобразования применяется к координатам при создании текущего пути и когда рисуется текст, формы, пути на объектах CanvasRenderingContext2D.

Большая часть API использует объекты SVGMatrix, а не этого API. Этот API остается в основном по историческим причинам.

Преобразования должны быть выполнены в обратном порядке.

Например, если преобразование масштабированием, которое удваивает ширину, идет перед преобразованием поворотом, при рисовании прямоугольника ширина которого в два раза меньше высоты, фактически выйдет квадрат.

context . scale(x, y)

Меняет матрицу преобразования, чтобы применить преобразование масштабированием с заданными характеристиками.

context . rotate(angle)

Меняет матрицу преобразования, чтобы применить преобразование поворотом с заданными характеристиками. Угол в радианах.

context . translate(x, y)

Меняет матрицу преобразования, чтобы применить преобразование перемещения с заданными характеристиками.

context . transform(a, b, c, d, e, f)

Меняет матрицу преобразования, чтобы применить матрицу с заданными аргументами, как описано ниже.

context . setTransform(a, b, c, d, e, f)

Меняет матрицу преобразования на матрицу с заданными аргументами, как описано ниже.

Метод scale(x, y) должен добавить масштабирующее преобразование, описанное аргументами в матрице преобразования. Аргумент x представляет собой масштабный коэффициент в горизонтальном направлении, и аргумент y представляет собой масштабный коэффициент в вертикальном направлении. Факторы являются кратными.

Метод rotate(angle) должен добавить поворотное преобразование, описанное аргументами в матрице преобразования. Аргумент angle представляет собой угол поворота по часовой стрелке выраженный в радианах.

Метод translate(x, y) должен добавить преобразование перемещения, описанное аргументами в матрице преобразования. Аргумент x представляет собой дистанцию перемещения в горизонтальном направлении, и аргумент y представляет собой дистанцию перемещения в вертикальном направлении. Аргументы в координатном пространстве единиц.

Метод transform(a, b, c, d, e, f) должен заместить текущую матрицу преобразования результатом умножения текущей матрицы и матрицы описанной с помощью:

a c e
b d f
0 0 1

Аргументы a, b, c, d, e, и f иногда называются m11, m12, m21, m22, dx, и dy или m11, m21, m12, m22, dx, и dy. Следует проявлять осторожность, в частности, с порядком второго и третьего аргументов (b and c), поскольку их порядок варьируется от API к API и они иногда используют обозначения m12/m21 и иногда m21/m12 для этих позиций.

Метод setTransform(a, b, c, d, e, f) должен сбросить текущее преобразование к единичной матрице, затем вызвать метод transform(a, b, c, d, e, f) с теми же аргументами.

7 Источники изображений для 2D рендеринга

Этот объединенный тип позволяет объектам реализовать любой из следующих интерфейсов как источник изображения:

Когда агент пользователя должен проверить пригодность аргумента image, где image является объектом CanvasImageSource, агент пользователя должен следовать следующим шагам, которые возвращают good, bad или aborted:

  1. Если аргумент image является объектом HTMLImageElement в битом состоянии, тогда показать InvalidStateError исключение, возвратить aborted и прервать эти шаги.

  2. Если аргумент image является объектом HTMLImageElement который не полностью декодируемый или если аргумент image является объектом HTMLVideoElement который readyState атрибут либо ничего не содержит или имеет метаданные, тогда возвратить bad и прервать эти шаги.

  3. Если аргумент image является объектом HTMLImageElement с шириной или высотой (или обоими) равными нулю, тогда возвратить bad и прервать эти шаги.

  4. Если аргумент image является объектом HTMLCanvasElement с горизонтальной или вертикальной размерностью равными нулю, тогда возвратить bad и прервать эти шаги.

  5. Возвратить good.

Когда объект CanvasImageSource представляет собой HTMLImageElement, изображение элемента должно использоваться как исходное изображение.

В частности, когда обект CanvasImageSource представляет собой анимированное изображение в HTMLImageElement, агент пользователя должен использовать дефолтное изображение анимации (то которое формат определяет быть использованным когда анимация не поддерживается или отключена), или если там нет такого изображения, первый кадр анимации при визуализации изображения для CanvasRenderingContext2D API.

Когда объект CanvasImageSource представляет собой HTMLVideoElement, тогда кадр в текущей playback позиции. Когда метод с аргументом вызваны, должно быть использовано исходное изображение при визуализации изображения для CanvasRenderingContext2D API, и размеры исходного изображения должны быть внутренней ширины и внутренней высоты от источника медиа (т.е. после того как любая коррекция соотношения была применена).

Когда объект CanvasImageSource представляет собой HTMLCanvasElement, битмап элемента должен быть использован как исходное изображение.

Аргумент image не изначально чист если это HTMLImageElement или HTMLVideoElement чье начало не то же как начало заданное в объекте настройки, или если это HTMLCanvasElement битмап которого с ложным флагом origin-clean, или если это объект CanvasRenderingContext2D битмап которого с ложным флагом origin-clean.

8 Стили заполнения и обводки

context . fillStyle [ = value ]

Возвращает текущий стиль используемый для заполнения форм.

Может быть установлен, чтобы изменить стиль заполнения.

Стиль может быть строкой, содержащей цвет CSS, либо CanvasGradient или объект CanvasPattern. Неверные значения игнорируются.

context . strokeStyle [ = value ]

Возвращает текущий стиль используемый для сглаживания форм.

Может быть установлен, чтобы изменить стиль сглаживания.

Стиль может быть строкой содержащей цвет CSS, либо CanvasGradient или объект CanvasPattern. Неверные значения игнорируются.

Атрибут fillStyle представляет собой цвет или стиль используемый внутри форм, и атрибут strokeStyle представляет собой цвет или стиль используемый для линий вокруг форм.

Оба атрибута могут быть строки или CanvasGradient, или CanvasPattern. При настройке, строки должны быть прочитаны как значения цвета CSS. Объекты CanvasGradient и CanvasPattern должны назначать сами себя [CSSCOLOR]. Если значение строчное, но не может быть прочитано как значение цвета CSS, не является строкой CanvasGradient или CanvasPattern, тогда должно быть проигнорировано и атрибут должен возвратиться к предыдущему значению. Если новое значение это объект CanvasPattern помеченный как not origin-clean, тогда флаг битмапа origin-clean должен быть поставлен ложный.

Когда контекст создан, атрибуты fillStyle и strokeStyle должны изначально иметь строчное значение #000000.

Если значение является цветом, на него не должна влиять матрица преобразования.


Существует два типа градиентов, линейный градиент и радиальный, оба представлены объектами реализующими непрозрачный интерфейс CanvasGradient.

Когда градиент был создан (смотрите выше), остановки (stops) расположены вдоль него, чтобы определить, как цвета распределены вдоль градиента. Цвет градиента на каждой остановке это цвет указанный для нее. Между каждой такой остановкой цвета и альфа-компонент должны быть линейно интерполированы над RGBA пространством без умножения альфа значения, чтобы найти цвет используемый на этом смещении. Перед первой остановкой, цвет должен быть цветом первой остановки. После последней остановки, цвет должен быть цветом последней остановки. Когда нет остановок, градиент является прозрачным черным.

gradient . addColorStop(offset, color)

Добавляет цвет остановки с заданным цветом градиента на заданное смещение. 0.0 это смещение на одном конце градиента, 1.0 - на другом.

Выдает исключение IndexSizeError если смещение не в диапазоне. Выдает исключение SyntaxError если цвет не может быть прочитан.

gradient = context . createLinearGradient(x0, y0, x1, y1)

Возвращает объект CanvasGradient который представляет линейный градиент, рисующий вдоль заданной линии с помощью координат.

gradient = context . createRadialGradient(x0, y0, r0, x1, y1, r1)

Возвращает объект CanvasGradient, представляющий радиальный градиент, рисующий вдоль конуса с помощью кругов представленных в аргументах.

Если какой-то из радиусов негативный, выдает исключение IndexSizeError.

Метод addColorStop(offset, color) на интерфейсе CanvasGradient добавляет новую остановку в градиент. Если offset меньше чем 0 или больше чем 1, тогда должно быть показано исключение IndexSizeError. Если color не может быть прочитан как значение CSS <color>, тогда показывается исключение SyntaxError. В другом случае, градиент должен иметь размещенную остановку на смещении offset по отношению ко всему градиенту и цветом полученным при чтении color как значения CSS <color>. Если множество остановок добавляются в одно и тоже смещение, они должны быть расположены в порядке добавления, с первой на начале градиента и каждой последующей на ничтожном растоянии от друг друга вдоль линии.

Метод createLinearGradient(x0, y0, x1, y1) принимает четыре аргумента, которые представляют собой начальную точку (x0, y0) и конечную точку (x1, y1) градиента. Метод должен возвратить линейный CanvasGradient инициализируемый в указанной строке.

Линейные градиенты должны визуализироваться таким образом, чтоб все точки на линии перпендикулярной к линии пересекающей начальную и конечную точку, имели цвет в точке где эти две линии пересекаются (с цветами исходящими от интерполяции и экстраполяции описанных выше). Точки в линейном градиенте должны преобразоваться как описано текущей матрицей преобразования при визуализации (рендеринге).

Если x0 = x1 и y0 = y1, то линейный градиент не должен рисовать ничего.

Метод createRadialGradient(x0, y0, r0, x1, y1, r1) принимает шесть аргументов, первые три представляют собой начало круга с началом (x0, y0) и радиусом r0, последние три представляют собой конец круга с началом (x1, y1) и радиусом r1. Значения в координатном пространстве единиц. Если что-то из r0 или r1 являются негативными, должно показаться исключение IndexSizeError. В другом случае, метод должен возвратить радиальный CanvasGradient с двумя заданными кругами.

Радиальные градиенты должны быть визуализированы при помощи следующих шагов:

  1. Если x0 = x1 и y0 = y1 и r0 = r1, то радиальный градиент не должен рисовать ничего. Прервать эти шаги.

  2. Сделать x(ω) = (x1-x0)ω + x0

    Сделать y(ω) = (y1-y0)ω + y0

    Сделать r(ω) = (r1-r0)ω + r0

    Сделать цвет в ω цветом в позиции на градиенте (с цветами исходящими из интерполяции и экстраполяции описанных выше).

  3. Для всех значений ω где r(ω) > 0, начинать со значения ω ближайшего к положительной бесконечности и заканчивать со значением ω ближайшим к негативной бесконечности, нарисовать окружность с радиусом r(ω) на позиции (x(ω), y(ω)), с цветом в ω, но только рисовать на частях холста (canvas) которые еще не были зарисованы раннее на этом шаге.

Это фактически создает конус, затронутый двумя кругами определенными в создании градиента, с частью конуса перед началом круга (0.0) цвета первого смещения и частью конуса после конечного круга (1.0) цвета последнего смещения, а зоны за конусом не затронуты градиентом (прозрачный черный).

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

Градиенты должны быть нарисованы только когда соответствующие сглаживания или эффекты заполнения требуют чтобы они были нарисованы.


Паттерны представлены объектами реализующими прозрачный CanvasPattern интерфейс.

pattern = context . createPattern(image, repetition)

Возвращает объект CanvasPattern, который использует данное изображение и повторяет в направлении заданном аргументом repetition.

Допустимые значения repetition: "repeat" (оба направления), "repeat-x" (горизонтальное), "repeat-y" (вертикальное) и "no-repeat" (ни один). Если аргумент repetition пуст, значение repeat используется.

Если изображение не имеет данных, выдается исключение InvalidStateError. Если второй аргумент не один из допустимых, выдается исключение SyntaxError. Если изображение еще не полностью декодировано, то аргумент возвращает null.

Для создания объектов этого типа используется метод createPattern(image, repetition). Когда метод вызван, пользовательский агент должен выполнить следующие шаги:

  1. Сделать image первым аргументом и repetition — вторым.
  2. Проверить пригодность аргумента изображения. Если это возвращает aborted, тогда показывается исключение и метод не возвращает ничего; прервать эти шаги. Если возвращает bad, тогда возвратить null прервать эти шаги. В другом случае это возвращает good; продолжить эти шаги.
  3. Если repetition пустая строка, сделать ее "repeat".
  4. Если repetition не один из: "repeat", "repeat-x", "repeat-y", or "no-repeat", выдать исключение SyntaxError и прервать эти шаги.
  5. Создать новый объект CanvasPattern с изображением image и поведением повторения заданным repetition.
  6. Если если аргумент не origin-clean, пометить объект CanvasPattern как not origin-clean.
  7. Возвратить объект CanvasPattern.

Изменения этого изображения после вызова метода createPattern() не должно влиять на паттерн.

Паттерны должны быть нарисованы так что верхняя левая часть первого изображения закреплена в начале координатного пространства, затем изображения повторяются по горизонтали слева направо, если строка была задана строка repeat-x, или вертикально сверху вниз, если была задана строка repeat-y, или во всех четырех направлениях всего холста, если была задана строка repeat. Изображения не масштабируются в этом процессе; один CSS пиксель изображения должен быть нарисован на одной координатной единице. Когда отображено, однако, паттерны должны быть нарисованы только там где эффекты сглаживания или заполнения требуют этого, и паттерн повторения должен быть затронут текущей матрицей преобразования. Пиксели не охватываемые паттерном повторения (если строка repeat не задана) должны быть прозрачными черными.

Если данные исходного изображения растровые, значение нарисованное в точке в зоне повторений вычисляются фильтрованием данных исходного изображения. Пользовательский агент может использовать любой алгоритм фильтрования (например, билинейной интерполяции или схожий).


Если радиальный градиент или паттерн повторения используется когда матрица преобразования сингулярна, в результате стиль должен быть прозрачный черный (в другом случае градиент или паттерн разрушились бы до точки или линии, оставив другие пиксели неопределенными). Линейные градиенты и цвета всегда определяют все точки даже с сингулярной матрицей преобразования.

9 Рисование прямоугольников на холсте

Есть три метода которые сразу рисуют прямоугольники на битмапе. Каждый из них принимает четыре аргумента; первые два задают координаты x и y верхнего левого угла, а вторые два задают ширину w и высоту h прямоугольника, соответственно.

Текущая матрица преобразования должна быть применена к следующим четырем координатам, которые формируют путь который затем должен быть закрыт чтобы получился заданный прямоугольник: (x, y), (x+w, y), (x+w, y+h), (x, y+h).

Фигуры рисуются без влияния current default path и подлежат clipping region, за исключением clearRect(), также эффектов теней, global alpha, and global операторов.

context . clearRect(x, y, w, h)

Очищает все пиксели на холсте в заданном прямоугольнике к прозрачному черному.

context . fillRect(x, y, w, h)

Рисует заданный прямоугольник на холсте, используя текущий стиль заполнения.

context . strokeRect(x, y, w, h)

Рисует прямоугольник на холст, используя текущий строчный стиль.

Метод clearRect(x, y, w, h) должен выполнить следующие шаги:

  1. Сделатьpixels сетом пикселей в заданном прямоугольнике, которые также пересекают текущий clipping region.

  2. Очистить пиксели в pixels к полностью прозрачному черному, удаляя любое предыдущее изображение.

  3. Очистить регионы которые покрывают пиксели в pixels в элементе canvas.

Если высота или ширина равна нулю, этот метод не имеет эффекта, так как сет пикселей будет пустым.

Метод fillRect(x, y, w, h) должен нарисовать указанную прямоугольную область в fillStyle. Если ширина или высота равна нулю, этот метод не имеет эффекта.

Метод strokeRect(x, y, w, h) должен принять результат от tracing the path описанного ниже, используя стили линий объекта CanvasRenderingContext2D и заполнить с strokeStyle.

Если оба w и h равны нулю, путь имеет один подпуть только с одной точкой (x, y), без линий, и этот метод не имеет эффекта (алгоритм trace a path возвращает пустой путь в этом случае).

Если только один из w и h равен нулю, тогда путь имеет один подпуть с двумя точками, с координатами (x, y) и (x+w, y+h), в этом порядке, соединенные одной прямой линией.

В другом случае, путь имеет один подпуть содержащий четыре точки с координатами (x, y), (x+w, y), (x+w, y+h) и (x, y+h), соединенные друг с другом прямыми линиями.

10 Рисование текста на холсте

context . fillText(text, x, y [, maxWidth ] )
context . strokeText(text, x, y [, maxWidth ] )

Заполнения и обводки (соответственно) заданного текста на заданной позиции. Если максимальная ширина задана, при необходимости текст будет отрегулирован чтобы соответствовать ей.

metrics = context . measureText(text)

Возвращает объект TextMetrics с метрикой данного текста в текущем шрифте.

metrics . width

Возвращает ширину текста, который был передан методом measureText().

Интерфейс CanvasRenderingContext2D обеспечивает следующие методы для отображения текста непосредственно на холст.

Методы fillText() и strokeText() принимают три или четыре аргумента: text, x, y, и опционально maxWidth, и отображают заданный text на заданных (x, y) координатах, обеспечивая текст не шире чем maxWidth если это задано, используя текущие значения font, textAlign и textBaseline. А именно, когда методы вызываются, агент пользователя должен выполнить следующие шаги:

  1. Запустить алгоритм подготовки текста, передавая ему text, объект CanvasRenderingContext2D и, если аргумент maxWidth был задан, этот аргумент. Сделать glyphs результатом.

  2. Переместить все фигуры в glyphs вправо на x CSS пикселей и вниз на y CSS пикселей.

  3. Нарисовать формы заданные в glyphs, как преобразованные с помощью текущей матрицы преобразования, с каждым CSS пикселем в координатном пространстве glyphs.

    Для fillText(), fillStyle должен применяться к формам и strokeStyle должен быть проигнорирован. Для strokeText() наоборот: strokeStyle должен примениться к результату начертания с помощью объекта CanvasRenderingContext2D для стилей линий, и fillStyle должен быть проигнорирован.

    Эти формы рисуются без влияния текущего пути и подлежат эффектам теней, global alpha, clipping region и global composition операторам.

  4. Если алгоритм подготовки текста использует шрифт который имеет происхождение, которое не то же, что происхождение описанное в entry settings object (даже если "использование шрифта" означает просто проверку имеет ли этот шрифт особый глиф, перед переходом к другому шрифту), тогда установить флаг битмапа origin-clean ложным.

Метод measureText() принимает один аргумент, text. Когда метод вызван, пользовательский агент должен запустить алгоритм подготовки текста, передать новый объект TextMetrics с его атрибутами установленными как описано в следующем списке. Если при выполнении этих измерений необходимо использовать шрифт, который имеет происхождение которое не то же что у объекта Document который содержит элемент canvas (даже если "использование шрифта" означает просто проверку имеет ли этот шрифт особый глиф, перед переходом к другому шрифту), тогда метод должен выдать исключение SecurityError. В другом случае, он должен возвратить новый объект TextMetrics. [CSS]

Атрибут width

Ширина этого инлайн-бокса в CSS пикселях. (Расстояние между глифами в тексте.)

Если при выполнении этих измерений необходимо использовать шрифт, который имеет происхождение которое не то же что у объекта Document который содержит элемент canvas (даже если "использование шрифта" означает просто проверку имеет ли этот шрифт особый глиф, перед переходом к другому шрифту), тогда метод должен выдать исключение SecurityError. В другом случае, он должен возвратить новый объект TextMetrics. [CSS]

Интерфейс TextMetrics используется для объектов возвращенных от measureText(). Он имеет один атрибут, width, который устанавливается методом measureText().

Будущая версия 2D context API может обеспечивать путь к отображению фрагментов документов с помощью CSS, прямо на холст.

11 Рисование пути на холсте

Контекст всегда имеет текущий путь по умолчанию. Есть только один текущий путь, это не часть состояния рисования. Текущий путь является path, как описано выше.

context . beginPath()

Сбрасывает текущий путь.

context . fill()

Заполняет подпути текущего пути или заданного пути текущим стилем заполнения.

context . stroke()

Сглаживает подпути текущего или заданного пути текущим стилем сглаживания.

context . drawFocusIfNeeded(element)

Информирует пользователя холста о месте запасного элемента, на основе текущего пути. Если заданный элемент имеет фокус, рисует обводку фокуса вокруг текущего пути, следуя правилам платформы или пользовательского агента.

context . clip()

В дальнейшем ограничивает clipping region текущему пути.

context . isPointInPath(x, y)

Возвращает true если заданная точка имеется в текущем пути.

Метод beginPath() должен очистить список подпутей в текущем пути контекста, поэтому здесь в очередной раз ноль подпутей.

Метод fill() должен заполнить все подпути текущего пути, используя fillStyle. Открытые подпути должны быть неявно закрыты при заполнении (без влияния на фактические подпути).

Таким образом, если пересекаются два подпути, имеющие разные витки, они компенсируются и не приводят к заполнению. Если они имеют одинаковый виток, эта область просто рисуется один раз.

Метод stroke() должен чертить путь, используя объект CanvasRenderingContext2D для стилей линий, а затем заполнить общую площадь сглаживания с помощью атрибута strokeStyle.

Стиль сглаживания зависит от преобразования во время рисования, даже если путь это текущий путь по умолчанию.

Пути, при заполнении или сглаживании, должны быть нарисованы без влияния текущего пути, но должны подвергаться эффектам теней, global alpha, clipping region и global composition операторов.

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


Метод drawFocusIfNeeded(element) при вызове должен выполнить следующие шаги:

  1. Если текущий путь имееть ноль подпутей, тогда прервать эти шаги.

  2. Если element не сфокусирован или не является вложенным элемента с которым контекст ассоциирован, прервать эти шаги.

  3. Если пользователь запросил использование отдельных контуров фокуса (например высококонтрастных контуров) или element будет иметь контур нарисованный вокруг него, тогда нарисовать контур фокуса соответствующего стиля вдоль намеченного пути, следуя правилам платформы.

    Некоторые платформы рисуют только линии фокуса вокруг элементов которые сфокусированы с помощью клавиатуры, а не с помощью мышки. Другие платформы вообще не рисуют линии фокуса вокруг некоторых элементов, если только соответствующая функция не включена. Этот API предназначен чтобы следовать данным правилам. Пользовательские агенты, которые реализуют это в зависимости от способа которым элемент был сфокусирован, поощряются делать это с помощью метода focus() основанном на способе вызова (если он был).

    Контуры фокуса не должны подвергаться эффектам теней, global alpha, или global composition операторам, но должны подвергаться clipping region. Когда зона фокуса обрезана с помощью элемента canvas, только визуальное представление контура фокуса вырезается в clipping region.

    Если зона фокуса не в пределах экрана, нужно прокрутить в видимую зону, тогда она получит фокус.

  4. Проинформировать пользователя о заданном расположении. Полное расположение соответствующего запасного элемента передается к доступному API, если оно поддерживается. Пользовательские агенты могут ждать до следующего раза, когда цикл обработки достигает своего шага "обновить рендеринг".

"Проинформировать пользователя", используемое в этом разделе, может означать вызов доступного API системы, которое будет уведомлять вспомогательные технологии, такие как инструменты увеличения.


Метод clip() должен создать новый clipping region путем вычисления пересечения текущей вырезанной области и зоной описаной с помощью пути, используя правило ненулевого индекса. Открытые подпути должны быть неявно закрыты при вычислении (без влияния на фактические подпути). Новая вырезанная область (clipping region) заменяет текущую вырезанную область.

При инициализации контекста, вырезанная область (clipping region) должна быть установлена прямоугольником с верхним левым углом на (0,0), с шириной и высотой координатного пространства.


Метод isPointInPath() должен возвращать true если точка заданная с помощью координат x и y при обработке как координат в координатном пространстве холста, не зависимо от текущего преобразования, внутри предполагаемого пути как определено правилом ненулевого индекса; и должен возвратить false в другом случае. Точки на самом пути должны рассматриваться как внутри пути. Если какой-то из аргументов равен бесконечности или NaN, тогда метод должен возвратить false.


12 Рисование изображений на холсте

Для того чтобы нарисовать изображение на холсте, используется метод drawImage.

Этот метод может быть вызван с тремя различными наборами аргументов:

Каждый из них может принять HTMLImageElement, HTMLCanvasElement или HTMLVideoElement для аргумента изображения image.

context . drawImage(image, dx, dy)
context . drawImage(image, dx, dy, dw, dh)
context . drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)

Рисует заданное изображение на холст. Аргументы интерпретируются следующим образом:

The sx and sy parameters give the x and y coordinates of the source rectangle; the sw and sh arguments give the width and height of the source rectangle; the dx and dy give the x and y coordinates of the destination rectangle; and the dw and dh arguments give the width and height of the destination rectangle.

Если первый аргумент не является элементом img, canvas или video, выдается исключение TypeMismatchError. Если изображение не содержит данных, выдается исключение InvalidStateError. Если один из размеров исходного прямоугольника равен нулю, выдается исключение IndexSizeError. Если изображение (еще) не полностью декодировано, ничего не рисуется.

Когда метод drawImage() вызван, пользовательский агент должен выполнить шаги:

  1. Проверить пригодность аргументаimage. Если возвращается aborted, то исключение было выдано и метод не выдает ничего; прервать эти шаги. Если возвращается bad, то прервать эти шаги ничего не рисуя. В другом случае возвращается good; продолжить.

  2. Установить источник и назначение прямоугольников как:

    Если не задано, аргументы dw и dh должны по умолчанию быть sw и sh, интерпретируемые таким образом, что один CSS пиксель в изображении рассматривается как единица в координатном пространстве единиц битмапа. Если аргументы sx, sy, sw и sh не заданы, по умолчанию они равняются 0, 0, внутренней ширине изображения в пикселях и внутренней высоте изображения в пикселях, соответственно. Если изображение не имеет внутренних размеров, должен быть использован конкретный размер объекта, как определено CSS алгоритмом "Concrete Object Size Resolution". Если же заданный размер не имеет указанных ширины/высоты и прочих параметров, внутренние данные объекта будут взяты из аргумента image, и размером объекта по умолчанию будет размер битмапа. [CSSIMAGES]

    Исходный прямоугольник — прямоугольник с углами в точках (sx, sy), (sx+sw, sy), (sx+sw, sy+sh), (sx, sy+sh).

    Конечный прямоугольник — с углами в точках (dx, dy), (dx+dw, dy), (dx+dw, dy+dh), (dx, dy+dh).

    Когда исходный прямоугольник за пределами исходного изображения, исходный прямоугольник должен быть обрезан под исходное изображение и конечный прямоугольник обрезан в той же пропорции.

    Когда конечный прямоугольник за пределами конечного изображения (битмапа), пиксели которые за пределами отбрасываются.

  3. Если один из аргументов sw или sh равен нулю, прервать эти шаги. Ничего не рисуется.

  4. Нарисовать зону аргумента image заданную исходным прямоугольником на зоне растрового изображения (битмапа) контекста заданной конечным прямоугольником, после применения текущей матрицы преобразования на конечном прямоугольнике.

    Данные изображения должны быть обработаны в изначальном направлении, даже если указаны отрицательные размеры.

    Данная спецификация не определяет алгоритм, используемый при масштабировании изображения.

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

    Если исходное изображение является растровым изображением, значение нарисованное на месте конечного прямоугольника вычисляется с помощью фильтрации данных исходного изображения. Агент пользователя может использовать любой алгоритм фильтрации (например, билинейной интерполяции или схожий). Когда алгоритм фильтрации требует значение пикселя за пределами оригинального изображения, он должен вместо этого использовать значение ближайшего пикселя с краю. Когда алгоритм фильтрации запрашивает значение пикселя извне исходного прямоугольника, но внутри оригинального изображения, следует использовать значение из оригинального изображения.

    Таким образом, масштабирование изображения по частям или в целом будет иметь тот же эффект.

    Изображения рисуются без влияния текущего пути (current path), но подлежат эффектам теней, global alpha, clipping region и global composition операторам.

  5. Если image argument не origin-clean, установить флаг origin-clean битмапа ложным.

Изображения рисуются без влияния текущего пути (current path), но подлежат эффектам теней, global alpha, clipping region и global composition операторам.

13 Hit области

Каждый элемент canvas чей основной контекст это объект CanvasRenderingContext2D, должен иметь список hit областей связанный с его битмапом.

Список hit областей это список из hit областей.

Каждая hit область содержит следующую информацию:

context . addHitRegion(options)

Добавляет hit область на холст, на основе текущего пути по умолчанию. Аргумент это объект со следующими членами:

id (по умолчанию пустая строка)
ID используемый для этой области. Он используется в событиях MouseEvent на canvas (event.region) и как путь к вызову этой области в последующих вызовах к addHitRegion().
control (по умолчанию null)
Элемент (потомок canvas) к которому события должны быть направлены, и который доступные инструменты используют как суррогат для описания и взаимодействия с этой областью.

Hit области могут быть использованы для различных целей:

В то время как ID и control не являются обязательными, при вызове addHitRegion, как минимум один из двух должен быть предоставлен чтобы создать hit область.

context . removeHitRegion(id)

Удаляет hit область с битмапа холста. Аргумент это ID области заданный с помощью addHitRegion().

Путь который был покрыт этой областью в результате этой операции очищается, оставляя область не-интерактивной. В частности, области которые занимали тот же путь перед тем как удаленные области были добавлены, не возобновляют свои прежние роли.

context . clearHitRegions()

Удаляет все hit области с битмапа холста.

Пути которые были покрыты этими областями в результате очищаются, оставляя все области не-интерактивными.

Область идентифицируемая с помощью ID ID в битмапе bitmap, это значение возвращаемое следующим алгоритмом (который может вернуть hit область или ничего):

  1. Если ID равен null, не возвращать ничего и прервать эти шаги.

  2. Сделать list списком hit областей связанным с bitmap.

  3. Если есть hit область в list которая ID чувствительна к регистру для ID, то вернуть эту hit область и прервать эти шаги.

  4. В другом случае, не возвращать ничего.

Область представляющая элемент управления control для битмапа bitmap это значение возвращенное с помощью следующего алгоритма (который может вернуть hit область или ничего):

  1. Если control равен null, не возвращать ничего и прервать эти шаги.

  2. Сделать list списком hit областей связанным с bitmap.

  3. Если есть hit область в list чей control равен control, то возвратить эту hit область и прервать эти шаги.

  4. В другом случае, не возвращать ничего.

Элемент управления представленный областью region для canvas элемента ancestor, это значение возвращаемое следующим алгоритмом (который может вернуть элемент или ничего):

  1. Если region не имеет control, не возвращать ничего и прервать эти шаги.

  2. Сделать control элементом управления области region.

  3. Если control не наследник ancestor, то не выдавать ничего и прервать эти шаги.

  4. В другом случае, возвратить control.

Область для пикселя pixel на битмапе bitmap это значение выдаваемое следующим алгоритмом (который может вернуть hit region или ничего):

  1. Сделать list списком hit областей связанным с bitmap.

  2. Если есть hit область в list чей путь содержит pixel, то возвратить эту hit область и прервать эти шаги.

  3. В другом случае, не возвращать ничего.


Когда вызван метод addHitRegion(), агент пользователя должен выполнить следующие шаги:

  1. Сделать arguments объектом для аргументов метода.

  2. Сделать source path текущим путем по умолчанию объекта CanvasRenderingContext2D.

  3. Сделать specified pixels пикселями внутри source path.

  4. Удалить из specified pixels все пиксели которые не содержатся внутри clipping region.

  5. Если id объекта arguments является пустой строкой, сделать его null.

  6. Если id объекта arguments является null и control объекта arguments является null, выдать исключение NotSupportedError и прервать эти шаги.

  7. Если id объекта arguments является null, то сделать previous region for this ID областью идентифицируемой ID заданным значением id для этого canvas. Если id является null или такой области сейчас нет, сделать previous region for this ID равным null.

  8. Если specified pixels не содержат пикселей, выдать исключение NotSupportedError и прервать эти шаги.

  9. Сделать region созданной hit областью, с ее информацией настроенной как:

    Путь hit области

    specified pixels.

    Ограничивающая окружность hit области

    Определенная агентом пользователя форма которая оборачивает пиксели содержащиеся в source path. (В простом случае, это может быть просто ограничивающий прямоугольник; эта спецификация позволяет ему иметь любую форму, чтобы поддерживать разные интерфейсы.)

    ID hit области

    Если id объекта arguments не является null: то значение id. В другом случае, region не имеет id.

    Hit region's control

    Если control объекта arguments не является null: то значение control. В другом случае, region не имеет control.

  10. Если control объекта arguments не является null, то сделать previous region for the control областью представляющей control заданным с control значением этого canvas элемента. Если control является null или такой области сейчас нет, сделать previous region for the control равным null.

  11. Если есть previous region with this control, удалить его с списка hit областей canvas.

  12. Если control объекта arguments не является null, проинформировать пользователя о расположении области представляющей control заданный с помощью значения control для этого элемента canvas. Полное местонахождение соответствующего резервного элемента, относящегося к control, передается к доступному API, если поддерживается.

  13. Если есть previous region with this ID, удалить его со списка hit областей canvas .

  14. Добавить region на список hit областей canvas.

Когда вызван метод removeHitRegion(), агент пользователя должен выполнить следующие шаги:

  1. Сделать region областью идентифицируемой с помощью ID заданным с помощью аргумента метода в этом canvas элементе, если есть. Если нет такой области на данный момент, прервать эти шаги.

    Если аргумент метода это пустая строка, то ни одна область не будет соответствовать.

  2. Удалить region со списка hit областей элемента canvas.

Когда вызван метод clearHitRegions(), агент пользователя должен выполнить следующие шаги:

  1. Удалить все hit regions с элемента canvas и очистить его список hit областей. Если нет областей на данный момент, прервать эти шаги.

Вызов clearRect() это способ очистить все или некоторые области. Вызов clearHitRegions() удаляет все hit области и очищает список hit областей. Список hit областей сбрасывается также когда визуализируемый контекст сброшен. Например, когда объект CanvasRenderingContext2D привязывается или отвязывается от canvas, или размеры битмапа меняются.


Интерфейс MouseEvent расширен для поддержки hit областей:

partial interface MouseEvent {
  readonly attribute DOMString? region;
};

partial dictionary MouseEventInit {
  DOMString? region;
};
event . region

Если мышь была над hit областью, то возвращает ID hit области, если она имеет его.

В другом случае, возвращает null.

Атрибут region на объектах MouseEvent должен возвратить значение на котором был инициализирован. Когда объект создан, этот атрибут должен быть установлен к null.

Когда MouseEvent генерируется на элементе canvas с помощью агента пользователя в ответ на наведение мышки, если элемент canvas имеет список hit областей, агент пользователя должен вместо этого выполнить следующие шаги. Если здесь указано действовать в обычном режиме, это означает что событие должно быть сгенерировано как если бы эти требования не были применены.

  1. Если указательное устройство (мышь или др.) не указывает на пиксель на холсте, действовать в обычном режиме и прервать эти шаги.

  2. Если элемент canvas не имеет списка hit областей, действовать в обычном режиме и прервать эти шаги.

  3. Сделать пиксель указанным с помощью указательного устройства.

  4. Сделать область hit областью для пикселя pixel на этом битмапе элемента canvas.

  5. Сделать id значением ID области region, если есть.

  6. Если есть id, то установить атрибут объекта события region к id.

  7. Отправить событие, но с обновлением объекта события как задано предыдущими шагами.

Такой подход упрощает обработку событий, не перенацеливая событие. Событие отправляется в обычном режиме как только атрибут event.region установлен к активному ID hit области. Событие полученное с помощью элемента canvas позволяет автору определять поведение события.


Агентам пользователя рекомендуется использовать информацию, предоставленную в списке hit областей элемента canvas, для улучшения доступности элементов canvas.

Каждая hit область должна быть обработана в эквиваленте узла в виртуальном дереве DOM с корнем на canvas элементе. Иерархия этого виртуального дерева DOM должна соответствовать иерархии hit областей. Для каждого узла в таком дереве DOM, ограничивающая окружность hit области задает область экрана для использования при представлении узла (если необходимо).

Семантика hit области для целей этого виртуального дерева DOM это control hit области, если имеется.

Для целей доступных инструментов, когда элемент C является потомком элемента canvas и есть область представляющая control C, то позиция элемента относительно документа должна быть представлена как если бы эта область была в виртуальном дереве DOM элемента canvas.


14 Пиксельная манипуляция

imagedata = context . createImageData(sw, sh)

Возвращает объект ImageData с заданными размерами в пикселях CSS (которые могут отображаться в другом количестве фактических пикселей устройства). Все пиксели в возвращаемом объекте — прозрачные черные.

imagedata = context . createImageData(imagedata)

Возвращает объект ImageData с теми же размерами как в аргументе. Все пиксели в возвращаемом объекте — прозрачные черные.

imagedata = context . getImageData(sx, sy, sw, sh)

Возвращает объект ImageData содержащий данные изображения для заданного прямоугольника на холсте.

Выдает исключение IndexSizeError если ширина или высота равны нулю.

Данные будут возвращены с одним пикселем данных изображения для каждой единицы координатного пространства на холсте (игнорируя преобразования).

imagedata . width
imagedata . height

Возвращает фактические размеры данных в объекте ImageData, в пикселях устройства.

imagedata . data

Возвращает одномерный массив содержащий данные в порядке RGBA, такие как целые числа в диапазоне от 0 до 255.

context . putImageData(imagedata, dx, dy [, dirtyX, dirtyY, dirtyWidth, dirtyHeight ])

Рисует данные с заданного объекта ImageData на холст. Если предоставлен dirty прямоугольник, рисуются только пиксели с этого прямоугольника.

Атрибуты globalAlpha и globalCompositeOperation, также как и атрибуты теней, игнорируются для целей вызова этого метода; пиксели на холсте заменяются оптом, без композиции, альфа-смешивания, без теней и т.д.

Выдает исключение NotSupportedError если какой-то из этих аргументов не конечное число.

Метод createImageData() используется для создания экземпляров новых пустых объектов ImageData. Когда метод вызван с двумя аргументами sw и sh, он должен вернуть объект ImageData представляющий прямоугольник с шириной в пикселях CSS равной абсолютной величине sw и высотой в пикселях CSS равной абсолютной величине sh. Когда вызван только с аргументом imagedata, он должен возвратить объект ImageData представляющий прямоугольник с теми же размерами что и объект ImageData как передано аргументом. Возвращенный объект ImageData должен быть заполнен прозрачным черным.

Метод getImageData(sx, sy, sw, sh) должен, если флаг битмап элемента canvas origin-clean установлен ложный, выдать исключение SecurityError; в другом случае, должен возвратить объект ImageData представляющий базовые данные пикселей для области холста, обозначаемой прямоугольником, чьи углы в четырех точках (sx, sy), (sx+sw, sy), (sx+sw, sy+sh), (sx, sy+sh), в координатном пространстве canvas. Пиксели за пределами холста должны быть возвращены как прозрачный черный. Пиксели возвращаются как не предварительно умноженные альфа значения.

Если любые аргументы createImageData() или getImageData() бесконечны или NaN, метод должен выдать исключение NotSupportedError. Если один из аргументов sw или sh равен нолю, метод должен выдать исключение IndexSizeError.

Объекты ImageData должны быть инициализированы так, чтобы их атрибут width был установлен w, количество пикселей в строке устройства в данных изображения, их атрибут height был установлен к h, количество строк в данных изображения, и их атрибут data инициализирован к объекту Uint8ClampedArray. Объект Uint8ClampedArray должен использовать Canvas Pixel ArrayBuffer для его хранения, и должен иметь нулевое начальное смещение, и длину равную длине его хранилища в байтах. Canvas Pixel ArrayBuffer должен содержать данные изображения. Как минимум одна сумма пикселя данных изображения должна быть возвращена. [TYPEDARRAY]

Canvas Pixel ArrayBuffer это ArrayBuffer, данные которого представлены в порядке справа-налево, построчно сверху вниз, начиная с верха слева, с каждым красным, зеленым, синим и альфа-компонентом пикселя, приведенными в этом порядке для каждого пикселя. Каждый компонент каждого пикселя устройства представленный в этом массиве должен находиться в диапазоне 0..255, представляя 8-битное значение для этого компонента. Компонентам должны быть назначены последовательные индексы начиная с 0 для верхнего левого красного компонента пикселя. [TYPEDARRAY]

Метод putImageData(imagedata, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight) записывает данные со структур ImageData обратно на холст.

Если какой-то из аргументов в методе бесконечен или NaN, метод должен выдать исключение NotSupportedError.

Когда последние четыре аргументе опущены, они должны считаться со значениями 0, 0 — width структуры imagedata и height структуры imagedata, соответственно.

Когда вызван с аргументами, которые не выдают исключение, метод putImageData() должен действовать следующим образом:

  1. Сделать dxdevice x-координатой пикселей устройства, соответствующей dx координатам в координатном пространстве canvas.

    Сделать dydevice y-координатой пикселей устройства, соответствующей dy координатам в координатном пространстве canvas.

  2. Если значение dirtyWidth негативное, сделать dirtyX dirtyX+dirtyWidth и сделать dirtyWidth равным абсолютной величине dirtyWidth.

    Если значение dirtyHeight негативное, сделать dirtyY dirtyY+dirtyHeight и сделать dirtyHeight равным абсолютной величине dirtyHeight.

  3. Если значение dirtyX негативное, сделать dirtyWidth dirtyWidth+dirtyX и сделать dirtyX равным нулю.

    Если значение dirtyY негативное, сделать dirtyHeight dirtyHeight+dirtyY и сделать dirtyY равным нулю.

  4. Если dirtyX+dirtyWidth больше чем атрибут width аргумента imagedata, сделать dirtyWidth значением атрибута width минус значение dirtyX.

    Если dirtyY+dirtyHeight больше чем атрибут height аргумента imagedata, сделать dirtyHeight значением атрибута height минус значение dirtyY.

  5. Если после этих изменений одно из dirtyWidth или dirtyHeight равно нолю или меньше ноля, остановить эти шаги без влияния на холст.

  6. В другом случае, для всех целых значений x и y, где dirtyXx < dirtyX+dirtyWidth и dirtyYy < dirtyY+dirtyHeight, копировать четыре канала пикселя с координатами (x, y) из данных структуры imagedata на пиксель с координатами (dxdevice+x, dydevice+y) базовых данных пикселей canvas.

Текущий путь, матрица преобразования, атрибуты теней, global alpha, clipping region и global composition оператор не должны влиять на методы getImageData() и putImageData().


В следующем примере, скрипт генерирует объект ImageData таким образом, что он может рисовать на нем.

// canvas is a reference to a <canvas> element
var context = canvas.getContext('2d');

// create a blank slate
var data = context.createImageData(canvas.width, canvas.height);

// create some plasma
FillPlasma(data, 'green'); // green plasma

// add a cloud to the plasma
AddCloud(data, data.width/2, data.height/2); // put a cloud in the middle

// paint the plasma+cloud on the canvas
context.putImageData(data, 0, 0);

// support methods
function FillPlasma(data, color) { ... }
function AddCloud(data, x, y) { ... }

Ниже приведен пример использования getImageData() и putImageData() для реализации фильтра обнаружения края.

<!DOCTYPE HTML>
<html>
 <head>
  <title>Edge detection demo</title>
  <script>
   var image = new Image();
   function init() {
     image.onload = demo;
     image.src = "image.jpeg";
   }
   function demo() {
     var canvas = document.getElementsByTagName('canvas')[0];
     var context = canvas.getContext('2d');

     // draw the image onto the canvas
     context.drawImage(image, 0, 0);

     // get the image data to manipulate
     var input = context.getImageData(0, 0, canvas.width, canvas.height);

     // get an empty slate to put the data into
     var output = context.createImageData(canvas.width, canvas.height);

     // alias some variables for convenience
     // notice that we are using input.width and input.height here
     // as they might not be the same as canvas.width and canvas.height
     // (in particular, they might be different on high-res displays)
     var w = input.width, h = input.height;
     var inputData = input.data;
     var outputData = output.data;

     // edge detection
     for (var y = 1; y < h - 1; y += 1) {
       for (var x = 1; x < w - 1; x += 1) {
         for (var c = 0; c < 3; c += 1) {
           var i = (y*w + x)*4 + c;
           outputData[i] = 127 + -inputData[i - w*4 - 4] -   inputData[i - w*4] - inputData[i - w*4 + 4] +
                                 -inputData[i - 4]       + 8*inputData[i]       - inputData[i + 4] +
                                 -inputData[i + w*4 - 4] -   inputData[i + w*4] - inputData[i + w*4 + 4];
         }
         outputData[(y*w + x)*4 + 3] = 255; // alpha
       }
     }

     // put the image data back after manipulation
     context.putImageData(output, 0, 0);
   }
  </script>
 </head>
 <body onload="init()">
  <canvas></canvas>
 </body>
</html>

15 Композиция

context . globalAlpha [ = value ]

Возвращает текущее альфа значение применяемое к операциям визуализиции.

Может быть установлен, чтобы изменить альфа значение. Значения вне диапазона 0.0 .. 1.0 игнорируются.

context . globalCompositeOperation [ = value ]

Возвращает текущую операцию композиции, из приведенного ниже списка.

Может быть установлен, чтобы изменить операцию композиции. Неизвестные значения игнорируются.

Все операции рисования затрагиваются global compositing атрибутами, globalAlpha и globalCompositeOperation.

Атрибут globalAlpha задает альфа значение которое применяется к формам и изображениям перед тем как они компонуются на холст. Значение должно быть в диапазоне от 0.0 (полностью прозрачный) до 1.0 (без прозрачности). При попытках установить атрибут к значению вне диапазона, включая бесконечность и NaN, атрибут должен вернуться к предыдущему значению. Когда контекст создан, атрибут globalAlpha должен изначально иметь значение 1.0.

Атрибут globalCompositeOperation устанавливает как формы и изображения рисуются на существующий битмап, как только они приняли globalAlpha и текущую матрицу преобразования. Он должен быть установлен к значению из следующего списка. В описании ниже, исходное изображение, A, это визуализируемые форма или изображение, и конечное изображение, B, это текущее состояние битмапа.

source-atop
A сверху B. Отображается исходное изображение везде где оба изображения непрозрачны. Отображается конечное изображение везде где конечное изображение непрозрачное, но исходное изображение прозрачное. Отображается прозрачность в других местах.
source-in
A в B. Отображается исходное изображение везде где оба изображения непрозрачны. Отображается прозрачность в других местах.
source-out
A вне B. Отображается исходное изображение везде где исходное изображение непрозрачно и конечное изображение прозрачно. Отображается прозрачность в других местах.
source-over (по умолчанию)
A над B. Отображается исходное изображение везде где исходное изображение непрозрачно. Отображается конечное изображение в других местах.
destination-atop
B сверху A. То же что и source-atop, но используя конечное изображение вместо исходного изображения и наоборот.
destination-in
B в A. То же что и source-in, но используя конечное изображение вместо исходного и наоборот.
destination-out
B вне A. То же что и source-out, но используя конечное изображение вместо исходного и наоборот.
destination-over
B над A. То же что и source-over, но используя конечное изображение вместо исходного и наоборот.
lighter
A плюс B. Отображается сумма исходного и конечного изображений, со значениями цвета до 255 (100%) как лимит.
copy
A (B игнорируется). Отображать исходное изображение вместо конечного изображения.
xor
A xor B. Исключается OR исходного и конечного изображений.
vendorName-operationName
Заданные вендором расширения этого списка должны использовать этот синтаксис.

Операторы из списка выше должны быть обработаны как описано оператором данным в начале их описания (например, A над B). Они должны быть применены как часть модели рисования, при которой также применяется clipping region. (Без clipping region, эти операторы действуют на всем битмапе с каждой операцией.) [PORTERDUFF]

Эти значения чувствительны к регистру — они должны использоваться точно как показано. Агенты пользователей должны не распознавать значений, которые не чувствительны к регистру для каждого значения из данных выше.

При настройке, если агент пользователя не распознает заданное значение, оно игнорируется, оставляя значение globalCompositeOperation не затронутым.

Когда контекст создан, атрибут globalCompositeOperation должен изначально иметь значение source-over.

16 Тени

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

context . shadowColor [ = value ]

Возвращает текущий цвет тени.

Может быть настроен, чтобы изменить цвет тени. Значения которые не читаются как цвета CSS, игнорируются.

context . shadowOffsetX [ = value ]
context . shadowOffsetY [ = value ]

Возвращает текущее смещение тени.

Может быть настроен, чтобы изменить смешение тени. Значения отличные от конечных чисел игнорируются.

context . shadowBlur [ = value ]

Возвращает текущий уровень размытия применяемый к теням.

Может быть настроен, чтобы изменить уровень размытия. Значения (конечные числа) больше ноля или равные ему, игнорируются.

Атрибут shadowColor устанавливает цвет тени.

Когда контекст создан, атрибут shadowColor изначально должен быть полностью прозрачным черным.

При получении, должна быть возвращена последовательность цвета.

При настройке, новое значение должно читаться как значение CSS <color>. Если значение не может читаться как значение CSS <color>, то оно игнорируется, и атрибут должен возвратиться к предыдущему значению. [CSSCOLOR]

Атрибуты shadowOffsetX и shadowOffsetY должны указать расстояние смещения тени в положительном горизонтальном и вертикальном расстоянии соответственно. Значения в координатном пространстве единиц. Они не затрагиваются текущей матрицей преобразования.

Когда контекст создан, атрибуты смещения тени должны изначально иметь значение 0.

При получении, они должны вернуть текущее значение. При настройке, значение должно меняться на новое значение, кроме случая если оно бесконечное или NaN, тогда новое значение игнорируется.

Атрибут shadowBlur определяет уровень эффекта размытия. (Единицы не связаны с координатным пространством и не затрагиваются текущей матрицей преобразования.)

Когда контекст создан, атрибут shadowBlur должен изначально иметь значение 0.

При получении, атрибут должен возвращать текущее значение. При настройке он меняется на новое значение, кроме случая если оно негативное, бесконечное или NaN, тогда новое значение игнорируется.

Тени рисуются только если альфа компонент цвета shadowColor не нулевой и хотя бы один из shadowBlur, shadowOffsetX или shadowOffsetY не нулевой.

Вполне вероятно, что это изменится: разработчики браузеров выразили заинтересованность в изменении модели обработки для теней таким образом, что они рисуются только когда оператор композиции имеет значение "source-over" (по умолчанию). Прочитать больше...

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

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

  2. Сделать B бесконечным прозрачным черным битмапом, чье координатное пространство и происхождение идентичны к A.

  3. Копировать альфа-канал A на B, смещение shadowOffsetX в положительном направлении x, и shadowOffsetY в положительном направлении y.

  4. Если shadowBlur больше чем 0:

    1. Сделать σ половиной значения от shadowBlur.

    2. Выполнить 2D размытие по Гауссу на B, используя σ как стандартное отклонение.

    Агенты пользователя могут ограничивать значения σ для реализации собственного максимального значения, чтоб избежать аппаратных ограничений во время операции размытия по Гауссу.

  5. Установить красный, зеленый и синий компоненты каждого пикселя в B к красному, зеленому и синему компонентам (соответственно) цвета в shadowColor.

  6. Умножить альфа компонент каждого пикселя в B на альфа компонент цвета shadowColor.

  7. Тень на битмапе B и она визуализируется как часть модели рисования описанной ниже.

Если текущая операция композиции это copy, тени не будут отображаться (т.к. фигура перекроет тень).

17 Модель рисования

Когда форма или изображение нарисованы, агенты пользователей должны следовать этим шагам в указанном порядке (или действовать как будто следуют):

  1. Визуализировать форму или изображение на бесконечно прозрачный черный битмап, создавая изображение A, как описано в предыдущих разделах. Для фигур текущее заполнение, обводки и стили должны быть выполнены, и сглаживание также должно быть подвергнуто текущей матрице преобразования.

  2. Когда тени нарисованы, визуализировать тень с изображения A, используя текущие стили изображения, создавая изображение B.

  3. Когда тени нарисованы, умножить альфа-компонент каждого пикселя в B с помощью globalAlpha.

  4. Когда тени нарисованы, добавить B в пределах clipping region над текущим битмапом холста с помощью current composition operator.

  5. Умножить альфа-компонент каждого пикселя в A с помощью globalAlpha.

  6. Добавить A в пределах clipping region над текущим битмапом холста с помощью current composition operator.

18 Советы

Этот раздел не является нормативным.

Когда холст является интерактивным, авторы должны включать фокусируемые элементы в содержание резерва элемента, соответствующие каждой фокусируемой части холста.

Для того чтобы указать какая часть холста сейчас сфокусирована, авторы должны использовать метод drawFocusIfNeeded(), передавая ему элемент для которого рисуется контур. Этот метод рисует контур только если элемент сфокусирован, так что он может просто быть вызван при рисовании элемента, без проверки является ли элемент сфокусированным или нет.


Авторы должны избегать реализации элементов редактирования текста при использовании canvas, потому что это имеет множество минусов: придется переписывать всё начиная от движения знака вставки до нативных возможностей типа копировать-вставить.

Это огромный объем работы, поэтому авторы должны быть сильно мотивированы не делать этого. Вместо этого можно использовать элемент input, элемент textarea или атрибут contenteditable.

19 Примеры

Этот раздел не является нормативным.

Ниже приведен пример кода, который использует canvas, чтобы нарисовать довольно яркие линии.

<canvas width="800" height="450"></canvas>
<script>

 var context = document.getElementsByTagName('canvas')[0].getContext('2d');

 var lastX = context.canvas.width * Math.random();
 var lastY = context.canvas.height * Math.random();
 var hue = 0;
 function line() {
   context.save();
   context.translate(context.canvas.width/2, context.canvas.height/2);
   context.scale(0.9, 0.9);
   context.translate(-context.canvas.width/2, -context.canvas.height/2);
   context.beginPath();
   context.lineWidth = 5 + Math.random() * 10;
   context.moveTo(lastX, lastY);
   lastX = context.canvas.width * Math.random();
   lastY = context.canvas.height * Math.random();
   context.bezierCurveTo(context.canvas.width * Math.random(),
                         context.canvas.height * Math.random(),
                         context.canvas.width * Math.random(),
                         context.canvas.height * Math.random(),
                         lastX, lastY);

   hue = hue + 10 * Math.random();
   context.strokeStyle = 'hsl(' + hue + ', 50%, 50%)';
   context.shadowColor = 'white';
   context.shadowBlur = 10;
   context.stroke();
   context.restore();
 }
 setInterval(line, 50);

 function blank() {
   context.fillStyle = 'rgba(0,0,0,0.1)';
   context.fillRect(0, 0, context.canvas.width, context.canvas.height);
 }
 setInterval(blank, 40);

</script>

Ссылки

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

[BEZIER]
Courbes à poles, P. de Casteljau. INPI, 1959.
[CSS]
Cascading Style Sheets Level 2 Revision 1 (URL: http://www.w3.org/TR/CSS/), B. Bos, T. Çelik, I. Hickson, H. Lie. W3C.
[CSSCOLOR]
CSS Color Module Level 3 (URL: http://www.w3.org/TR/css3-color/), T. Çelik, C. Lilley, L. Baron. 7 June 2011. Рекомендация W3C.
[CSSFONTS]
CSS Fonts Module Level 3 (URL: http://www.w3.org/TR/css3-fonts/), J. Daggett. W3C.
[CSSIMAGES]
CSS Image Values and Replaced Content Module Level 3 (URL: http://www.w3.org/TR/css3-images/), E. Etemad, T. Atkins. W3C.
[CSSOM]
Cascading Style Sheets Object Model (CSSOM) (URL: http://www.w3.org/TR/cssom/), S. Pieters, G. Adams. W3C.
[HTML]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 октября 2014. Рекомендация W3C. URL: http://www.w3.org/TR/html5/
[PORTERDUFF]
Compositing Digital Images (URL: http://keithp.com/~keithp/porterduff/p253-porter.pdf), T. Porter, T. Duff. В Компьютерной графике, том 18, номер 3, стр. 253-259. ACM Press, июль 1984.
[TYPEDARRAY]
Typed Array Specification (URL: https://www.khronos.org/registry/typedarray/specs/latest/), D. Herman, K. Russell. Khronos.
[WEBIDL]
Web IDL (URL: http://www.w3.org/TR/WebIDL-1/), Cameron McCormack, Boris Zbarsky, Yves Lafon, Travis Leithead. W3C.