Add internalFormat to Texture

[DavidPeicho]

• Adds internalFormat attribute to Texture Object;
• Adds internalFormat copy to Texture.copy();
• Adds internal formats to constants.js;
• Adds internal formats conversion to WebGLUtils;
• Adds singed / unsigned SAMPLER_3D, and SAMPLER_2D_ARRAY to WebGLUniforms

Sorry if sometimes the name are not consistant between each internal format. Just tell me what you like the most between R16FFormat and R16FloatFormat for instance, it is quite quick to change.

@takahirox sorry for the time I took for that. My own fork already had this feature, and my work was a priority.

[DavidPeicho]

This was a request made by @mrdoob, as you commented:

I do not think we need this method. I disagree with @mrdoob.

Whenever everyone will agree on this I can make the change, meaning deleting it if needed.

[DavidPeicho]

It has been a long time. I am going to fix the linting.
Regarding the setter, I am going to remove it and use the public attribute. If this causes trouble we can still talk about that in another PR as @WestLangley said.

[ixcviw7bw]

Many formats are still missing, for example R16UI. Here is a table showing all possible formats:

https://webgl2fundamentals.org/webgl/lessons/webgl-data-textures.html

It would be good to have them all.

[DavidPeicho]

Good point, the spec is a bit fuzzy on all the available formats / internal formats.
If you want to improve this PR that's even better, you just need to add them in src/constants.js and src/renderers/webgl/WebGLUtils.js.

[DavidPeicho]

Thanks @bilgorajskim for the thorough list of formats.

@Mugen87 @WestLangley Are you happy with it?

[ixcviw7bw]

I've opened another PR in your fork that fixes a few things that were still missing. @DavidPeicho

[mrdoob]

Considering that internalFormat is pretty much GL...

How about just doing:

texture.internalGLFormat = 'R8'

And make the code just do gl[ texture.internalGLFormat ]?

[DavidPeicho]

I would be really up for that, because it makes debugging so much easier. Though right now format and type are custom Three.js constants mapped to GL, so this doesn't "compliant" in with what has been made.

I am not too opinionated about that in general. In the same ideas of what you propose, what about

texture.gpuFormat

So it can match later with a WebGPU renderer?

[mrdoob]

Though right now format and type are custom Three.js constants mapped to GL, so this doesn't "compliant" in with what has been made.

That's okay.

I am not too opinionated about that in general. In the same ideas of what you propose, what about

texture.gpuFormat

So it can match later with a WebGPU renderer?

Sounds good to me 👍

[mrdoob]

@DavidPeicho do you think you can update the PR with that change? 😇

[DavidPeicho]

@mrdoob Yes I will change it. Do we still go through the mapping in WebGLUtils or do we use it like:

// User sets the internal format using the GL name.
texture.gpuFormat= 'R8'

// Renderer uploads the texture using:
var glInternalFormat = WebGL2RenderingContext[texture.gpuFormat]

[mrdoob]

Those two lines should be enough I think.

[GuDuJian-J-Zhang]

hope to merge soon

[DavidPeicho]

• Renamed internalFormat to gpuFormat. Includes:
  • Changing the attribute name in Texture.js
  • Modifying slightly the getInternalFormat() function in WebGLTextures.js to accommodate this change.
  • Updating docs to reflect the new name

I didn't change the current Three.js constant mapping to WebGL2 constants, but I kept it as-is, i.e:

myTexture.gpuFormat = THREE.R11F_G11F_B10FFormat; // THREE.R11F_G11F_B10FFormat = 1067
// 1067 is later mapped to WebGL2RenderingContext.R11F_G11F_B10F

For a simple reason, the WebGL2 Specification states that you can still use the RGB and RGBA formats as internal formats. So it means that a user will not be able to do:

myTexture.gpuFormat = THREE.RGBFormat;

Except if in WebGLTextures.js we hardcode something... which didn't seem great like that.

Otherwise we can also delete all constants for gpu format and simply use string, but WebGPU will anyway supports those kind of formats, so I guess it's actually better for Three.js to define it's own constants, and later perform the mapping for each GPU backend (like it's done right now with every constant).

Tell me what you think @mrdoob. If we keep the constants, maybe it could make sense to rename them a bit, I didn't think too much on that.

[mrdoob]

I didn't change the current Three.js constant mapping to WebGL2 constants, but I kept it as-is, i.e:

myTexture.gpuFormat = THREE.R11F_G11F_B10FFormat; // THREE.R11F_G11F_B10FFormat = 1067
// 1067 is later mapped to WebGL2RenderingContext.R11F_G11F_B10F

For a simple reason, the WebGL2 Specification states that you can still use the RGB and RGBA formats as internal formats. So it means that a user will not be able to do:

myTexture.gpuFormat = THREE.RGBFormat;

Then can't do myTexture.gpuFormat = 'RGB';?

What I'm proposing is to not add all these new constants and just pass a string to gpuFormat.

[DavidPeicho]

@mrdoob done.

• Updated gpuFormat to a string attribute, matching one of the internal format defined in the WebGL2 Specification.
• Added console.warn in WebGLTextures.js when the specified gpuFormat isn't found
• Removed every internal format constants from constants.js and WebGLUtils.js
• Updated docs to reflect the change from constants to string.
• Updated Texture.d.ts and constants.d.ts to reflect the string type

[DavidPeicho]

@mrdoob

• Renamed gpuFormat back to internalFormat in Texure.js, WebGLTextures.js
• Updated docs with internalFormat
• Updated Texture.d.ts with internalFormat as well

Do you want me to squash the commits?

[Mugen87]

Do you want me to squash the commits?

That would be great! 😇

[DavidPeicho]

Squashed the commits and rebased.

Just a note to @bilgorajskim, sorry your commits went away. The decision has been made to use directly the GL string as interalFormat anyway. Thanks a lot for the help you provided with all the constants!

[ixcviw7bw]

No problem :) The way it works now is simpler, and I agree with the decision.

[DavidPeicho]

@mrdoob

I pushed again a few changes to constants.js and to WebGLUtils.js. I forgot about that, but some GL internal formats require new GL formats as well. It's just 5 new constants. Unfortunately if we don't add them it makes some nice internal formats unavailable.

According to the spec,

• format RED_INTEGER is required to use internal format R8UI
• format RG is required to use internal formats RG*
• format RG_INTEGER is requried to use internal format RG8UI
• format RGB_INTEGER is requried to use internal format RGB8UI
• format RGBA_INTEGER is requried to use internal format RGBA8UI

[mrdoob]

Great! I'll do some additional clean up after merging but this looks great.

[mrdoob]

Thanks for being patient! 😇

[mrdoob]

@DavidPeicho a8cc32b

[WestLangley]

@DavidPeicho Awesome!

[rotu]

It seems like you can uniquely infer the format from an internalFormat (but not vice versa).

Any reason not to accept an internalFormat value in the Texture constructor instead of a base format?

[mrdoob]

Moving properties around in the constructor is a pain and the usage is messy.
Better to keep constructor properties to a minimum and modify the desired values after construction.