3D Retina Resolution

3D Retina Resolution

Treat an explicit 200% rendering request as two drawing-buffer pixels per CSS pixel in each dimension. A 1200 × 800 CSS canvas therefore uses a 2400 × 1600 drawing buffer, or four times the pixels of 100%. Layout and camera framing stay unchanged.

Choose the scale deliberately

• Fixed 200%: effective pixel ratio is 2, independent of device pixel ratio. This is the default when the user explicitly requests 200%.
• Automatic Retina, capped at 2×: effective ratio is Math.min(window.devicePixelRatio || 1, 2). This can render at 1× on an ordinary display; label it Auto rather than claiming it always renders at 200%.
• Relative to native resolution: multiply native DPR only when the user explicitly wants that meaning. Native 2× multiplied by another 2 becomes 4× per dimension, or sixteen times the CSS pixel count.

Keep an explicit quality selection distinct from automatic adaptation. Inspect the project's renderer and post-processing architecture before changing sizing.

Synchronize the rendering pipeline

Use CSS to size the canvas and its container, then measure the container in CSS pixels. In Three.js WebGL, one consistent convention is logical sizes plus pixel ratio:

function resize3D(width, height, ratio = 2) {
  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return;
  if (!Number.isFinite(ratio) || ratio <= 0) throw new RangeError('Invalid render ratio');
  renderer.setPixelRatio(ratio);
  renderer.setSize(width, height, false); // CSS owns displayed dimensions
  camera.aspect = width / height;        // perspective camera
  camera.updateProjectionMatrix();
  if (composer) {
    composer.setPixelRatio(ratio);
    composer.setSize(width, height);     // logical pixels; do not multiply again
  }
  const physicalWidth = renderer.domElement.width;
  const physicalHeight = renderer.domElement.height;
  resizeCustomTargets(physicalWidth, physicalHeight);
}

The snippet assumes an existing renderer, perspective camera, optional composer (or null), and a resizeCustomTargets adapter supplied by the app. For an orthographic camera, update its bounds according to the existing framing policy instead of setting aspect.

The adapter updates only app-owned targets and uniforms; composer-managed passes already receive sizing through the composer. Set full-resolution depth/normal targets to physical dimensions. Size lower-resolution AO, bloom, or ray targets by their deliberate scale factors. Set sampling-resolution uniforms to the dimensions of the texture actually sampled, including reciprocal resolution where the shader expects it.

The renderer and composer each maintain their own pixel ratio. Updating only the canvas can leave a lower-resolution intermediate image stretched to a Retina output. Conversely, passing already doubled dimensions into a composer that also has DPR 2 allocates 4× dimensions. See the renderer and composer sizing APIs.

Handle layout and display changes

Observe the canvas container with ResizeObserver, coalesce notifications, and resize only when dimensions or effective ratio change. Skip zero-sized hidden views and retry when they become visible. Re-evaluate native DPR on browser zoom or display changes in Auto mode, including when CSS dimensions remain unchanged. Recreate a resolution media-query listener after each DPR change if using that approach.

Use canvas.getBoundingClientRect() for pointer normalization: (clientX - rect.left) / rect.width, and likewise for Y. Raycasting uses normalized coordinates derived from CSS space, not drawing-buffer pixels. Convert to physical pixels separately only for APIs such as a pixel readback.

Retina output does not automatically improve a blurry texture, coarse model, shadow map, or low-resolution reflection. Check those sources independently. Avoid CSS scaling or image-rendering: pixelated as a substitute for the correct drawing buffer. Higher resolution and antialiasing solve related but different artifacts.