Difference Between Object Space and Screen Space UV

1. What Are They?

vModelUV (Model / Geometry UV Coordinates)

  • Origin: Defined by the 3D model’s geometry attributes (uv) and passed from the vertex shader to the fragment shader via a varying variable (hence the v prefix).
  • Behavior: They are anchored directly to the surface of the 3D mesh. If your 3D cube rotates, scales, or moves across the screen, the vModelUV coordinates on its surface move right along with it. They always range from 0.0 to 1.0 across the individual face or unwrap of that specific geometry.

screenUV (Screen-Space / Viewport Coordinates)

  • 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 screenUV of (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

FeaturevModelUV (Geometry Space)screenUV (Screen Space)
SourceVertex Attribute (geometry.attributes.uv)Fragment Pixel Position (gl_FragCoord)
Pipeline StageInterpolated from Vertex Shader $\rightarrow$ Fragment ShaderCalculated entirely inside the Fragment Shader
Object DependencyAttached to the 3D mesh surfaceAttached to the 2D screen / canvas viewport
Reaction to Camera/RotationMoves, rotates, and distorts with the 3D objectStays locked to the screen like a glass overlay
Typical Range0.0 to 1.0 across the mesh UV unwrap0.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, vModelUV standardizes the “varying UV” convention. Meanwhile, introductory shader tutorials (The Book of Shaders) popularized naming screen coordinates st or uv. When mixed together, it’s easy to forget whether uv belongs to the mesh or the screen.

Recommended Naming Conventions:

  1. For Mesh Geometry Coordinates (vModelUV):
    • Keep vmUV if working within standard Three.js boilerplates, or rename for clarity:
    • vModelUV or vGeometryUV (makes it instantly obvious that these belong to the 3D object’s surface mapping).
  2. For Screen / Viewport Coordinates (screenUV):
    • screenUV or fragCoordNormalized (clearly communicates that these represent absolute window/pixel coordinates normalized from 0.0 to 1.0).

Cleaned-Up Example:

OpenGL Shading Language