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 8 commits into
base: main
Choose a base branch
from
Open

add first prototype of texElementImage2D #3752

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 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
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
41 changes: 41 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.

@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.

width and height are destination parameters

Not quite if the command follows the texSubImage design.

There are several widths and heights here that exist in separate domains:

  1. Dimensions of the texture. These are set in advance by the developer (by calling regular texStorage or texImage commands) and not related to the Element API in any way.
  2. Dimensions and the offset of the Element's source rectangle. These affect Element rasterization and are not related to the texture.
  3. Target rasterization dimensions. These also only affect the rasterization and are not related to the texture (as it exists already).
  4. Texture's sub-region offset (xoffset and yoffset). These have nothing to do with the rasterization geometry and only exist within the texture dimensions set in 1.

@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.

I have in mind two reasons to prefer adding xoffset and yoffset to the config and leaving internalFormat where it is:

  • It places all geometry parameters in config, which I think is good ergonomics.

  • It doesn't break existing calling conventions if we allow xoffset and yoffset to default to zero when not specified.

In my mind, that's more compelling than keeping the GL-specific bits outside the config. The very fact that this function uses a dictionary of parameters already sets it apart from existing WebGL API's.

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

@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.

GLsizei height;
};
</pre>

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

undefined texElementImage2D(GLenum target, GLenum internalformat, (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 +2222,35 @@ <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, GLenum internalformat, (Element or ElementImage) element,
Comment thread
cabanier marked this conversation as resolved.
Outdated
optional WebGLCopyElementImageConfig config = {});
</dt>
<dd>
<p>Renders <code>element</code> to the currently bound <code>WebGLTexture</code> at level zero.</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 <code>WebGLBuffer</code> is bound to the <code>PIXEL_UNPACK_BUFFER</code> target, generates an <code>INVALID_OPERATION</code> error.</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 the generated texture size, in texels. If neither member is supplied, the texture 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>

@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.

Replace "they define the generated texture size" with "they specify the area of the texture to be modified; this will result in scaling of the source graphic if the specified size does not match the source element's intrinsic size."

<p>The <code>internalformat</code> argument 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>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 +2247 to +2248

@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>If <code>internalformat</code> is not listed in the table above, generates an <code>INVALID_ENUM</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, texture width, or texture height is not positive, generates an <code>INVALID_VALUE</code> error.</p>
<p>
If <a href="#PIXEL_STORE_PARAM_CONSTRAINTS">pixel store parameter constraints</a> are not met,
Comment thread
cabanier marked this conversation as resolved.
Outdated
generates an <code>INVALID_OPERATION</code> error.
</p>
</dd>
</dl>

<!-- ======================================================================================================= -->
Expand Down
13 changes: 12 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,9 @@ interface mixin WebGL2RenderingContextOverloads
optional unsigned long long srcOffset = 0,
optional GLuint srcLengthOverride = 0);

undefined texElementImage2D(GLenum target, GLenum internalformat, (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 +613,3 @@ interface WebGL2RenderingContext
WebGL2RenderingContext includes WebGLRenderingContextBase;
WebGL2RenderingContext includes WebGL2RenderingContextBase;
WebGL2RenderingContext includes WebGL2RenderingContextOverloads;