WHATWG Wiki - User contributions [en]

CanvasRenderedPixelSize

2014-06-24T01:03:54Z

Roc: Created page with ":''This proposal is to allow Web developers to match canvas backing store resolution to device resolution.'' == Use Case Descriptions == Use case #1: a Web application needs..."

:''This proposal is to allow Web developers to match canvas backing store resolution to device resolution.''

== Use Case Descriptions ==

Use case #1: a Web application needs to render content to a canvas (using 2D or WebGL contexts) being displayed on a high-DPI screen. For best quality output, the pixels of the canvas backing store need to match 1:1 with screen pixels.

Use case #2: As #1, and the user moves the page from screen to screen resulting in dynamic DPI changes.

Use case #3: As #1, and the canvas is inside a CSS scale transform which may change dynamically.

Use case #4: As #1, and the canvas's CSS content box has arbitrary fractional CSS pixel size and offset from the viewport.

Use case #5: As #3, but the canvas is inside an <code><iframe></code> in a page with a different origin which contains the CSS transform.

=== Current Usage and Workarounds ===

Safari shipped a canvas implementation that automatically resized the backing store but this caused various problems, such as incompatibility with some existing content and a need for new "HD" APIs that authors were not motivated to use. This approach does not work for WebGL in any case.

The current best workaround is to set the canvas backing store size by computing the canvas content box in CSS pixels relative to the viewport, as accurately as possible (e.g. using <code>getBoxQuads</code>), multiplying by <code>window.devicePixelRatio</code>, and using that to set the canvas width and height. This approach does not easily adapt to dynamic changes and does not handle use cases #4 or #5. In use-case #4 the computed device pixel size may be non-integer, in which case the UA is likely to snap the content-box to device pixel edges and the Web developer cannot predict how that snapping will be done. In use-case #5 the developer cannot know about the CSS transform in the foreign-origin content.

== Goals ==

# Leave the application in control of setting the pixel size of the backing store.
# Retain the invariant that 1 unit in canvas coordinate space is 1 backing store pixel.
# Make it easy for applications to set the pixel size of the backing store so that backing store pixels are 1:1 with device pixels, when that's possible.

== Non Goals ==

# Enable high-resolution backing store for existing content.

== Proposed Solutions ==

Hixie proposed a canvas attribute to opt into automatic sizing of the backing store, but this violates goals #1 and #2. Violating goal #1 is a problem because applications often use temporary canvases and other assets which are dependent on the pixel size of the backing store. Goal #1 is also essential for WebGL.

=== Suggested Solution ===

Expose a preferred size for the canvas backing store directly to Web authors. Web authors who want to match screen resolution set the canvas width and height to that size. Expose an event on the canvas that fires when the preferred size changes.

== Suggested IDL ==

Add two new DOM attributes to <code>HTMLCanvasElement</code>:

<pre>partial interface HTMLCanvasElement {
readonly attribute long renderedPixelWidth;
readonly attribute long renderedPixelHeight;
};</pre>

The values of these attributes are not normatively defined. For example, a UA might reduce these values to conserve system resources.
However, under normal steady-state conditions a UA is expected to choose values such that, if the canvas element has a CSS background color exactly filling its content-box, and the UA renders that CSS background color as a rectangle whose edges are aligned to device pixel edges, then <code>renderedPixelWidth</code> and <code>renderedPixelHeight</code> are the device pixel size of that rectangle.

Add a new event <code>renderedsizechange</code> to <code>HTMLCanvasElement</code>. This event does not bubble and is not cancelable. Whenever the value that would be returned by <code>renderedPixelWidth</code> or <code>renderedPixelHeight</code> changes, queue a task to fire <code>renderedsizechange</code> at the <code>HTMLCanvasElement</code> if there is not already a task pending to fire such an event at that element.

== Rationale: ==

This API appears to be the minimal API needed to achieve the goals, is opt-in, and can be used in several different ways depending on how ambitious the app developer is:
* Simplest possible usage: set the canvas size once when loading and don't handle dynamic changes.
<pre> <script>
canvas.width = canvas.renderedPixelWidth; canvas.height = canvas.renderedPixelHeight;
</script></pre>
* Update canvas size for every frame of a game:
<pre> <script>
function renderFrame() {
canvas.width = canvas.renderedPixelWidth; canvas.height = canvas.renderedPixelHeight;
...
window.requestAnimationFrame(renderFrame);
}
</script></pre>
* Update canvas size and re-render only when DPI changes:
<pre> <script>
function render() {
canvas.width = canvas.renderedPixelWidth; canvas.height = canvas.renderedPixelHeight;
...
}
canvas.addEventHandler("renderedsizechange", render, false);
</script></pre>

== Issues: ==

None known.

[[Category:Proposals]]

WorkerCanvas

2013-10-24T09:24:52Z

Roc:

WorkerCanvas

2013-10-22T21:59:28Z

Roc: /* Spec changes */

WorkerCanvas

2013-10-22T21:56:56Z

Roc: /* Spec changes */

WorkerCanvas

2013-10-22T21:55:19Z

Roc: /* WebIDL */

WorkerCanvas

2013-10-22T21:51:53Z

Roc: /* WebIDL */

WorkerCanvas

2013-10-22T21:48:44Z

Roc:

WorkerCanvas

2013-10-22T21:48:23Z

Roc: /* WebIDL */

== WebIDL ==

[Constructor(unsigned long width, unsigned long height)]
interface WorkerCanvas {
attribute unsigned long width;
attribute unsigned long height;
RenderingContext? getContext(DOMString contextId, any... arguments);
void toBlob(FileCallback? _callback, optional DOMString type, any... arguments);
ImageBitmap transferToImageBitmap();
};

partial interface RenderingContext {
void commit();
};

WorkerCanvas implements Transferable;
ImageBitmap implements Transferable;

partial interface HTMLCanvasElement {
WorkerCanvas transferControlToWorker();
};

partial interface ImageBitmap {
void transferToCanvas((HTMLCanvasElement or WorkerCanvas) canvas);
void close();
};

== Spec changes ==

Transferring of ImageBitmaps has to be defined. It should neuter the ImageBitmap in the sending thread. ImageBitmap.close also neuters the ImageBitmap. Neutering should set the ImageBitmap's width and height to 0.

HTMLCanvasElement.transferControlToWorker behaves like transferControlToProxy in the current WHATWG spec. WorkerCanvas is Transferable, but transfer fails if transferred other than from the main thread to a worker. All its methods throw if not called on a worker, or if it's neutered.

ImageBitmap.transferToCanvas replaces the canvas contents with the contents of the ImageBitmap, setting the canvas size to the ImageBitmap's size.

== Spec changes ==

Structured clone of ImageBitmaps has to be defined; since they're immutable, it's straightforward. The implementation can share the underlying buffer data across threads. An ImageBitmap can also be implemented as the result of deferred rendering of a list of drawing commands.

transferControlToWorker behaves like transferControlToProxy in the current WHATWG spec. WorkerCanvas is Transferable, but transfer fails if transferred other than from the main thread to a worker. All its methods throw if not called on a worker, or if it's neutered.

HTMLImageElement.srcObject behaves like HTMLMediaElement.srcObject: if non-null, it takes precedence over the "src" attribute and renders the contents of the Blob (as a decoded image) or the ImageBitmap.

WorkerCanvas

2013-10-22T21:41:13Z

Roc: Created page with "== WebIDL == [Constructor(unsigned long width, unsigned long height)] interface WorkerCanvas { attribute unsigned long width; attribute unsigned long height; Rende..."