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