Skip to content

add first prototype of texElementImage2D #3752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cabanier wants to merge 9 commits into
base: main
Choose a base branch
from
Open

add first prototype of texElementImage2D #3752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
3e411b1
add first prototype of texElementImage2D
cabanier Dec 15, 2025
c16ae72
add addition texElementImage2D + constraints + address review comments
cabanier Dec 19, 2025
948dc72
Add missing definitions of texElementImage2D
cabanier Apr 25, 2026
5a802e7
incorporate texElementImage2D feedback
cabanier May 30, 2026
8a4b80c
address @szager-chromium review comments
cabanier May 30, 2026
ab6501e
address @lexaknyazev's comments
cabanier Jun 18, 2026
51f5f85
address feedback
cabanier Jun 25, 2026
40c3709
Restore mip level for texElementImage2D
cabanier Jun 29, 2026
ef71b45
Make texElementImage2D update existing texture storage
cabanier Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions specs/latest/2.0/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,15 @@ <h3>Types</h3>
<pre class="idl">
typedef long long GLint64;
typedef unsigned long long GLuint64;

dictionary WebGLCopyElementImageConfig {
GLfloat sx;
GLfloat sy;
GLfloat swidth;
GLfloat sheight;
GLsizei width;

@szager-chromium szager-chromium Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add GLint xoffset and GLint yoffset parameters after sheight.

@lexaknyazev lexaknyazev Aug 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current Element API is

texElementImage2D(target, level, internalformat, element, config)

The texSubImage2D API is

texSubImage2D(target, level, xoffset, yoffset, ...)

Given that the proposed xoffset and yoffset parameters refer to the GL API, why add them to the config object (that is Element-specific) instead of the command (that is GL-specific)? I'd expect them to be in the same group as the level and the WebGL WG decided that level should be among the command parameters, not the config object.

@lexaknyazev lexaknyazev Aug 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also since the new design no longer allocates a GL texture, the internalformat parameter needs to be moved to the config.

@lexaknyazev lexaknyazev Aug 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In other words:

  • parameters that drive Element rasterization should be in the config;
  • parameters that directly interact with GL should be on their usual places.

@szager-chromium szager-chromium Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The motivation for moving parameters to WebGLCopyElementImageConfig was just to avoid the need for overloads of the method just to accommodate various permutations of geometry arguments. The existing WebGLCopyElementImageConfig.(width|height) parameters already specify a destination size, and any scaling they imply is performed by GL, not by web content rendering. So I don't think adding xoffset and yoffset here contradicts any existing design principle or separation of web-specific from GL-specific arguments. The purpose of WebGLCopyElementImageConfig is really to encapsulate all the geometry.

@cabanier cabanier Aug 3, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should get this on the WebGL working group agenda and discuss it there, what do you think?

+1. I'll hold off on making changes until it's been discussed.

@szager-chromium szager-chromium Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lexaknyazev -- thinking more about this, I see your point about aligning with the function signature of texSubImage2D and keeping the GL-specific parameters separate. Until you pointed it out, I didn't actually know that the automatic scaling behavior of the width and height parameters was specific to the WebGL layer.

I'm OK with putting xoffset and yoffset in the main method signature rather than in the config. I also think that we can probably get rid of the internalFormat parameter. So the new IDL would be:

  undefined texElementImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
                              (Element or ElementImage) element,
                              optional WebGLCopyElementImageConfig config = {}); // May throw DOMException

Does this look good to you?

@szager-chromium szager-chromium Aug 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lexaknyazev -- I think we're going to proceed with this change to the API, but I'm hoping we can get you to weigh in first; thanks.

@lexaknyazev lexaknyazev Aug 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New IDL shown in #3752 (comment) looks good to me.

@cabanier cabanier Aug 13, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the PR

GLsizei height;
};
</pre>

<!-- ======================================================================================================= -->
Expand Down Expand Up @@ -935,6 +944,10 @@ <h3><a name="WEBGLRENDERINGCONTEXT">The WebGL context</a></h3>
optional unsigned long long srcOffset = 0,
optional GLuint srcLengthOverride = 0);

undefined texElementImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
(Element or ElementImage) element,
optional WebGLCopyElementImageConfig config = {}); // May throw DOMException

undefined uniform1fv(WebGLUniformLocation? location, Float32List data, optional unsigned long long srcOffset = 0,
optional GLuint srcLength = 0);
undefined uniform2fv(WebGLUniformLocation? location, Float32List data, optional unsigned long long srcOffset = 0,
Expand Down Expand Up @@ -2210,6 +2223,36 @@ <h4>Texture objects</h4>
<p><em>offset</em> is the byte offset into the WebGLBuffer's data store; generates an <code>INVALID_VALUE</code> error if it's less than 0.</p>
<p>The ETC2 and EAC texture formats defined in OpenGL ES 3.0 are <a href="#NO_ETC2_EAC">not available in WebGL 2.0</a>.
</dd>

<dt class="idl-code">
[throws] undefined texElementImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
(Element or ElementImage) element,
optional WebGLCopyElementImageConfig config = {});
</dt>
<dd>
<p>Like <code>texSubImage2D</code>, this function updates a rectangular subregion of an existing texture image. It does not define or allocate texture storage. The texture image identified by <code>target</code> and <code>level</code> must have been previously defined, for example by calling <code>texImage2D</code> or <code>texStorage2D</code>; otherwise, generates an <code>INVALID_OPERATION</code> error.</p>
<p>The <code>level</code> argument identifies the mipmap level of the texture object bound to <code>target</code> to update. The <code>xoffset</code> and <code>yoffset</code> arguments specify the offsets, in texels, within that mipmap level at which the update begins.</p>
<p>The <code>element</code> argument identifies an <a href="https://whatpr.org/html/11588/canvas.html#concept-canvas-element-image-snapshots">element image snapshot</a>, as defined by HTML. The HTML algorithms define how element image snapshots are created, updated, retrieved, and filtered for security- or privacy-sensitive information. If <code>element</code> is an <code>Element</code>, the source rendering is the snapshot from the most recent <code>paint</code> event for the <a href="#context-canvas">canvas</a> of the current context. If <code>element</code> is an <code>ElementImage</code>, the source rendering is that captured snapshot.</p>
<p>If this function is called with an <code>Element</code> that is not a direct child of the <a href="#context-canvas">canvas</a> of the current context in the most recent rendering update, generates an <code>INVALID_OPERATION</code> error.</p>
<p>If <code>target</code> is not <code>TEXTURE_2D</code>, generates an <code>INVALID_ENUM</code> error.</p>
<p>If no <code>WebGLTexture</code> is bound to <code>target</code>, generates an <code>INVALID_OPERATION</code> error.</p>
<p>If a WebGLBuffer is bound to the <code>PIXEL_UNPACK_BUFFER</code> target, generates an <code>INVALID_OPERATION</code> error.</p>
<p>All <code>UNPACK_</code> pixel store parameters are ignored by this function.</p>
<p>If <code>config.sx</code>, <code>config.sy</code>, <code>config.swidth</code>, and <code>config.sheight</code> are all supplied, they define the source rectangle of the element image snapshot to render, in CSS pixels. If none of them are supplied, the source rectangle has <code>sx</code> and <code>sy</code> of 0, <code>swidth</code> equal to the source's natural width, and <code>sheight</code> equal to the source's natural height. If only some of them are supplied, generates an <code>INVALID_VALUE</code> error.</p>
<p>If <code>config.width</code> and <code>config.height</code> are both supplied, they define, in texels, the size of the rasterized image and the destination subregion to update. The source rectangle is scaled to these dimensions. If neither member is supplied, the width and height default to the source rectangle size scaled by the inverse of the canvas-grid-to-CSS scaling factor used to produce the element image snapshot. If only one of them is supplied, generates an <code>INVALID_VALUE</code> error.</p>
<p>The internal format of the texture image identified by <code>target</code> and <code>level</code> must be one of the values in the following table. Each value has an implied source format of <code>RGBA</code> and the listed implied source type:</p>
<table>
<tr><th>Texture Internal Format</th><th>Implied Source Type</th></tr>
<tr><td>RGBA8</td><td>UNSIGNED_BYTE</td></tr>
<tr><td>SRGB8_ALPHA8</td><td>UNSIGNED_BYTE</td></tr>
<tr><td>RGBA16F</td><td>HALF_FLOAT</td></tr>
<tr><td>RGBA32F</td><td>FLOAT</td></tr>
Comment on lines +2248 to +2249

@lexaknyazev lexaknyazev Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The spec should be very clear about the transfer functions used in each case.

I'd expect that 8-bit values are always sRGB-encoded and the choice between RGBA8 and SRGB8_ALPHA8 is only to allow apps to bypass hardware sRGB decoding during texture sampling if they wish so for some reason.

However, floating-point values are usually not sRGB encoded. If we aren't sure about the latter, maybe floating-point options could be omitted for now.

</table>
<p>The RGBA source values produced by rendering the element image snapshot are computed independently of the texture's internal format. In particular, when the internal format is <code>RGBA8</code> or <code>SRGB8_ALPHA8</code>, the generated <code>UNSIGNED_BYTE</code> source values are identical; the choice between those formats only affects the texture's storage and subsequent sampling behavior.</p>
<p>If the texture image's internal format is not listed in the table above, generates an <code>INVALID_OPERATION</code> error.</p>
<p>If <code>level</code>, <code>xoffset</code>, or <code>yoffset</code> is negative, or if the destination subregion extends outside the texture image, generates an <code>INVALID_VALUE</code> error.</p>
<p>If any supplied numeric member of <code>config</code> is negative, or if the computed source rectangle width, source rectangle height, rasterized image width, or rasterized image height is not positive, generates an <code>INVALID_VALUE</code> error.</p>
</dd>
</dl>

<!-- ======================================================================================================= -->
Expand Down
14 changes: 13 additions & 1 deletion specs/latest/2.0/webgl2.idl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,15 @@
typedef long long GLint64;
typedef unsigned long long GLuint64;

dictionary WebGLCopyElementImageConfig {
GLfloat sx;
GLfloat sy;
GLfloat swidth;
GLfloat sheight;
GLsizei width;

@szager-chromium szager-chromium Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add GLint xoffset and GLint yoffset

GLsizei height;
};


[Exposed=(Window,Worker)]
interface WebGLQuery : WebGLObject {
Expand Down Expand Up @@ -558,6 +567,10 @@ interface mixin WebGL2RenderingContextOverloads
optional unsigned long long srcOffset = 0,
optional GLuint srcLengthOverride = 0);

undefined texElementImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
(Element or ElementImage) element,
optional WebGLCopyElementImageConfig config = {}); // May throw DOMException

undefined uniform1fv(WebGLUniformLocation? location, Float32List data, optional unsigned long long srcOffset = 0,
optional GLuint srcLength = 0);
undefined uniform2fv(WebGLUniformLocation? location, Float32List data, optional unsigned long long srcOffset = 0,
Expand Down Expand Up @@ -601,4 +614,3 @@ interface WebGL2RenderingContext
WebGL2RenderingContext includes WebGLRenderingContextBase;
WebGL2RenderingContext includes WebGL2RenderingContextBase;
WebGL2RenderingContext includes WebGL2RenderingContextOverloads;