dom/webidl/CanvasRenderingContext2D.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * The origin of this IDL file is
   7  * http://www.whatwg.org/specs/web-apps/current-work/
   8  *
   9  * © Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and
  10  * Opera Software ASA. You are granted a license to use, reproduce
  11  * and create derivative works of this document.
  12  */
  13
  14 enum CanvasWindingRule { "nonzero", "evenodd" };
  15
  16 enum CanvasLineCap { "butt", "round", "square" };
  17 enum CanvasLineJoin { "round", "bevel", "miter" };
  18 enum CanvasTextAlign { "start", "end", "left", "right", "center" };
  19 enum CanvasTextBaseline { "top", "hanging", "middle", "alphabetic", "ideographic", "bottom" };
  20 enum CanvasDirection { "ltr", "rtl", "inherit" };
  21 enum CanvasFontKerning { "auto", "normal", "none" };
  22 enum CanvasFontStretch { "ultra-condensed", "extra-condensed", "condensed", "semi-condensed", "normal", "semi-expanded", "expanded", "extra-expanded", "ultra-expanded" };
  23 enum CanvasFontVariantCaps { "normal", "small-caps", "all-small-caps", "petite-caps", "all-petite-caps", "unicase", "titling-caps" };
  24 enum CanvasTextRendering { "auto", "optimizeSpeed", "optimizeLegibility", "geometricPrecision" };
  25
  26 [GenerateInit]
  27 dictionary CanvasRenderingContext2DSettings {
  28   // signal if the canvas contains an alpha channel
  29   boolean alpha = true;
  30
  31   boolean desynchronized = false;
  32
  33   PredefinedColorSpace colorSpace = "srgb";
  34
  35   // whether or not we're planning to do a lot of readback operations
  36   boolean willReadFrequently = false;
  37 };
  38
  39 dictionary HitRegionOptions {
  40   Path2D? path = null;
  41   DOMString id = "";
  42   Element? control = null;
  43 };
  44
  45 typedef (HTMLImageElement or
  46          SVGImageElement) HTMLOrSVGImageElement;
  47
  48 typedef (HTMLOrSVGImageElement or
  49          HTMLCanvasElement or
  50          HTMLVideoElement or
  51          OffscreenCanvas or
  52          ImageBitmap or
  53          VideoFrame) CanvasImageSource;
  54
  55 [Exposed=Window]
  56 interface CanvasRenderingContext2D {
  57
  58   // back-reference to the canvas.  Might be null if we're not
  59   // associated with a canvas.
  60   readonly attribute HTMLCanvasElement? canvas;
  61
  62   CanvasRenderingContext2DSettings getContextAttributes();
  63
  64   // Show the caret if appropriate when drawing
  65   [Func="CanvasUtils::HasDrawWindowPrivilege"]
  66   const unsigned long DRAWWINDOW_DRAW_CARET   = 0x01;
  67   // Don't flush pending layout notifications that could otherwise
  68   // be batched up
  69   [Func="CanvasUtils::HasDrawWindowPrivilege"]
  70   const unsigned long DRAWWINDOW_DO_NOT_FLUSH = 0x02;
  71   // Draw scrollbars and scroll the viewport if they are present
  72   [Func="CanvasUtils::HasDrawWindowPrivilege"]
  73   const unsigned long DRAWWINDOW_DRAW_VIEW    = 0x04;
  74   // Use the widget layer manager if available. This means hardware
  75   // acceleration may be used, but it might actually be slower or
  76   // lower quality than normal. It will however more accurately reflect
  77   // the pixels rendered to the screen.
  78   [Func="CanvasUtils::HasDrawWindowPrivilege"]
  79   const unsigned long DRAWWINDOW_USE_WIDGET_LAYERS = 0x08;
  80   // Don't synchronously decode images - draw what we have
  81   [Func="CanvasUtils::HasDrawWindowPrivilege"]
  82   const unsigned long DRAWWINDOW_ASYNC_DECODE_IMAGES = 0x10;
  83
  84   /**
  85    * Renders a region of a window into the canvas.  The contents of
  86    * the window's viewport are rendered, ignoring viewport clipping
  87    * and scrolling.
  88    *
  89    * @param x
  90    * @param y
  91    * @param w
  92    * @param h specify the area of the window to render, in CSS
  93    * pixels.
  94    *
  95    * @param backgroundColor the canvas is filled with this color
  96    * before we render the window into it. This color may be
  97    * transparent/translucent. It is given as a CSS color string
  98    * (e.g., rgb() or rgba()).
  99    *
 100    * @param flags Used to better control the drawWindow call.
 101    * Flags can be ORed together.
 102    *
 103    * Of course, the rendering obeys the current scale, transform and
 104    * globalAlpha values.
 105    *
 106    * Hints:
 107    * -- If 'rgba(0,0,0,0)' is used for the background color, the
 108    * drawing will be transparent wherever the window is transparent.
 109    * -- Top-level browsed documents are usually not transparent
 110    * because the user's background-color preference is applied,
 111    * but IFRAMEs are transparent if the page doesn't set a background.
 112    * -- If an opaque color is used for the background color, rendering
 113    * will be faster because we won't have to compute the window's
 114    * transparency.
 115    *
 116    * This API cannot currently be used by Web content. It is chrome
 117    * and Web Extensions (with a permission) only.
 118    */
 119   [Throws, NeedsSubjectPrincipal, Func="CanvasUtils::HasDrawWindowPrivilege"]
 120   undefined drawWindow(Window window, double x, double y, double w, double h,
 121                        UTF8String bgColor, optional unsigned long flags = 0);
 122
 123   /**
 124    * This causes a context that is currently using a hardware-accelerated
 125    * backend to fallback to a software one. All state should be preserved.
 126    */
 127   [ChromeOnly]
 128   undefined demote();
 129 };
 130
 131 CanvasRenderingContext2D includes CanvasState;
 132 CanvasRenderingContext2D includes CanvasTransform;
 133 CanvasRenderingContext2D includes CanvasCompositing;
 134 CanvasRenderingContext2D includes CanvasImageSmoothing;
 135 CanvasRenderingContext2D includes CanvasFillStrokeStyles;
 136 CanvasRenderingContext2D includes CanvasShadowStyles;
 137 CanvasRenderingContext2D includes CanvasFilters;
 138 CanvasRenderingContext2D includes CanvasRect;
 139 CanvasRenderingContext2D includes CanvasDrawPath;
 140 CanvasRenderingContext2D includes CanvasUserInterface;
 141 CanvasRenderingContext2D includes CanvasText;
 142 CanvasRenderingContext2D includes CanvasDrawImage;
 143 CanvasRenderingContext2D includes CanvasImageData;
 144 CanvasRenderingContext2D includes CanvasPathDrawingStyles;
 145 CanvasRenderingContext2D includes CanvasTextDrawingStyles;
 146 CanvasRenderingContext2D includes CanvasPathMethods;
 147
 148
 149 interface mixin CanvasState {
 150   // state
 151   undefined save(); // push state on state stack
 152   undefined restore(); // pop state stack and restore state
 153   undefined reset(); // reset the rendering context to its default state
 154   boolean isContextLost(); // return whether context is lost
 155 };
 156
 157 interface mixin CanvasTransform {
 158   // transformations (default transform is the identity matrix)
 159   [Throws, LenientFloat]
 160   undefined scale(double x, double y);
 161   [Throws, LenientFloat]
 162   undefined rotate(double angle);
 163   [Throws, LenientFloat]
 164   undefined translate(double x, double y);
 165   [Throws, LenientFloat]
 166   undefined transform(double a, double b, double c, double d, double e, double f);
 167
 168   [NewObject, Throws] DOMMatrix getTransform();
 169   [Throws, LenientFloat]
 170   undefined setTransform(double a, double b, double c, double d, double e, double f);
 171   [Throws]
 172   undefined setTransform(optional DOMMatrix2DInit transform = {});
 173   [Throws]
 174   undefined resetTransform();
 175 };
 176
 177 interface mixin CanvasCompositing {
 178   attribute unrestricted double globalAlpha; // (default 1.0)
 179   [Throws]
 180   attribute DOMString globalCompositeOperation; // (default source-over)
 181 };
 182
 183 interface mixin CanvasImageSmoothing {
 184   // drawing images
 185   attribute boolean imageSmoothingEnabled;
 186 };
 187
 188 interface mixin CanvasFillStrokeStyles {
 189   // colors and styles (see also the CanvasPathDrawingStyles interface)
 190   attribute (UTF8String or CanvasGradient or CanvasPattern) strokeStyle; // (default black)
 191   attribute (UTF8String or CanvasGradient or CanvasPattern) fillStyle; // (default black)
 192   [NewObject]
 193   CanvasGradient createLinearGradient(double x0, double y0, double x1, double y1);
 194   [NewObject, Throws]
 195   CanvasGradient createRadialGradient(double x0, double y0, double r0, double x1, double y1, double r1);
 196   [NewObject]
 197   CanvasGradient createConicGradient(double angle, double cx, double cy);
 198   [NewObject, Throws]
 199   CanvasPattern? createPattern(CanvasImageSource image, [LegacyNullToEmptyString] DOMString repetition);
 200 };
 201
 202 interface mixin CanvasShadowStyles {
 203   [LenientFloat]
 204   attribute double shadowOffsetX; // (default 0)
 205   [LenientFloat]
 206   attribute double shadowOffsetY; // (default 0)
 207   [LenientFloat]
 208   attribute double shadowBlur; // (default 0)
 209   attribute UTF8String shadowColor; // (default transparent black)
 210 };
 211
 212 interface mixin CanvasFilters {
 213   [SetterThrows]
 214   attribute UTF8String filter; // (default empty string = no filter)
 215 };
 216
 217 interface mixin CanvasRect {
 218   [LenientFloat]
 219   undefined clearRect(double x, double y, double w, double h);
 220   [LenientFloat]
 221   undefined fillRect(double x, double y, double w, double h);
 222   [LenientFloat]
 223   undefined strokeRect(double x, double y, double w, double h);
 224 };
 225
 226 interface mixin CanvasDrawPath {
 227   // path API (see also CanvasPathMethods)
 228   undefined beginPath();
 229   undefined fill(optional CanvasWindingRule winding = "nonzero");
 230   undefined fill(Path2D path, optional CanvasWindingRule winding = "nonzero");
 231   undefined stroke();
 232   undefined stroke(Path2D path);
 233   undefined clip(optional CanvasWindingRule winding = "nonzero");
 234   undefined clip(Path2D path, optional CanvasWindingRule winding = "nonzero");
 235 // NOT IMPLEMENTED  undefined resetClip();
 236   [NeedsSubjectPrincipal]
 237   boolean isPointInPath(unrestricted double x, unrestricted double y, optional CanvasWindingRule winding = "nonzero");
 238   [NeedsSubjectPrincipal] // Only required because overloads can't have different extended attributes.
 239   boolean isPointInPath(Path2D path, unrestricted double x, unrestricted double y, optional CanvasWindingRule winding = "nonzero");
 240   [NeedsSubjectPrincipal]
 241   boolean isPointInStroke(double x, double y);
 242   [NeedsSubjectPrincipal] // Only required because overloads can't have different extended attributes.
 243   boolean isPointInStroke(Path2D path, unrestricted double x, unrestricted double y);
 244 };
 245
 246 interface mixin CanvasUserInterface {
 247   [Throws] undefined drawFocusIfNeeded(Element element);
 248 // NOT IMPLEMENTED  undefined scrollPathIntoView();
 249 // NOT IMPLEMENTED  undefined scrollPathIntoView(Path path);
 250 };
 251
 252 interface mixin CanvasText {
 253   // text (see also the CanvasPathDrawingStyles interface)
 254   [Throws, LenientFloat]
 255   undefined fillText(DOMString text, double x, double y, optional double maxWidth);
 256   [Throws, LenientFloat]
 257   undefined strokeText(DOMString text, double x, double y, optional double maxWidth);
 258   [NewObject, Throws]
 259   TextMetrics measureText(DOMString text);
 260 };
 261
 262 interface mixin CanvasDrawImage {
 263   [Throws, LenientFloat]
 264   undefined drawImage(CanvasImageSource image, double dx, double dy);
 265   [Throws, LenientFloat]
 266   undefined drawImage(CanvasImageSource image, double dx, double dy, double dw, double dh);
 267   [Throws, LenientFloat]
 268   undefined drawImage(CanvasImageSource image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);
 269 };
 270
 271 // See https://github.com/whatwg/html/issues/6262 for [EnforceRange] usage.
 272 interface mixin CanvasImageData {
 273   // pixel manipulation
 274   [NewObject, Throws]
 275   ImageData createImageData([EnforceRange] long sw, [EnforceRange] long sh);
 276   [NewObject, Throws]
 277   ImageData createImageData(ImageData imagedata);
 278   [NewObject, Throws, NeedsSubjectPrincipal]
 279   ImageData getImageData([EnforceRange] long sx, [EnforceRange] long sy, [EnforceRange] long sw, [EnforceRange] long sh);
 280   [Throws]
 281   undefined putImageData(ImageData imagedata, [EnforceRange] long dx, [EnforceRange] long dy);
 282   [Throws]
 283   undefined putImageData(ImageData imagedata, [EnforceRange] long dx, [EnforceRange] long dy, [EnforceRange] long dirtyX, [EnforceRange] long dirtyY, [EnforceRange] long dirtyWidth, [EnforceRange] long dirtyHeight);
 284 };
 285
 286 interface mixin CanvasPathDrawingStyles {
 287   // line caps/joins
 288   [LenientFloat]
 289   attribute double lineWidth; // (default 1)
 290   attribute CanvasLineCap lineCap; // (default "butt")
 291   attribute CanvasLineJoin lineJoin; // (default "miter")
 292   [LenientFloat]
 293   attribute double miterLimit; // (default 10)
 294
 295   // dashed lines
 296   [LenientFloat, Throws] undefined setLineDash(sequence<double> segments); // default empty
 297   sequence<double> getLineDash();
 298   [LenientFloat] attribute double lineDashOffset;
 299 };
 300
 301 interface mixin CanvasTextDrawingStyles {
 302   // text
 303   [SetterThrows]
 304   attribute UTF8String font; // (default 10px sans-serif)
 305   attribute CanvasTextAlign textAlign; // (default: "start")
 306   attribute CanvasTextBaseline textBaseline; // (default: "alphabetic")
 307   attribute CanvasDirection direction; // (default: "inherit")
 308   attribute UTF8String letterSpacing; // default: "0px"
 309   attribute CanvasFontKerning fontKerning; // (default: "auto")
 310   attribute CanvasFontStretch fontStretch; // (default: "normal")
 311   attribute CanvasFontVariantCaps fontVariantCaps; // (default: "normal")
 312   attribute CanvasTextRendering textRendering; // (default: "auto")
 313   attribute UTF8String wordSpacing; // default: "0px"
 314 };
 315
 316 interface mixin CanvasPathMethods {
 317   // shared path API methods
 318   undefined closePath();
 319   [LenientFloat]
 320   undefined moveTo(double x, double y);
 321   [LenientFloat]
 322   undefined lineTo(double x, double y);
 323   [LenientFloat]
 324   undefined quadraticCurveTo(double cpx, double cpy, double x, double y);
 325
 326   [LenientFloat]
 327   undefined bezierCurveTo(double cp1x, double cp1y, double cp2x, double cp2y, double x, double y);
 328
 329   [Throws, LenientFloat]
 330   undefined arcTo(double x1, double y1, double x2, double y2, double radius);
 331 // NOT IMPLEMENTED  [LenientFloat] undefined arcTo(double x1, double y1, double x2, double y2, double radiusX, double radiusY, double rotation);
 332
 333   [LenientFloat]
 334   undefined rect(double x, double y, double w, double h);
 335
 336   [Throws]
 337   undefined roundRect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h, optional (unrestricted double or DOMPointInit or sequence<(unrestricted double or DOMPointInit)>) radii = 0);
 338
 339   [Throws, LenientFloat]
 340   undefined arc(double x, double y, double radius, double startAngle, double endAngle, optional boolean anticlockwise = false);
 341
 342   [Throws, LenientFloat]
 343   undefined ellipse(double x, double y, double radiusX, double radiusY, double rotation, double startAngle, double endAngle, optional boolean anticlockwise = false);
 344 };
 345
 346 [Exposed=(Window,Worker),
 347  Func="mozilla::dom::OffscreenCanvas::PrefEnabledOnWorkerThread"]
 348 interface CanvasGradient {
 349   // opaque object
 350   [Throws]
 351   // addColorStop should take a double
 352   undefined addColorStop(float offset, UTF8String color);
 353 };
 354
 355 [Exposed=(Window,Worker),
 356  Func="mozilla::dom::OffscreenCanvas::PrefEnabledOnWorkerThread"]
 357 interface CanvasPattern {
 358   // opaque object
 359   // [Throws, LenientFloat] - could not do this overload because of bug 1020975
 360   // undefined setTransform(double a, double b, double c, double d, double e, double f);
 361
 362   [Throws]
 363   undefined setTransform(optional DOMMatrix2DInit matrix = {});
 364 };
 365
 366 [Exposed=(Window,Worker)]
 367 interface TextMetrics {
 368
 369   // x-direction
 370   readonly attribute double width; // advance width
 371
 372   // [experimental] actualBoundingBox* attributes
 373   [Pref="dom.textMetrics.actualBoundingBox.enabled"]
 374   readonly attribute double actualBoundingBoxLeft;
 375   [Pref="dom.textMetrics.actualBoundingBox.enabled"]
 376   readonly attribute double actualBoundingBoxRight;
 377
 378   // y-direction
 379   // [experimental] fontBoundingBox* attributes
 380   [Pref="dom.textMetrics.fontBoundingBox.enabled"]
 381   readonly attribute double fontBoundingBoxAscent;
 382   [Pref="dom.textMetrics.fontBoundingBox.enabled"]
 383   readonly attribute double fontBoundingBoxDescent;
 384
 385   // [experimental] actualBoundingBox* attributes
 386   [Pref="dom.textMetrics.actualBoundingBox.enabled"]
 387   readonly attribute double actualBoundingBoxAscent;
 388   [Pref="dom.textMetrics.actualBoundingBox.enabled"]
 389   readonly attribute double actualBoundingBoxDescent;
 390
 391   // [experimental] emHeight* attributes
 392   [Pref="dom.textMetrics.emHeight.enabled"]
 393   readonly attribute double emHeightAscent;
 394   [Pref="dom.textMetrics.emHeight.enabled"]
 395   readonly attribute double emHeightDescent;
 396
 397   // [experimental] *Baseline attributes
 398   [Pref="dom.textMetrics.baselines.enabled"]
 399   readonly attribute double hangingBaseline;
 400   [Pref="dom.textMetrics.baselines.enabled"]
 401   readonly attribute double alphabeticBaseline;
 402   [Pref="dom.textMetrics.baselines.enabled"]
 403   readonly attribute double ideographicBaseline;
 404 };
 405
 406 [Exposed=(Window,Worker)]
 407 interface Path2D
 408 {
 409   constructor();
 410   constructor(Path2D other);
 411   constructor(UTF8String pathString);
 412
 413   [Throws] undefined addPath(Path2D path, optional DOMMatrix2DInit transform = {});
 414 };
 415 Path2D includes CanvasPathMethods;