API Reference

Package entrypoints

Entrypoint	Use it for
threejs-debug-view	Native runtime: view definitions, render planning, TSL compositor, WebGPU helpers, and public types.
threejs-debug-view/r3f	Optional R3F adapter: DebugViewLayer, DebugViews, bundled Leva shell, and useDebugViewsControls().

See R3F for what ships on npm versus the repo demo and docs site.

Native runtime

Import from threejs-debug-view when your app owns the WebGPU render loop. Full walkthrough: Native Runtime.

API	Use when
createDebugPipelineRuntime()	Single compositor output (overlay, breakdown, grid, etc.)
createDebugViewportRenderer()	Panes need different resolutionScale or per-pane cameras
requiresViewportRuntime()	Choosing between the two paths after createDebugViewportPlan()

createDebugViewportRenderer() options:

Option	Default	Notes
overlayOpacity	1	Per-pane opacity. Viewport cells are opaque single-view passes, not compositor overlay blends.
dividerStyle	—	Forwarded to uniforms only; TSL dividers are not drawn between scissor panes.

Pane rects are cached when the viewport renderer is constructed. Rebuild when the plan changes.

Planning and uniforms

• resolveDebugViewLayout() — normalize layout presets into rows, columns, and slots
• createDebugRenderPlan() — pass and pipeline view selection for a layout
• createDebugPipelineRuntimeKey() — stable rebuild key for runtime caches
• createDebugViewportPlan() / createDebugViewportRenderGraphPlan() — multi-pane viewport graphs
• createDebugViewUniforms() / updateDebugViewUniforms() — TSL uniform state
• createDebugViewportLabels() / createDebugViewportRects() — viewport presentation helpers
• readHeatmapCostFromCanvas() — shader-cost pixel sampling

Controls (native)

The root export includes layout/pane helpers and the DebugViewsOptions type for custom native UI:

• DebugViewsOptions, DebugViewsControlValues
• createPaneAssignmentsKey(), createViewportViews(), getVisiblePaneCount(), getVisiblePaneCountForLayout()
• isPaneAssignmentLayout(), usesPaneAssignments()

R3F components

Import from threejs-debug-view/r3f.

DebugViewLayer

Optional R3F adapter layer with default views and Leva controls.

<DebugViewLayer />

Use DebugViews when your app owns controls, layout state, custom views, or viewport assignments.

DebugViewLayer mounts Leva on document.body by default. Set showLeva={false} when mounting DebugViewLeva elsewhere.

Prop	Purpose
views	Optional custom view list. Defaults to DEFAULT_DEBUG_VIEWS.
viewLabels	Optional labels passed to the bundled Leva controls.
maxPaneCount	Upper bound for panes, rows, and columns in the controls.
showEnabledControl	Shows the Leva Enabled toggle. Defaults to true. The demo sets this to false.
showLeva	Mounts the bundled Leva panel on document.body. Defaults to true.
showLabels	Overrides the Leva viewport-label toggle.
showLegends	Overrides the Leva diagnostic-legend toggle.
layout	Overrides the Leva layout preset (for example breakdown).
diagonalAngle	Overrides the Leva diagonal angle for split-diagonal and breakdown.
viewportViews	Overrides Leva pane assignments with fixed DebugViewportView entries.

DebugViewLeva

Bundled Leva panel for debug view controls. Mount it yourself when the panel should live in a specific place in your app shell while sharing the same Leva store as useDebugViewsControls.

DebugViews

R3F component for presenting debug views inside a <Canvas>.

Prop	Purpose
views	Registered debug views.
activeView	Selected view index for single/overlay flows.
layout	Layout preset or layout config.
paneCount	Number of visible panes for row, column, and grid layouts.
diagonalAngle	Angle in degrees for split-diagonal and breakdown. breakdown defaults to 25 degrees.
maxDiagonalAngle	Optional override for the default 45 degree diagonal angle clamp.
viewportViews	Explicit pane assignments for fixed views, labels, cameras, or resolution scale.
showLabels	Renders DOM labels over panes (for example Shader Complexity, Normal).
showLegends	Shows bottom diagnostic ramps (shader cost, overlap). Defaults to true.
viewportLabels	Label overrides or formatter.
overlayOpacity	Blend amount for overlay mode.
lineWidth	Divider hairline thickness in normalized screen space (default thin).
edgeColor	Silver rim at divider edges as RGB [0–1, 0–1, 0–1].
coreColor	Center fill inside dividers as RGB [0–1, 0–1, 0–1].

layout decides the arrangement, paneCount decides how many panes are visible, and viewportViews decides what each explicit pane renders. Simple pane assignments use the compositor path; per-pane cameras and resolutionScale use the viewport/scissor path.

useDebugViewsControls()

Returns Leva-backed control state to spread onto DebugViews. See Quick Start — bring your own controls.

Also exported from /r3f: mountDebugViewLeva, DEBUG_VIEW_LEVA_THEME.

Types

DebugView

interface DebugView {
  id?: string
  label: string
  node?: DebugNode
  mode?: "passthrough" | "normal" | "depth" | "heatmap"
  source?: DebugViewSource
  scale?: number
  bias?: number
}

DebugViewportView

interface DebugViewportView {
  view: number | DebugViewSource | DebugView
  label?: string
  camera?: Camera
  resolutionScale?: number
}

resolutionScale is normalized to 1, 0.5, or 0.25.

Built-in sources

Built-in DebugViewSource values:

Source	Notes
beauty	Final scene color.
normal	View-space geometry normals.
depth	View-space depth visualization.
albedo / baseColor	Base color without lighting.
materialNormal / normalMap	Material-perturbed normals.
emissive	Material emissive contribution.
roughness	Packed material scalar, defaults to 1 when unsupported.
ao	Packed material AO, defaults to 1 when unsupported.
metallic / metalness	Packed material scalar, defaults to 0 when unsupported.
opacity / transparency	Packed alpha scalar.
wireframe	Override-material pass.
lightingOnly	Neutral lighting override pass.
reflectionOnly	Reflective override pass.
overdraw	Measured overlap heatmap (contributor layer count). Click the viewport to sample integer layers from the pass buffer.
overdrawVisual	Additive overlap visualization (approx).
lightComplexity	Light overlap heatmap (v1 analytic point/spot/rect counter; globals excluded).
shaderCost	Shader-complexity heatmap from shader-unit buckets. Click the viewport in DebugViewLayer to sample a pixel; the legend shows shader complexity when idle.

shaderCost is not a native GPU instruction counter. Render-pass timing and overlap diagnostics are separate signals, not ALU/TEX/occupancy data.

Custom views

Use createCustomDebugView() when a custom TSL node may be recreated by React but should keep a stable logical identity:

const fresnel = createCustomDebugView({
  id: "shader:fresnel",
  label: "Fresnel",
  node: fresnelNode,
  mode: "passthrough",
})

The compositor runtime rebuilds when a custom node instance changes. The viewport render graph uses id in stable pass keys.

Helper index

• DEFAULT_DEBUG_VIEWS, getDebugViewLabels()
• createCustomDebugView()
• createDebugRenderPlan()
• createDebugPipelineRuntime()
• createDebugViewportRenderer()
• createDebugViewportPlan()
• createDebugViewportRenderGraphPlan()
• requiresViewportRuntime()