Home | History | Annotate | Download | only in canvas 
      1 /*
      2  * Copyright (C) 2006 Apple Computer, Inc.  All rights reserved.
      3  *
      4  * Redistribution and use in source and binary forms, with or without
      5  * modification, are permitted provided that the following conditions
      6  * are met:
      7  * 1. Redistributions of source code must retain the above copyright
      8  *    notice, this list of conditions and the following disclaimer.
      9  * 2. Redistributions in binary form must reproduce the above copyright
     10  *    notice, this list of conditions and the following disclaimer in the
     11  *    documentation and/or other materials provided with the distribution.
     12  *
     13  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
     14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
     17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
     21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     24  */
     25 
     26 // http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#canvasrenderingcontext2d
     27 
     28 // FIXME: float => double throughout
     29 // FIXME: Use union type in drawImage and createPattern once supported:
     30 // http://crbug.com/372891
     31 typedef (HTMLImageElement or
     32          HTMLVideoElement or
     33          HTMLCanvasElement // or
     34          // CanvasRenderingContext2D or
     35          // ImageBitmap
     36          ) CanvasImageSource;
     37 
     38 enum CanvasFillRule { "nonzero", "evenodd" };
     39 
     40 [
     41     TypeChecking=(Interface,Unrestricted),
     42     WillBeGarbageCollected,
     43 ] interface CanvasRenderingContext2D {
     44     // back-reference to the canvas
     45     readonly attribute HTMLCanvasElement canvas;
     46 
     47     // state
     48     void save(); // push state on state stack
     49     void restore(); // pop state stack and restore state
     50 
     51     // transformations (default transform is the identity matrix)
     52     [RuntimeEnabled=ExperimentalCanvasFeatures] attribute SVGMatrix currentTransform;
     53     void scale(unrestricted float x, unrestricted float y);
     54     void rotate(unrestricted float angle);
     55     void translate(unrestricted float x, unrestricted float y);
     56     void transform(unrestricted float a, unrestricted float b, unrestricted float c, unrestricted float d, unrestricted float e, unrestricted float f);
     57     void setTransform(unrestricted float a, unrestricted float b, unrestricted float c, unrestricted float d, unrestricted float e, unrestricted float f);
     58     void resetTransform();
     59 
     60     // compositing
     61     attribute unrestricted float globalAlpha; // (default 1.0)
     62     [TreatNullAs=NullString] attribute DOMString globalCompositeOperation; // (default source-over)
     63 
     64     // image smoothing
     65     [ImplementedAs=imageSmoothingEnabled, MeasureAs=PrefixedImageSmoothingEnabled] attribute boolean webkitImageSmoothingEnabled;
     66     [MeasureAs=UnprefixedImageSmoothingEnabled] attribute boolean imageSmoothingEnabled;
     67 
     68     // colors and styles (see also the CanvasDrawingStyles interface)
     69     // FIXME: Use union types when supported: http://crbug.com/372891
     70     [Custom] attribute object strokeStyle; // (default black)
     71     [Custom] attribute object fillStyle; // (default black)
     72     CanvasGradient createLinearGradient(float x0, float y0, float x1, float y1);
     73     [RaisesException] CanvasGradient createRadialGradient(float x0, float y0, float r0, float x1, float y1, float r1);
     74     [RaisesException] CanvasPattern createPattern(HTMLCanvasElement canvas, DOMString? repetitionType);
     75     [RaisesException] CanvasPattern createPattern(HTMLImageElement image, DOMString? repetitionType);
     76     [RaisesException] CanvasPattern createPattern(HTMLVideoElement image, DOMString? repetitionType);
     77 
     78     // shadows
     79     attribute unrestricted float shadowOffsetX;
     80     attribute unrestricted float shadowOffsetY;
     81     attribute unrestricted float shadowBlur;
     82     [TreatNullAs=NullString] attribute DOMString shadowColor;
     83 
     84     // rects
     85     void clearRect(unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height);
     86     void fillRect(unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height);
     87     void strokeRect(unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height);
     88 
     89     // path API (see also CanvasPathMethods)
     90     void beginPath();
     91     void fill(optional CanvasFillRule winding);
     92     void fill(Path2D path, optional CanvasFillRule winding);
     93     void stroke();
     94     void stroke(Path2D path);
     95     // Focus rings
     96     void drawFocusIfNeeded(Element element);
     97     void drawFocusIfNeeded(Path2D path, Element element);
     98 
     99     [RuntimeEnabled=ExperimentalCanvasFeatures] void scrollPathIntoView(optional Path2D path);
    100     void clip(optional CanvasFillRule winding);
    101     void clip(Path2D path, optional CanvasFillRule winding);
    102     boolean isPointInPath(unrestricted float x, unrestricted float y, optional CanvasFillRule winding);
    103     boolean isPointInPath(Path2D path, unrestricted float x, unrestricted float y, optional CanvasFillRule winding);
    104     boolean isPointInStroke(unrestricted float x, unrestricted float y);
    105     boolean isPointInStroke(Path2D path, unrestricted float x, unrestricted float y);
    106 
    107     // text (see also the CanvasDrawingStyles interface)
    108     void fillText(DOMString text, unrestricted float x, unrestricted float y, optional unrestricted float maxWidth);
    109     void strokeText(DOMString text, unrestricted float x, unrestricted float y, optional unrestricted float maxWidth);
    110     TextMetrics measureText(DOMString text);
    111 
    112     // drawing images
    113     [RaisesException] void drawImage(HTMLImageElement image, unrestricted float x, unrestricted float y);
    114     [RaisesException] void drawImage(HTMLImageElement image, unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height);
    115     [RaisesException] void drawImage(HTMLImageElement image, unrestricted float sx, unrestricted float sy, unrestricted float sw, unrestricted float sh, unrestricted float dx, unrestricted float dy, unrestricted float dw, unrestricted float dh);
    116     [RaisesException] void drawImage(HTMLCanvasElement canvas, unrestricted float x, unrestricted float y);
    117     [RaisesException] void drawImage(HTMLCanvasElement canvas, unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height);
    118     [RaisesException] void drawImage(HTMLCanvasElement canvas, unrestricted float sx, unrestricted float sy, unrestricted float sw, unrestricted float sh, unrestricted float dx, unrestricted float dy, unrestricted float dw, unrestricted float dh);
    119     [RaisesException] void drawImage(HTMLVideoElement video, unrestricted float x, unrestricted float y);
    120     [RaisesException] void drawImage(HTMLVideoElement video, unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height);
    121     [RaisesException] void drawImage(HTMLVideoElement video, unrestricted float sx, unrestricted float sy, unrestricted float sw, unrestricted float sh, unrestricted float dx, unrestricted float dy, unrestricted float dw, unrestricted float dh);
    122     [RuntimeEnabled=ExperimentalCanvasFeatures, RaisesException] void drawImage(ImageBitmap imageBitmap, unrestricted float x, unrestricted float y);
    123     [RuntimeEnabled=ExperimentalCanvasFeatures, RaisesException] void drawImage(ImageBitmap imageBitmap, unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height);
    124     [RuntimeEnabled=ExperimentalCanvasFeatures, RaisesException] void drawImage(ImageBitmap imageBitmap, unrestricted float sx, unrestricted float sy, unrestricted float sw, unrestricted float sh, unrestricted float dx, unrestricted float dy, unrestricted float dw, unrestricted float dh);
    125 
    126     // hit regions
    127     [RuntimeEnabled=ExperimentalCanvasFeatures, RaisesException] void addHitRegion(optional HitRegionOptions options);
    128     [RuntimeEnabled=ExperimentalCanvasFeatures] void removeHitRegion(DOMString id);
    129     [RuntimeEnabled=ExperimentalCanvasFeatures] void clearHitRegions();
    130 
    131     // pixel manipulation
    132     ImageData createImageData(ImageData imagedata);
    133     [RaisesException] ImageData createImageData(float sw, float sh);
    134     [RaisesException] ImageData getImageData(float sx, float sy, float sw, float sh);
    135     void putImageData(ImageData imagedata, float dx, float dy);
    136     void putImageData(ImageData imagedata, float dx, float dy, float dirtyX, float dirtyY, float dirtyWidth, float dirtyHeight);
    137 
    138     // Context state
    139     // Should be merged with WebGL counterpart in CanvasRenderingContext, once no-longer experimental
    140     [RuntimeEnabled=ExperimentalCanvasFeatures] boolean isContextLost();
    141 
    142     Canvas2DContextAttributes getContextAttributes();
    143 
    144     // FIXME: factor out to CanvasDrawingStyles
    145     // line caps/joins
    146     attribute unrestricted float lineWidth; // (default 1)
    147     [TreatNullAs=NullString] attribute DOMString lineCap; // "butt", "round", "square" (default "butt")
    148     [TreatNullAs=NullString] attribute DOMString lineJoin; // "round", "bevel", "miter" (default "miter")
    149     attribute unrestricted float miterLimit; // (default 10)
    150 
    151     // dashed lines
    152     void setLineDash(sequence<unrestricted float> dash);
    153     sequence<unrestricted float> getLineDash();
    154     attribute unrestricted float lineDashOffset;
    155 
    156     // text
    157     attribute DOMString font; // (default 10px sans-serif)
    158     attribute DOMString textAlign; // "start", "end", "left", "right", "center" (default: "start")
    159     attribute DOMString textBaseline; // "top", "hanging", "middle", "alphabetic", "ideographic", "bottom" (default: "alphabetic")
    160     [RuntimeEnabled=ExperimentalCanvasFeatures] attribute DOMString direction; // "inherit", "rtl", "ltr" (default: "inherit")
    161 
    162     // Non-standard APIs. Candidates for deprecation
    163     // https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D
    164     [MeasureAs=CanvasRenderingContext2DSetAlpha] void setAlpha(unrestricted float alpha);
    165     [MeasureAs=CanvasRenderingContext2DSetCompositeOperation] void setCompositeOperation(DOMString compositeOperation);
    166     [MeasureAs=CanvasRenderingContext2DSetLineWidth] void setLineWidth(unrestricted float width);
    167     [MeasureAs=CanvasRenderingContext2DSetLineCap] void setLineCap(DOMString cap);
    168     [MeasureAs=CanvasRenderingContext2DSetLineJoin] void setLineJoin(DOMString join);
    169     [MeasureAs=CanvasRenderingContext2DSetMiterLimit] void setMiterLimit(unrestricted float limit);
    170     [MeasureAs=CanvasRenderingContext2DClearShadow] void clearShadow();
    171     [MeasureAs=CanvasRenderingContext2DSetStrokeColor] void setStrokeColor(DOMString color, optional unrestricted float alpha);
    172     [MeasureAs=CanvasRenderingContext2DSetStrokeColor] void setStrokeColor(unrestricted float grayLevel, optional unrestricted float alpha);
    173     [MeasureAs=CanvasRenderingContext2DSetStrokeColor] void setStrokeColor(unrestricted float r, unrestricted float g, unrestricted float b, unrestricted float a);
    174     [MeasureAs=CanvasRenderingContext2DSetStrokeColor] void setStrokeColor(unrestricted float c, unrestricted float m, unrestricted float y, unrestricted float k, unrestricted float a);
    175     [MeasureAs=CanvasRenderingContext2DSetFillColor] void setFillColor(DOMString color, optional unrestricted float alpha);
    176     [MeasureAs=CanvasRenderingContext2DSetFillColor] void setFillColor(unrestricted float grayLevel, optional unrestricted float alpha);
    177     [MeasureAs=CanvasRenderingContext2DSetFillColor] void setFillColor(unrestricted float r, unrestricted float g, unrestricted float b, unrestricted float a);
    178     [MeasureAs=CanvasRenderingContext2DSetFillColor] void setFillColor(unrestricted float c, unrestricted float m, unrestricted float y, unrestricted float k, unrestricted float a);
    179     [MeasureAs=CanvasRenderingContext2DDrawImageFromRect] void drawImageFromRect(
    180         HTMLImageElement? image, optional unrestricted float sx, optional unrestricted float sy, optional unrestricted float sw, optional unrestricted float sh,
    181         optional unrestricted float dx, optional unrestricted float dy, optional unrestricted float dw, optional unrestricted float dh, optional DOMString compositeOperation);
    182     [MeasureAs=CanvasRenderingContext2DSetShadow] void setShadow(unrestricted float width, unrestricted float height, unrestricted float blur, optional DOMString color, optional unrestricted float alpha);
    183     [MeasureAs=CanvasRenderingContext2DSetShadow] void setShadow(unrestricted float width, unrestricted float height, unrestricted float blur, unrestricted float grayLevel, optional unrestricted float alpha);
    184     [MeasureAs=CanvasRenderingContext2DSetShadow] void setShadow(unrestricted float width, unrestricted float height, unrestricted float blur, unrestricted float r, unrestricted float g, unrestricted float b, unrestricted float a);
    185     [MeasureAs=CanvasRenderingContext2DSetShadow] void setShadow(unrestricted float width, unrestricted float height, unrestricted float blur, unrestricted float c, unrestricted float m, unrestricted float y, unrestricted float k, unrestricted float a);
    186 };
    187 
    188 CanvasRenderingContext2D implements CanvasPathMethods;
    189