Ok, here's some updated text... how's this look?
object getContext(in DOMString contextId, in optional
any attributes)
'contextId' must be a string naming a canvas rendering context to be
returned. For example, this specification defines the '2d' context,
which, if requested, will return either a reference to an object
implementing CanvasRenderingContext2D or null, if a 2D context cannot
be created at this time. Other specifications may define
their own contexts, which would return different objects.
If getContext() is called with a contextId that the implementation
supports and such a context can be created, a reference to an object
implementing the context API is returned and the new context is added
to the list of active contexts for this canvas. If contextId is not
supported or it cannot be created, null is returned. The optional
'attributes' parameter must be either null, or an object
specific to the context being requested. A null or unspecified value
for the 'attributes' parameter is equivalent to requesting default
attributes for the given context. Any unknown attributes should be
ignored by the context.
If the canvas has at least one active context and getContext() is
called with a contextId that names an already-active context, it must
return the same resulting context object
provided that the attributes are identical to all previous requests for
that context ID. If the attributes are not identical, getContext()
must raise an INVALID_STATE_ERR exception. (XXX is INVALID_STATE the
right thing here? or is SYNTAX_ERR better?) Deciding which attributes
are identical is up to the specific context being requested, but should
mean that the requested attributes and their values are the same as in
all previous getContext() calls with this contextId.
If the canvas has at least one active context and getContext() is
called with a contextId that does not name an already-active context,
it may
either return a new canvas context that can be used simultaneously with
all previously obtained contexts, or return null to indicate that the
newly requested context cannot be used with the previously obtained
contexts. If a non-null value is returned, the new context is added to
the list of active contexts for this canvas.
If multiple rendering contexts are active, they all render to the same
canvas bitmap; they are not layered or otherwise isolated. Changes
made to
the canvas bitmap with one context must be immediately visible to any
other
active contexts on the canvas. It is up to the implementation to
manage synchronization issues associated with rendering with different
contexts to the same canvas.
|