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 };
 155
 156 interface mixin CanvasTransform {
 157   // transformations (default transform is the identity matrix)
 158   [Throws, LenientFloat]
 159   undefined scale(double x, double y);
 160   [Throws, LenientFloat]
 161   undefined rotate(double angle);
 162   [Throws, LenientFloat]
 163   undefined translate(double x, double y);
 164   [Throws, LenientFloat]
 165   undefined transform(double a, double b, double c, double d, double e, double f);
 166
 167   [NewObject, Throws] DOMMatrix getTransform();
 168   [Throws, LenientFloat]
 169   undefined setTransform(double a, double b, double c, double d, double e, double f);
 170   [Throws]
 171   undefined setTransform(optional DOMMatrix2DInit transform = {});
 172   [Throws]
 173   undefined resetTransform();
 174 };
 175
 176 interface mixin CanvasCompositing {
 177   attribute unrestricted double globalAlpha; // (default 1.0)
 178   [Throws]
 179   attribute DOMString globalCompositeOperation; // (default source-over)
 180 };
 181
 182 interface mixin CanvasImageSmoothing {
 183   // drawing images
 184   attribute boolean imageSmoothingEnabled;
 185 };
 186
 187 interface mixin CanvasFillStrokeStyles {
 188   // colors and styles (see also the CanvasPathDrawingStyles interface)
 189   attribute (UTF8String or CanvasGradient or CanvasPattern) strokeStyle; // (default black)
 190   attribute (UTF8String or CanvasGradient or CanvasPattern) fillStyle; // (default black)
 191   [NewObject]
 192   CanvasGradient createLinearGradient(double x0, double y0, double x1, double y1);
 193   [NewObject, Throws]
 194   CanvasGradient createRadialGradient(double x0, double y0, double r0, double x1, double y1, double r1);
 195   [NewObject]
 196   CanvasGradient createConicGradient(double angle, double cx, double cy);
 197   [NewObject, Throws]
 198   CanvasPattern? createPattern(CanvasImageSource image, [LegacyNullToEmptyString] DOMString repetition);
 199 };
 200
 201 interface mixin CanvasShadowStyles {
 202   [LenientFloat]
 203   attribute double shadowOffsetX; // (default 0)
 204   [LenientFloat]
 205   attribute double shadowOffsetY; // (default 0)
 206   [LenientFloat]
 207   attribute double shadowBlur; // (default 0)
 208   attribute UTF8String shadowColor; // (default transparent black)
 209 };
 210
 211 interface mixin CanvasFilters {
 212   [SetterThrows]
 213   attribute UTF8String filter; // (default empty string = no filter)
 214 };
 215
 216 interface mixin CanvasRect {
 217   [LenientFloat]
 218   undefined clearRect(double x, double y, double w, double h);
 219   [LenientFloat]
 220   undefined fillRect(double x, double y, double w, double h);
 221   [LenientFloat]
 222   undefined strokeRect(double x, double y, double w, double h);
 223 };
 224
 225 interface mixin CanvasDrawPath {
 226   // path API (see also CanvasPathMethods)
 227   undefined beginPath();
 228   undefined fill(optional CanvasWindingRule winding = "nonzero");
 229   undefined fill(Path2D path, optional CanvasWindingRule winding = "nonzero");
 230   undefined stroke();
 231   undefined stroke(Path2D path);
 232   undefined clip(optional CanvasWindingRule winding = "nonzero");
 233   undefined clip(Path2D path, optional CanvasWindingRule winding = "nonzero");
 234 // NOT IMPLEMENTED  undefined resetClip();
 235   [NeedsSubjectPrincipal]
 236   boolean isPointInPath(unrestricted double x, unrestricted double y, optional CanvasWindingRule winding = "nonzero");
 237   [NeedsSubjectPrincipal] // Only required because overloads can't have different extended attributes.
 238   boolean isPointInPath(Path2D path, unrestricted double x, unrestricted double y, optional CanvasWindingRule winding = "nonzero");
 239   [NeedsSubjectPrincipal]
 240   boolean isPointInStroke(double x, double y);
 241   [NeedsSubjectPrincipal] // Only required because overloads can't have different extended attributes.
 242   boolean isPointInStroke(Path2D path, unrestricted double x, unrestricted double y);
 243 };
 244
 245 interface mixin CanvasUserInterface {
 246   [Throws] undefined drawFocusIfNeeded(Element element);
 247 // NOT IMPLEMENTED  undefined scrollPathIntoView();
 248 // NOT IMPLEMENTED  undefined scrollPathIntoView(Path path);
 249 };
 250
 251 interface mixin CanvasText {
 252   // text (see also the CanvasPathDrawingStyles interface)
 253   [Throws, LenientFloat]
 254   undefined fillText(DOMString text, double x, double y, optional double maxWidth);
 255   [Throws, LenientFloat]
 256   undefined strokeText(DOMString text, double x, double y, optional double maxWidth);
 257   [NewObject, Throws]
 258   TextMetrics measureText(DOMString text);
 259 };
 260
 261 interface mixin CanvasDrawImage {
 262   [Throws, LenientFloat]
 263   undefined drawImage(CanvasImageSource image, double dx, double dy);
 264   [Throws, LenientFloat]
 265   undefined drawImage(CanvasImageSource image, double dx, double dy, double dw, double dh);
 266   [Throws, LenientFloat]
 267   undefined drawImage(CanvasImageSource image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);
 268 };
 269
 270 // See https://github.com/whatwg/html/issues/6262 for [EnforceRange] usage.
 271 interface mixin CanvasImageData {
 272   // pixel manipulation
 273   [NewObject, Throws]
 274   ImageData createImageData([EnforceRange] long sw, [EnforceRange] long sh);
 275   [NewObject, Throws]
 276   ImageData createImageData(ImageData imagedata);
 277   [NewObject, Throws, NeedsSubjectPrincipal]
 278   ImageData getImageData([EnforceRange] long sx, [EnforceRange] long sy, [EnforceRange] long sw, [EnforceRange] long sh);
 279   [Throws]
 280   undefined putImageData(ImageData imagedata, [EnforceRange] long dx, [EnforceRange] long dy);
 281   [Throws]
 282   undefined putImageData(ImageData imagedata, [EnforceRange] long dx, [EnforceRange] long dy, [EnforceRange] long dirtyX, [EnforceRange] long dirtyY, [EnforceRange] long dirtyWidth, [EnforceRange] long dirtyHeight);
 283 };
 284
 285 interface mixin CanvasPathDrawingStyles {
 286   // line caps/joins
 287   [LenientFloat]
 288   attribute double lineWidth; // (default 1)
 289   attribute CanvasLineCap lineCap; // (default "butt")
 290   attribute CanvasLineJoin lineJoin; // (default "miter")
 291   [LenientFloat]
 292   attribute double miterLimit; // (default 10)
 293
 294   // dashed lines
 295   [LenientFloat, Throws] undefined setLineDash(sequence<double> segments); // default empty
 296   sequence<double> getLineDash();
 297   [LenientFloat] attribute double lineDashOffset;
 298 };
 299
 300 interface mixin CanvasTextDrawingStyles {
 301   // text
 302   [SetterThrows]
 303   attribute UTF8String font; // (default 10px sans-serif)
 304   attribute CanvasTextAlign textAlign; // (default: "start")
 305   attribute CanvasTextBaseline textBaseline; // (default: "alphabetic")
 306   attribute CanvasDirection direction; // (default: "inherit")
 307   attribute UTF8String letterSpacing; // default: "0px"
 308   attribute CanvasFontKerning fontKerning; // (default: "auto")
 309   attribute CanvasFontStretch fontStretch; // (default: "normal")
 310   attribute CanvasFontVariantCaps fontVariantCaps; // (default: "normal")
 311   attribute CanvasTextRendering textRendering; // (default: "auto")
 312   attribute UTF8String wordSpacing; // default: "0px"
 313 };
 314
 315 interface mixin CanvasPathMethods {
 316   // shared path API methods
 317   undefined closePath();
 318   [LenientFloat]
 319   undefined moveTo(double x, double y);
 320   [LenientFloat]
 321   undefined lineTo(double x, double y);
 322   [LenientFloat]
 323   undefined quadraticCurveTo(double cpx, double cpy, double x, double y);
 324
 325   [LenientFloat]
 326   undefined bezierCurveTo(double cp1x, double cp1y, double cp2x, double cp2y, double x, double y);
 327
 328   [Throws, LenientFloat]
 329   undefined arcTo(double x1, double y1, double x2, double y2, double radius);
 330 // NOT IMPLEMENTED  [LenientFloat] undefined arcTo(double x1, double y1, double x2, double y2, double radiusX, double radiusY, double rotation);
 331
 332   [LenientFloat]
 333   undefined rect(double x, double y, double w, double h);
 334
 335   [Throws]
 336   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);
 337
 338   [Throws, LenientFloat]
 339   undefined arc(double x, double y, double radius, double startAngle, double endAngle, optional boolean anticlockwise = false);
 340
 341   [Throws, LenientFloat]
 342   undefined ellipse(double x, double y, double radiusX, double radiusY, double rotation, double startAngle, double endAngle, optional boolean anticlockwise = false);
 343 };
 344
 345 [Exposed=(Window,Worker),
 346  Func="mozilla::dom::OffscreenCanvas::PrefEnabledOnWorkerThread"]
 347 interface CanvasGradient {
 348   // opaque object
 349   [Throws]
 350   // addColorStop should take a double
 351   undefined addColorStop(float offset, UTF8String color);
 352 };
 353
 354 [Exposed=(Window,Worker),
 355  Func="mozilla::dom::OffscreenCanvas::PrefEnabledOnWorkerThread"]
 356 interface CanvasPattern {
 357   // opaque object
 358   // [Throws, LenientFloat] - could not do this overload because of bug 1020975
 359   // undefined setTransform(double a, double b, double c, double d, double e, double f);
 360
 361   [Throws]
 362   undefined setTransform(optional DOMMatrix2DInit matrix = {});
 363 };
 364
 365 [Exposed=(Window,Worker)]
 366 interface TextMetrics {
 367
 368   // x-direction
 369   readonly attribute double width; // advance width
 370
 371   // [experimental] actualBoundingBox* attributes
 372   [Pref="dom.textMetrics.actualBoundingBox.enabled"]
 373   readonly attribute double actualBoundingBoxLeft;
 374   [Pref="dom.textMetrics.actualBoundingBox.enabled"]
 375   readonly attribute double actualBoundingBoxRight;
 376
 377   // y-direction
 378   // [experimental] fontBoundingBox* attributes
 379   [Pref="dom.textMetrics.fontBoundingBox.enabled"]
 380   readonly attribute double fontBoundingBoxAscent;
 381   [Pref="dom.textMetrics.fontBoundingBox.enabled"]
 382   readonly attribute double fontBoundingBoxDescent;
 383
 384   // [experimental] actualBoundingBox* attributes
 385   [Pref="dom.textMetrics.actualBoundingBox.enabled"]
 386   readonly attribute double actualBoundingBoxAscent;
 387   [Pref="dom.textMetrics.actualBoundingBox.enabled"]
 388   readonly attribute double actualBoundingBoxDescent;
 389
 390   // [experimental] emHeight* attributes
 391   [Pref="dom.textMetrics.emHeight.enabled"]
 392   readonly attribute double emHeightAscent;
 393   [Pref="dom.textMetrics.emHeight.enabled"]
 394   readonly attribute double emHeightDescent;
 395
 396   // [experimental] *Baseline attributes
 397   [Pref="dom.textMetrics.baselines.enabled"]
 398   readonly attribute double hangingBaseline;
 399   [Pref="dom.textMetrics.baselines.enabled"]
 400   readonly attribute double alphabeticBaseline;
 401   [Pref="dom.textMetrics.baselines.enabled"]
 402   readonly attribute double ideographicBaseline;
 403 };
 404
 405 [Exposed=(Window,Worker)]
 406 interface Path2D
 407 {
 408   constructor();
 409   constructor(Path2D other);
 410   constructor(DOMString pathString);
 411
 412   [Throws] undefined addPath(Path2D path, optional DOMMatrix2DInit transform = {});
 413 };
 414 Path2D includes CanvasPathMethods;