WebGLTexture: Basic support for gl.texStorage2D().

[Mugen87]

Related issue: #21874

Description

Introduces the usage of the WebGL 2 API texStorage2D(). Only normal textures are supported right now (so no data, compressed or cube textures). Before rolling out it everywhere I thought we could do it an incremental fashion and thus easier spot potential issues.

The PR helps to mitigate #22758.

[Mugen87]

It seems the implementation has problems with video textures.

When starting rendering, video textures have a 0 width and height. These are no valid values for texStorage2D(). Chrome reports:

[.WebGL-0x7ffd0c04f600]GL ERROR :GL_INVALID_VALUE : glTexStorage2D: dimensions out of range

Since textures defined via texStorage2D() are immutable, it's not possible to resize the texture at a later point.

[Mugen87]

There is also issue when updating existing textures. texStorage2D() is only allowed to run once per texture. When setting Texture.needsUpdate o true multiple times, the engine is not allowed to call texStorage2D() again. Otherwise the following warning is reported:

[.WebGL-0x7ffd11025c00]GL ERROR :GL_INVALID_OPERATION : glTexStorage2D: texture is immutable

[toji]

Second commit with the fixes is more-or-less exactly what I would expect to see from an implementation of this feature. 👍

Does Three allow users to change a texture to an entirely different image after it's been created? As in: with different dimensions or format? If so then the way to handle that with texStorage is to simply delete the old GL texture handle when those mutable properties change and replace it with a new one. Sounds heavyweight, but it's essentially what texImage2D is doing behind the scenes when you reshape the texture.

[Mugen87]

Does Three allow users to change a texture to an entirely different image after it's been created?

Technically it's at least possible. In the following fiddle, the initial 1024x1024 texture image is replaced with a 256x256 image: https://jsfiddle.net/ufyrwt5m/

However, I'm not sure if we ever defined some sort of policy about this. E.g. with buffer attributes we have stated that it's not possible to replace or resize the internal array buffer after the creation. We could define something similar for textures.

If we state that certain properties like the image (or at least its dimensions) and other structural data like texture format or type are considered to be immutable after the textures creation (or initial use), it should be easier to adapt texStorage2D(). As a consequence, users would have to create a new instance of Texture if fundamental image properties change.

Personally, I would prefer such a policy since we could benefit from certain assumptions in the engine that makes it easier to implement optimized code like the usage of texStorage().

Besides, why would someone suddenly change the data type or format of a texture? It seems more natural to me to create a new texture object if I want to use a different image.

[toji]

Adopting a policy like that would definitely align better with the backend graphics APIs. With WebGPU, for example, all textures have immutable dimensions and formats. I'd encourage it!

[Mugen87]

@mrdoob @WestLangley @donmccurdy @sunag Would you be okay if we add the following statement (or something similar) to the Texture documentation?

After the initial use of a texture it's not possible to change its dimensions, format or type. Please create a new texture for these use cases and call dispose() on the previous one.

I would also add this note to the migration guide. Having this policy in place would make it easier to build the engine on top of WebGPU and texStorage2D() (WebGL 2).

[WestLangley]

Something like

Note: After the initial use of a texture, its dimensions, format, and type cannot be changed. Instead, call dispose() on the texture and instantiate a new one.

[donmccurdy]

Would you be okay if we add the following statement (or something similar) to the Texture documentation?

Would this affect the pattern below?

material.map = textureLoader.load('image.png');
render();

Presumably the texture will be 'rendered' a few times before the image is downloaded and assigned to the texture, is that OK? Note this also applies to compressed textures. Otherwise I think I'm fine with saying that a texture cannot be resized.

[Mugen87]

Presumably the texture will be 'rendered' a few times before the image is downloaded and assigned to the texture, is that OK?

Yes, that works. The PR does not affect this behavior.

WebGLTextures only uploads the texture when Texture.needsUpdate has been set at least once and thus the version is greater 0. The line below checks this requirement.

three.js/src/renderers/webgl/WebGLTextures.js

Line 341 in 8bf2f21

if ( texture.version > 0 && textureProperties.__version !== texture.version ) {

Only then uploadTexture() is executed which contains all the calls of texImage2D() or texStorage2D().

[mrdoob]

Thanks!

[Mugen87]

Before rolling out it everywhere I thought we could do it an incremental fashion and thus easier spot potential issues.

I suggest to expand the support of texStorage2D() with 136 to include other types of textures like data and cube textures.