Skip to content

Commit

Permalink
Add drawingBufferColorSpace/unpackColorSpace attributes to WebGLRende…
Browse files Browse the repository at this point in the history 
…ringContextBase. (#3292)

Define their behavior both for presenting the rendering context's
results, and uploading textures via texImage2D / texSubImage2D from
DOM inputs (the TexImageSource union type). Notably:

 - The drawing buffer is reallocated when drawingBufferColorSpace is
   changed.

 - unpackColorSpace applies to ImageBitmaps.

Follows whatwg/html#6562 , in which the
PredefinedColorSpace enum was defined, and its behavior for 2D canvas
contexts specified.

Address review feedback from kainino, ccameron-chromium and kdashg.
  • Loading branch information
@kenrussell
kenrussell committed May 7, 2022
1 parent 8822798 commit 2be1eff
Showing 1 changed file with 62 additions and 10 deletions.
72 changes: 62 additions & 10 deletions specs/latest/1.0/index.html
View file
Expand Up @@ -1721,6 +1721,8 @@ <h3><a name="WEBGLRENDERINGCONTEXT">The WebGL context</a></h3>
readonly attribute (HTMLCanvasElement or OffscreenCanvas) canvas;
readonly attribute GLsizei drawingBufferWidth;
readonly attribute GLsizei drawingBufferHeight;
attribute PredefinedColorSpace drawingBufferColorSpace = "srgb";
attribute PredefinedColorSpace unpackColorSpace = "srgb";

[WebGLHandlesContextLoss] WebGLContextAttributes? getContextAttributes();
[WebGLHandlesContextLoss] boolean isContextLost();
Expand Down Expand Up @@ -1979,6 +1981,33 @@ <h4>Attributes</h4>
The actual height of the drawing buffer. May be different from the
<code>height</code> attribute of the <code>HTMLCanvasElement</code> if
the implementation is unable to satisfy the requested width or height.
<dt>
<code class=attribute-name>
<a id="DOM-WebGLRenderingContext-drawingBufferColorSpace">
drawingBufferColorSpace
</a>
</code>
of type <code><a href="https://html.spec.whatwg.org/multipage/canvas.html#predefinedcolorspace">PredefinedColorSpace</a></code>
<a href="#refsPREDEFINEDCOLORSPACE">(specification)</a>
<dd>
The color space used to interpret the drawing buffer's content values.
Changing this attribute causes the drawing buffer to be reallocated; its
current contents are lost. This attribute affects the on-screen display
of the rendering context, and the interpretation of this context's
drawing buffer when it is drawn to a 2D canvas context, or uploaded to
textures in another WebGL or <a href="#refsWEBGPU">WebGPU</a> rendering
context.
<dt>
<code class=attribute-name>
<a id="DOM-WebGLRenderingContext-unpackColorSpace">
unpackColorSpace
</a>
</code>
of type <code><a href="https://html.spec.whatwg.org/multipage/canvas.html#predefinedcolorspace">PredefinedColorSpace</a></code>
<a href="#refsPREDEFINEDCOLORSPACE">(specification)</a>
<dd>
The color space into which <code>TexImageSource</code> sources are
converted when uploading them to textures in this context.
</dl>

<!-- ======================================================================================================= -->
Expand Down Expand Up @@ -2653,10 +2682,27 @@ <h4>Texture objects</h4>
The width and height of the texture are set as specified in section
<a href="#TEXTURE_UPLOAD_SIZE">Texture Upload Width and Height</a>.<br><br>

The source image data is conceptually first converted to the data type and format
specified by the <em>format</em> and <em>type</em> arguments, and then transferred to
the WebGL implementation. Format conversion is performed according to the following table.
If a packed pixel format is specified which would imply loss of bits of precision from the
First, the source image data is conceptually converted to the color space specified by
the <a href="#DOM-WebGLRenderingContext-unpackColorSpace">unpackColorSpace</a>
attribute, except if the source image data is an <code>HTMLImageElement</code>, and
the <code>UNPACK_COLORSPACE_CONVERSION_WEBGL</code> pixel storage parameter is set
to <code>NONE</code>. <br><br>

<div class="note rationale">

This color space conversion applies to <code>ImageBitmap</code> objects as well, though
other texture unpack parameters do not apply to <code>ImageBitmap</code>s because they
are expected to be specified during <code>ImageBitmap</code> construction.
Implementation experience revealed that it was beneficial to
perform <code>ImageBitmap</code>s' color space conversion as late as possible when
uploading to WebGL textures.

</div>

Next, the source image data is converted to the data type and format specified by
the <em>format</em> and <em>type</em> arguments, and then transferred to the WebGL
implementation. Format conversion is performed according to the following table. If a
packed pixel format is specified which would imply loss of bits of precision from the
image data, this loss of precision must occur. <br><br>

<table class="foo">
Expand Down Expand Up @@ -2799,12 +2845,8 @@ <h4>Texture objects</h4>
<a href="#TEXTURE_UPLOAD_SIZE">Texture Upload Width and Height</a>.<br><br>

See <a href="#TEXIMAGE2D_HTML">texImage2D</a> for the interpretation of
the <em>format</em> and <em>type</em> arguments, and notes on
the <code>UNPACK_PREMULTIPLY_ALPHA_WEBGL</code> pixel storage parameter. <br><br>

See <a href="#PIXEL_STORAGE_PARAMETERS">Pixel Storage Parameters</a> for WebGL-specific
pixel storage parameters that affect the behavior of this function when it is called
with any argument type other than <code>ImageBitmap</code>. <br><br>
the <em>format</em> and <em>type</em> arguments, handling of WebGL-specific pixel
storage parameters, and potential color space transformations of the input. <br><br>

The first pixel transferred from the source to the WebGL implementation corresponds
to the upper left corner of the source. This behavior is modified by the
Expand Down Expand Up @@ -4587,6 +4629,16 @@ <h2>References</h2>
<dd>(Non-normative) <cite><a href="https://w3c.github.io/webcodecs/">WebCodecs API</a></cite>,
C. Cunningham, P. Adenot, B. Aboba. W3C.
</dd>
<dt id="refsPREDEFINEDCOLORSPACE">[PREDEFINEDCOLORSPACE]</dt>
<dd><cite><a href="https://html.spec.whatwg.org/multipage/canvas.html#predefinedcolorspace">
HTML Living Standard - The PredefinedColorSpace enum</a></cite>,
WHATWG.
</dd>
<dt id="refsWEBGPU">[WEBGPU]</dt>
<dd><cite><a href="https://gpuweb.github.io/gpuweb/">
WebGPU Editor's Draft</a></cite>,
WebGPU Community Group.
</dd>
</dl>

<!-- ======================================================================================================= -->
Expand Down

0 comments on commit 2be1eff

Please sign in to comment.