Skip to content
Permalink
Browse files

[giow] (2) Redefine getContext() so that the handling of multple cont…

…ext types is defined.

git-svn-id: http://svn.whatwg.org/webapps@5227 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information...
Hixie committed Aug 2, 2010
1 parent 38230bf commit f6e15bb2462fbd15304401d133107fbecdf2c2fa
Showing with 318 additions and 112 deletions.
  1. +97 −33 complete.html
  2. +97 −33 index
  3. +124 −46 source

<header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG src=/images/logo></a></p>
<hgroup><h1>Web Applications 1.0</h1>
<h2 class="no-num no-toc">Draft Standard &mdash; 30 July 2010</h2>
<h2 class="no-num no-toc">Draft Standard &mdash; 2 August 2010</h2>
</hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
context.fillRect(100,0,50,50); // only this square remains</pre>
</div>

<p>To draw on the canvas, authors must first obtain a reference to a
<dfn id=context>context</dfn> using the <dfn id=dom-canvas-getcontext title=dom-canvas-getContext><code>getContext(<var title="">contextId</var>)</code></dfn> method of the
<code><a href=#the-canvas-element>canvas</a></code> element.</p>

<dl class=domintro><dt><var title="">context</var> = <var title="">canvas</var> . <code title=dom-canvas-getContext><a href=#dom-canvas-getcontext>getContext</a></code>(<var title="">contextId</var>)</dt>
<hr><dl class=domintro><dt><var title="">context</var> = <var title="">canvas</var> . <code title=dom-canvas-getContext><a href=#dom-canvas-getcontext>getContext</a></code>(<var title="">contextId</var>)</dt>

<dd>

<p>Returns an object that exposes an API for drawing on the canvas.</p>
<p>Returns an object that exposes an API for drawing on the
canvas. The argument specifies the desired API.</p>

<!--2DCONTEXT-->

<p>This specification defines the "<code title=canvas-context-2d><a href=#canvas-context-2d>2d</a></code>" context below. There is also
a specification that defines a "<code title=canvas-context-webgl>webgl</code>" context. <a href=#refsWEBGL>[WEBGL]</a></p>

<!--2DCONTEXT-->

<p>The list of defined contexts is given on the <a href=http://wiki.whatwg.org/wiki/CanvasContexts>WHATWG Wiki
CanvasContexts page</a>. <a href=#refsWHATWGWIKI>[WHATWGWIKI]</a>

<p>Returns null if the given context ID is not supported.</p>
<p>Returns null if the given context ID is not supported or if the
canvas has already been initialised with some other (incompatible)
context type (e.g. trying to get a "<code title=canvas-context-2d><a href=#canvas-context-2d>2d</a></code>" context after getting a
"<code title=canvas-context-webgl>webgl</code>" context).</p>

</dd>

</dl><!--2DCONTEXT--><p>This specification only defines one context, with the name "<code title=canvas-context-2d><a href=#canvas-context-2d>2d</a></code>". <span class=impl>If <code title=dom-canvas-getContext><a href=#dom-canvas-getcontext>getContext()</a></code> is called with
that exact string for its <var title="">contextId</var> argument,
then the UA must return a reference to an object implementing
<code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code>. Other specifications may
define their own contexts, which would return different
objects.</span></p>
</dl><div class=impl>

<!--2DCONTEXT-->
<p>A <code><a href=#the-canvas-element>canvas</a></code> element can have a <dfn id=primary-context>primary
context</dfn>, which is the first context to have been obtained for
that element. When created, a <code><a href=#the-canvas-element>canvas</a></code> element must not
have a <a href=#primary-context>primary context</a>.</p>

<div class=impl>
<p>The <dfn id=dom-canvas-getcontext title=dom-canvas-getContext><code>getContext(<var title="">contextId</var>)</code></dfn> method of the
<code><a href=#the-canvas-element>canvas</a></code> element, when invoked, must run the following
steps:</p>

<p>Vendors may also define experimental contexts using the syntax
<code><var title="">vendorname</var>-<var title="">context</var></code>, for example, <code>moz-3d</code>.</p>
<ol><li><p>Let <var title="">contextId</var> be the argument to the
method.</li>

<li><p>If <var title="">contextId</var> is not the name of a
context supported by the user agent, return null and abort these
steps.</li>

<li><p>If the element has a <a href=#primary-context>primary context</a> and that
context's entry in the <a href=http://wiki.whatwg.org/wiki/CanvasContexts>WHATWG Wiki
CanvasContexts page</a> does not list <var title="">contextId</var>
as a context with which it is compatible, return null and abort
these steps. <a href=#refsWHATWGWIKI>[WHATWGWIKI]</a></li>

<li><p>If the element does not have a <a href=#primary-context>primary context</a>,
let the element's <a href=#primary-context>primary context</a> be <var title="">contextId</var>.</li>

<p>When the UA is passed an empty string or a string specifying a
context that it does not support, then it must return null. String
comparisons must be <a href=#case-sensitive>case-sensitive</a>.</p>
<li><p>If the <code title=dom-canvas-getContext><a href=#dom-canvas-getcontext>getContext()</a></code> method has
already been invoked on this element for the same <var title="">contextId</var>, return the same object as was returned
that time, and abort these steps.</li>

<li><p><dfn id=getcontext-return title=getContext-return>Return a new object for <var title="">contextId</var></dfn>, as defined by the specification
given for <var title="">contextId</var>'s entry in the <a href=http://wiki.whatwg.org/wiki/CanvasContexts>WHATWG Wiki
CanvasContexts page</a>. <a href=#refsWHATWGWIKI>[WHATWGWIKI]</a></li>

</ol><p>New context types may be registered in the <a href=http://wiki.whatwg.org/wiki/CanvasContexts>WHATWG Wiki
CanvasContexts page</a>. <a href=#refsWHATWGWIKI>[WHATWGWIKI]</a></p>

<p>Anyone is free to edit the WHATWG Wiki CanvasContexts page at any
time to add a new context type. These new context types must be
specified with the following information:</p>

<dl><dt>Keyword</dt>

<dd><p>The value of <var title="">contextID</var> that will return
the object for the new API.</dd>


<dt>Specification</dt>

<dd><p>A link to a formal specification of the context type's
API. It could be another page on the Wiki, or a link to an external
page. If the type does not have a formal specification, an informal
description can be substituted until such time as a formal
specification is available.</dd>


<dt>Compatible with</dt>

<dd><p>The list of context types that are compatible with this one
(i.e. that operate on the same underlying bitmap). This list must
be transitive and symmetric; if one context type is defined as
compatible with another, then all types it is compatible with must
be compatible with all types the other is compatible with.</dd>

</dl><p>Vendors may also define experimental contexts using the syntax
<code><var title="">vendorname</var>-<var title="">context</var></code>, for example,
<code>moz-3d</code>. Such contexts should be registered in the
WHATWG Wiki CanvasContexts page.</p>

</div>


<!-- v2: we're on v4. suggestions for next version are marked v5. -->

<p>When the <code title=dom-canvas-getContext><a href=#dom-canvas-getcontext>getContext()</a></code>
method of a <code><a href=#the-canvas-element>canvas</a></code> element is invoked with <dfn id=canvas-context-2d title=canvas-context-2d><code>2d</code></dfn> as the argument, a
<code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object is returned.</p>



<div class=impl>
<p>This specification defines the <dfn id=canvas-context-2d title=canvas-context-2d><code>2d</code></dfn> context type, whose
API is implemented using the <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code>
interface.</p>

<div class=impl>

<p>There is only one <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object
per canvas, so calling the <code title=dom-canvas-getContext><a href=#dom-canvas-getcontext>getContext()</a></code> method with the
<code title=canvas-context-2d><a href=#canvas-context-2d>2d</a></code> argument a second time
must return the same object.</p>
<p>When the <code title=dom-canvas-getContext><a href=#dom-canvas-getcontext>getContext()</a></code>
method of a <code><a href=#the-canvas-element>canvas</a></code> element is is to <a href=#getcontext-return title=getContext-return>return a new object for the <var title="">contextId</var></a> <code title=canvas-context-2d><a href=#canvas-context-2d>2d</a></code>, the user agent must return a
new <code><a href=#canvasrenderingcontext2d>CanvasRenderingContext2D</a></code> object.</p>

</div>


<p>When an element with the <code title=attr-fe-autofocus><a href=#attr-fe-autofocus>autofocus</a></code> attribute specified is
<a href=#insert-an-element-into-a-document title="insert an element into a document">inserted into a
document</a>, user agents should run the following steps:</p>~
document</a>, user agents should run the following steps:</p>

<ol><li><p>If the <code><a href=#document>Document</a></code>'s <a href=#browsing-context>browsing context</a>
had the <a href=#sandboxed-automatic-features-browsing-context-flag>sandboxed automatic features browsing context
deleted</a>.</li>
<li><p>Invoke the <a href=#html-fragment-parsing-algorithm>HTML fragment parsing algorithm</a>
with an arbitrary orphan <code><a href=#the-body-element-0>body</a></code> element owned by the
same <code><a href=#document>Document</a></code> as the <i><a href=#context>context</a></i> element and with
the <var title="">value</var> argument as <i><a href=#the-input-element>input</a></i>.</li>
same <code><a href=#document>Document</a></code> as the <i title="">context</i> element
and with the <var title="">value</var> argument as <i title="">input</i>.</li>
<li><p>Insert the nodes returned by the previous step into the
document at the location of the caret, firing any mutation events
as appropriate.</li>
addresses in HTML5</a></cite>, D. Connolly,
C. Sperberg-McQueen.</dd>

<dt id=refsWEBGL>[WEBGL]</dt>
<dd><cite><a href=https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/WebGL-spec.html>WebGL
Specification</a></cite>, C. Marrin. Khronos Group.</dd>

<dt id=refsWEBIDL>[WEBIDL]</dt>
<!--
<dd><cite><a href="http://www.w3.org/TR/WebIDL/">Web
Oops, something went wrong.

0 comments on commit f6e15bb

Please sign in to comment.
You can’t perform that action at this time.