TSL: Add texture offset feature

[shotamatsuda]

Related issue: None

Description

This PR adds offsetNode to TextureNode and Texture3DNode for the texel offset applied to the unnormalized texture coordinate before sampling the texture.

In the WebGLBackend, a texture sample with an offset should be transpiled to the corresponding built-in functions, but in the WebGPUBackend, the built-in functions corresponding to the following do not have an offset parameter, thus they behave differently than built-in functions (i.e. works without upper/lower limits on the offset).

• load()
• sample(), level() on unfilterable textures

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	338.91 79.1	338.91 79.1	+0 B +0 B
WebGPU	577.16 159.18	578.64 159.46	+1.48 kB +273 B
WebGPU Nodes	575.77 158.94	577.25 159.21	+1.48 kB +273 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

	Before	After	Diff
WebGL	470.7 113.91	470.7 113.91	+0 B +0 B
WebGPU	647.72 175.15	649.2 175.43	+1.48 kB +284 B
WebGPU Nodes	601.82 164.31	603.3 164.59	+1.48 kB +279 B

[shotamatsuda]

This part and another similar one in generateFilteredTexture are a bit odd, but they are implemented this way because the wrap function expects normalized texture coordinates.

[Mugen87]

There is already the possibility to define offset for textures:

three.js/src/textures/Texture.js

Lines 191 to 198 in f78867d

	/**
	* How much a single repetition of the texture is offset from the beginning,
	* in each direction U and V. Typical range is `0.0` to `1.0`.
	*
	* @type {Vector2}
	* @default (0,0)
	*/
	this.offset = new Vector2( 0, 0 );

Is offsetNode now an alternative way to define texture offset?

What would happen if you use offsetNode with a texture that has already defined an offset?

[shotamatsuda]

If I'm correct, that offset is for repeating, but the offset node on TextureNode is for sampling offset (i.e. sampling a UV with an offset of the unnormalized texture coordinate, just as we do with textureOffset() in GLSL).

[shotamatsuda]

Answering your question, both offsets are applied. One is in the UV space with a wrap function, and the other is applied at sampling time after wrapping.

A typical use case of the sampling offset is convolution or neighbor texel lookup, and Texture's offset is not appropriate for it.

[Mugen87]

For the sake of completeness, Texture.offset can be used without repeating: https://jsfiddle.net/ycan6evL/

But I understand there is a distinction between offsetting texture coordinates and use cases where textureOffset() is used. I have just never used this GLSL function and wanted to understand from a user perspective how to use offsetNode.

So the unit of offsetNode is texels (integers), right?

[shotamatsuda]

I should have said wrapS, wrapT, and wrapR. If they are not set to repeating, textures aren't repeating of course.

Yes, offsetNode is in signed integers, as written in the JSDoc. Both GLSL and WGSL have well-defined dedicated functions or overloads.