Built-in Views

The built-in views are the default diagnostics exported by DEFAULT_DEBUG_VIEWS from the root package. Each view is a small render source: the UI chooses a view, the render plan resolves only the required passes, and the compositor presents the result.

Examples below show both the native runtime and the optional R3F adapter; the same DEFAULT_DEBUG_VIEWS list works in either path — see Native Runtime.

Try them in the homepage demo.

Scene buffers

Source	Mode	Output	Use it to check
beauty	passthrough	Final scene color.	Baseline rendering.
normal	passthrough	View-space geometry normals.	Model orientation, hard edges, and geometry normals.
depth	depth	Pass depth converted to view-space distance.	Camera depth, clipping, and depth precision.

Material buffers

Source	Mode	Output	Use it to check
albedo / baseColor	passthrough	Base color without lighting.	Texture color and material authoring.
materialNormal / normalMap	passthrough	Material-perturbed normal output.	Normal maps and tangent-space detail.
emissive	passthrough	Material emissive color.	Emissive contribution independent of lighting.

Packed scalar buffers

Source	Channel	Output	Use it to check
roughness	R	Packed roughness scalar.	Overly glossy or rough materials.
metallic / metalness	G	Packed metallic scalar.	Metalness maps and PBR setup.
ao	B	Packed ambient occlusion scalar.	AO map contribution.
opacity / transparency	A	Packed opacity or inverse opacity.	Transparent or cutout surfaces.

Scalar material data is packed into one RGBA target instead of allocating one render target per scalar view. That keeps the composer under common WebGPU color attachment limits.

Unsupported material properties use shader-side defaults instead of temporary material mutation:

• roughness defaults to 1
• metallic defaults to 0
• AO defaults to 1, meaning no material AO contribution
• opacity defaults to 1

ao reads material-authored AO maps. It is not a screen-space AO buffer unless your app exposes one through a custom view or a dedicated pass.

Override passes

Source	Mode	Output	Cost model
wireframe	passthrough	White wireframe override material.	Renders only when selected or visible in a layout.
lightingOnly	passthrough	Neutral non-metal material override.	Renders only when selected or visible in a layout.
reflectionOnly	passthrough	Reflective neutral material override.	Renders only when selected or visible in a layout.
overdraw	heatmap	Measured contributor layer count (depth prepass + blend counter). Legend: 0 / 1 / 4 / 8+ layers. Click to sample integer layers from the pass buffer.	Renders only when selected or visible in a layout.
overdrawVisual	heatmap	Optional additive overlap visualization (approx). Not in DEFAULT_DEBUG_VIEWS.	Renders only when selected or visible in a layout.
lightComplexity	heatmap	Light Overlap — analytic dynamic light count (point/spot/rect). v1: no shadows, no cluster culling parity. Legend Low → High.	Renders only when selected or visible in a layout.
shaderCost	heatmap	Shader-cost heatmap from source-labeled shader-unit buckets.	Renders only when selected or visible in a layout.

Demand-driven override passes add another scene render only when the selected layout or viewport plan actually needs that source.

See Performance Model for how single-view switching reuses compatible runtime pipelines.

Caution

shaderCost is a shader-cost estimate, not a browser-exposed shader instruction counter. Keep pass timing and overlap diagnostics separate from this view so the UI does not imply native ALU/TEX/occupancy data. Overlap and shader cost each render their own legend when both panes are visible.

Native example

import {
  DEFAULT_DEBUG_VIEWS,
  createDebugRenderPlan,
  createDebugPipelineRuntime,
  createDebugViewUniforms,
  resolveDebugViewLayout,
  updateDebugViewUniforms,
} from "threejs-debug-view"

const views = DEFAULT_DEBUG_VIEWS
const layout = resolveDebugViewLayout("quad")
const plan = createDebugRenderPlan(views, 0, layout)
const uniforms = createDebugViewUniforms()

const runtime = createDebugPipelineRuntime(scene, camera, plan, layout, renderer, uniforms)

function animate() {
  updateDebugViewUniforms(uniforms, plan.activePipelineView, layout, plan.pipelineViews.length, 4)
  runtime.pipeline.render()
  requestAnimationFrame(animate)
}

R3F composed example

import { DEFAULT_DEBUG_VIEWS } from "threejs-debug-view"
import { DebugViews } from "threejs-debug-view/r3f"

<DebugViews
  views={DEFAULT_DEBUG_VIEWS}
  activeView={0}
  layout="quad"
  paneCount={4}
  showLabels
/>

R3F explicit pane example

Use explicit pane assignments when panes must keep fixed views.

<DebugViews
  views={DEFAULT_DEBUG_VIEWS}
  viewportViews={[
    { view: "beauty", label: "Beauty" },
    { view: "normal", label: "Normals" },
    { view: "roughness", label: "Roughness", resolutionScale: 0.5 },
    { view: "shaderCost", label: "Shader Complexity", resolutionScale: 0.5 },
  ]}
  layout="quad"
  paneCount={4}
  showLabels
/>