Three.js Blocks

Home
Documentation
Examples
Tools

biplanarTexture

@three-blocks/coreWebGPUWebGL
biplanarTexture(textureXNode : Node, textureYNode : Node, textureZNode : Node, scaleNode : Node<float>, positionNode : Node<vec3>, normalNode : Node<vec3>, hardnessNode : Node<float>) : Node<vec4>

Efficient biplanar texture mapping for world-space triplanar-style effects. Samples only the two most dominant axis projections and blends them, reducing texture fetches compared to full triplanar mapping.

Algorithm

  • Determines the two dominant axes based on surface normal
  • Projects position onto corresponding planes (XY, YZ, ZX)
  • Samples textures with proper derivatives for mipmapping
  • Blends samples using weighted power curve for smooth transitions

Benefits

  • 33% fewer texture samples than triplanar (2 vs 3)
  • Avoids visible seams on axis-aligned surfaces
  • Supports per-axis texture variation
  • Automatic mipmap derivatives via grad()
Parameters
textureXNodeNode
Texture sampled on YZ plane (X-axis projection).
textureYNodeoptionalNode
Texture sampled on ZX plane (Y-axis projection).
Default is textureXNode.
textureZNodeoptionalNode
Texture sampled on XY plane (Z-axis projection).
Default is textureXNode.
scaleNodeoptionalNode<float>
UV coordinate scale multiplier.
Default is 1.
positionNodeoptionalNode<vec3>
Fragment position for UV projection.
Default is positionLocal.
normalNodeoptionalNode<vec3>
Surface normal for axis weight calculation.
Default is normalLocal.
hardnessNodeoptionalNode<float>
Blend sharpness (higher = sharper transitions).
Default is 8.
Returns
Node<vec4> — Blended texture color (RGBA).
Example
import { biplanarTexture } from '@three-blocks/core';
import { texture, float } from 'three/tsl';

const diffuseTex = texture(diffuseMap);
const normalTex = texture(normalMap);

// Same texture on all axes with 2x tiling
material.colorNode = biplanarTexture(diffuseTex, null, null, float(2));

// Different textures per axis
material.colorNode = biplanarTexture(
  texture(texX),  // YZ plane
  texture(texY),  // ZX plane
  texture(texZ),  // XY plane
  float(1),       // scale
  positionLocal,  // position
  normalLocal,    // normal
  float(8)        // blend hardness
);