1. What Are They?
vModelUV (Model / Geometry UV Coordinates)
vModelUV- Origin: Defined by the 3D model’s geometry attributes (
uv) and passed from the vertex shader to the fragment shader via avaryingvariable (hence thevprefix). - Behavior: They are anchored directly to the surface of the 3D mesh. If your 3D cube rotates, scales, or moves across the screen, the
coordinates on its surface move right along with it. They always range fromvModelUV0.0to1.0across the individual face or unwrap of that specific geometry.
screenUV (Screen-Space / Viewport Coordinates)
screenUV- Origin: Calculated entirely in the fragment shader using the pixel’s absolute window position (
gl_FragCoord.xy) divided by the screen/canvas resolution (u_resolution.xy). - Behavior: They are anchored to the 2D viewport window (the canvas screen), completely independent of any 3D geometry. A pixel at the bottom-left corner of your canvas will always have an
ofscreenUV(0.0, 0.0), whether a 3D sphere is sitting there, rotating, or even if there is no mesh at all.
2. Key Differences at a Glance
| Feature | vModelUV (Geometry Space) | screenUV (Screen Space) |
| Source | Vertex Attribute (geometry.attributes.uv) | Fragment Pixel Position (gl_FragCoord) |
| Pipeline Stage | Interpolated from Vertex Shader $\rightarrow$ Fragment Shader | Calculated entirely inside the Fragment Shader |
| Object Dependency | Attached to the 3D mesh surface | Attached to the 2D screen / canvas viewport |
| Reaction to Camera/Rotation | Moves, rotates, and distorts with the 3D object | Stays locked to the screen like a glass overlay |
| Typical Range | 0.0 to 1.0 across the mesh UV unwrap | 0.0 to 1.0 across the screen width/height |
3. When to Use Which?
Pick vModelUV when:
- Mapping Textures: You want to wrap an image, logo, or normal map onto a 3D model (like a cube, plane, or custom GLTF character).
- Surface-Locked Patterns: You want procedural stripes, wood grain, or grid lines that deform, wrap, and rotate naturally along with the 3D object’s topology.
- UV-Based Displacements: You are animating vertex data or performing UV distortion effects localized to a specific mesh.
Pick st when:
- Screen-Space Post-Processing: You are writing full-screen fragment shaders (like screen ripples, vignette, chromatic aberration, or blur) applied to a full-screen quad.
- Viewport Gradients: You want a background gradient that fills the entire browser window or canvas regardless of what 3D objects are moving in front of it.
- Raymarching / Signed Distance Fields (SDFs): You are rendering procedural 2D shapes directly inside a flat quad on the screen.
4. What Should Be the Right Name for Them?
Naming variables clearly prevents massive confusion when working with both screen-space and geometry-space coordinates in the same shader file.
- Why the original names can be confusing: In Three.js,
vModelUVstandardizes the “varying UV” convention. Meanwhile, introductory shader tutorials (The Book of Shaders) popularized naming screen coordinatesstoruv. When mixed together, itβs easy to forget whetheruvbelongs to the mesh or the screen.
Recommended Naming Conventions:
- For Mesh Geometry Coordinates (
):vModelUV- Keep vmUV if working within standard Three.js boilerplates, or rename for clarity:
vModelUVorvGeometryUV(makes it instantly obvious that these belong to the 3D object’s surface mapping).
- For Screen / Viewport Coordinates (
):screenUVscreenUVorfragCoordNormalized(clearly communicates that these represent absolute window/pixel coordinates normalized from0.0to1.0).
Cleaned-Up Example:
OpenGL Shading Language