r3f-performance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

R3F Performance

R3F性能优化

Optimize render performance through draw call reduction, geometry optimization, smart loading, and profiling.

通过减少绘制调用、几何优化、智能加载和性能分析来优化渲染性能。

Quick Start

快速开始

tsx

// Performance-optimized Canvas
<Canvas
  dpr={[1, 2]}                    // Limit pixel ratio
  performance={{ min: 0.5 }}      // Adaptive performance
  frameloop="demand"              // Only render on change
  gl={{ 
    powerPreference: 'high-performance',
    antialias: false              // Disable for mobile
  }}
>
  <Suspense fallback={null}>
    <Scene />
  </Suspense>
</Canvas>

tsx

// 性能优化后的Canvas
<Canvas
  dpr={[1, 2]}                    // 限制像素比
  performance={{ min: 0.5 }}      // 自适应性能
  frameloop="demand"              // 仅在变化时渲染
  gl={{ 
    powerPreference: 'high-performance',
    antialias: false              // 移动端禁用
  }}
>
  <Suspense fallback={null}>
    <Scene />
  </Suspense>
</Canvas>

Frame Budget

帧预算

Target 60fps = 16.67ms per frame. Budget breakdown:

Phase	Target	Notes
JavaScript	< 4ms	useFrame logic, state updates
GPU Render	< 10ms	Draw calls, shaders
Compositing	< 2ms	Post-processing, overlays
Buffer	~1ms	Safety margin

目标60fps = 每帧16.67ms。预算细分：

阶段	目标	说明
JavaScript	< 4ms	useFrame逻辑、状态更新
GPU渲染	< 10ms	绘制调用、着色器
合成	< 2ms	后期处理、叠加层
缓冲	~1ms	安全余量

Draw Call Optimization

绘制调用优化

The Golden Rule

黄金法则

Fewer draw calls > fewer triangles

A scene with 100 meshes of 1000 triangles each is slower than 1 mesh of 100,000 triangles.

更少的绘制调用 > 更少的三角形

一个包含100个各有1000个三角形的网格场景，比1个包含100,000个三角形的网格场景更慢。

Reduction Techniques

优化技巧

Technique	Draw Calls	When to Use
Instancing	1 per unique mesh	100+ identical objects
Merged geometry	1 per merged batch	Static scene parts
Texture atlases	Fewer materials	Many similar textures
LOD	Reduces complexity	Large/distant objects

技巧	绘制调用数	使用场景
实例化	每个唯一网格1次	100+个相同对象
合并几何	每个合并批次1次	静态场景部分
纹理图集	减少材质数量	大量相似纹理
LOD	降低复杂度	大型/远距离对象

Instancing (Best for Identical Meshes)

实例化（最适合相同网格）

tsx

// 10,000 cubes = 1 draw call
<instancedMesh args={[undefined, undefined, 10000]}>
  <boxGeometry />
  <meshStandardMaterial />
</instancedMesh>

tsx

// 10,000个立方体 = 1次绘制调用
<instancedMesh args={[undefined, undefined, 10000]}>
  <boxGeometry />
  <meshStandardMaterial />
</instancedMesh>

Geometry Merging (Static Scenes)

几何合并（静态场景）

tsx

import { useMemo } from 'react';
import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils';
import * as THREE from 'three';

function MergedScene() {
  const mergedGeometry = useMemo(() => {
    const geometries: THREE.BufferGeometry[] = [];
    
    // Create many positioned geometries
    for (let i = 0; i < 100; i++) {
      const geo = new THREE.BoxGeometry(1, 1, 1);
      geo.translate(
        (Math.random() - 0.5) * 20,
        (Math.random() - 0.5) * 20,
        (Math.random() - 0.5) * 20
      );
      geometries.push(geo);
    }
    
    return mergeGeometries(geometries);
  }, []);
  
  return (
    <mesh geometry={mergedGeometry}>
      <meshStandardMaterial />
    </mesh>
  );
}

tsx

import { useMemo } from 'react';
import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils';
import * as THREE from 'three';

function MergedScene() {
  const mergedGeometry = useMemo(() => {
    const geometries: THREE.BufferGeometry[] = [];
    
    // 创建多个带位置的几何
    for (let i = 0; i < 100; i++) {
      const geo = new THREE.BoxGeometry(1, 1, 1);
      geo.translate(
        (Math.random() - 0.5) * 20,
        (Math.random() - 0.5) * 20,
        (Math.random() - 0.5) * 20
      );
      geometries.push(geo);
    }
    
    return mergeGeometries(geometries);
  }, []);
  
  return (
    <mesh geometry={mergedGeometry}>
      <meshStandardMaterial />
    </mesh>
  );
}

Level of Detail (LOD)

细节层次（LOD）

Swap geometry based on camera distance:

tsx

import { useMemo } from 'react';
import * as THREE from 'three';

function LODMesh() {
  const lod = useMemo(() => {
    const lodObject = new THREE.LOD();
    
    // High detail (close)
    const highGeo = new THREE.SphereGeometry(1, 64, 64);
    const highMesh = new THREE.Mesh(highGeo, new THREE.MeshStandardMaterial({ color: 'red' }));
    lodObject.addLevel(highMesh, 0);
    
    // Medium detail
    const medGeo = new THREE.SphereGeometry(1, 32, 32);
    const medMesh = new THREE.Mesh(medGeo, new THREE.MeshStandardMaterial({ color: 'orange' }));
    lodObject.addLevel(medMesh, 10);
    
    // Low detail (far)
    const lowGeo = new THREE.SphereGeometry(1, 8, 8);
    const lowMesh = new THREE.Mesh(lowGeo, new THREE.MeshStandardMaterial({ color: 'green' }));
    lodObject.addLevel(lowMesh, 30);
    
    return lodObject;
  }, []);
  
  return <primitive object={lod} />;
}

根据相机距离切换几何：

tsx

import { useMemo } from 'react';
import * as THREE from 'three';

function LODMesh() {
  const lod = useMemo(() => {
    const lodObject = new THREE.LOD();
    
    // 高细节（近距离）
    const highGeo = new THREE.SphereGeometry(1, 64, 64);
    const highMesh = new THREE.Mesh(highGeo, new THREE.MeshStandardMaterial({ color: 'red' }));
    lodObject.addLevel(highMesh, 0);
    
    // 中等细节
    const medGeo = new THREE.SphereGeometry(1, 32, 32);
    const medMesh = new THREE.Mesh(medGeo, new THREE.MeshStandardMaterial({ color: 'orange' }));
    lodObject.addLevel(medMesh, 10);
    
    // 低细节（远距离）
    const lowGeo = new THREE.SphereGeometry(1, 8, 8);
    const lowMesh = new THREE.Mesh(lowGeo, new THREE.MeshStandardMaterial({ color: 'green' }));
    lodObject.addLevel(lowMesh, 30);
    
    return lodObject;
  }, []);
  
  return <primitive object={lod} />;
}

Drei LOD Helper

Drei LOD辅助工具

tsx

import { Detailed } from '@react-three/drei';

function AdaptiveSphere() {
  return (
    <Detailed distances={[0, 10, 30]}>
      {/* Close: high detail */}
      <mesh>
        <sphereGeometry args={[1, 64, 64]} />
        <meshStandardMaterial />
      </mesh>
      
      {/* Medium distance */}
      <mesh>
        <sphereGeometry args={[1, 32, 32]} />
        <meshStandardMaterial />
      </mesh>
      
      {/* Far: low detail */}
      <mesh>
        <sphereGeometry args={[1, 8, 8]} />
        <meshStandardMaterial />
      </mesh>
    </Detailed>
  );
}

tsx

import { Detailed } from '@react-three/drei';

function AdaptiveSphere() {
  return (
    <Detailed distances={[0, 10, 30]}>
      {/* 近距离：高细节 */}
      <mesh>
        <sphereGeometry args={[1, 64, 64]} />
        <meshStandardMaterial />
      </mesh>
      
      {/* 中等距离 */}
      <mesh>
        <sphereGeometry args={[1, 32, 32]} />
        <meshStandardMaterial />
      </mesh>
      
      {/* 远距离：低细节 */}
      <mesh>
        <sphereGeometry args={[1, 8, 8]} />
        <meshStandardMaterial />
      </mesh>
    </Detailed>
  );
}

Frustum Culling

视锥体剔除

Objects outside camera view are not rendered. Enabled by default, but:

tsx

// Disable for objects that animate into view unpredictably
<mesh frustumCulled={false}>
  <boxGeometry />
  <meshStandardMaterial />
</mesh>

// Force bounding sphere update for dynamic geometry
useEffect(() => {
  geometry.computeBoundingSphere();
}, [geometry]);

相机视野外的对象不会被渲染。默认启用，但：

tsx

// 对不可预测进入视野的对象禁用
<mesh frustumCulled={false}>
  <boxGeometry />
  <meshStandardMaterial />
</mesh>

// 为动态几何强制更新包围球
useEffect(() => {
  geometry.computeBoundingSphere();
}, [geometry]);

Adaptive Performance

自适应性能

R3F's adaptive performance system automatically adjusts DPR:

tsx

<Canvas
  performance={{
    min: 0.5,     // Minimum DPR under stress
    max: 1,       // Maximum DPR
    debounce: 200 // Debounce time for changes (ms)
  }}
/>

R3F的自适应性能系统会自动调整DPR：

tsx

<Canvas
  performance={{
    min: 0.5,     // 高负载下的最小DPR
    max: 1,       // 最大DPR
    debounce: 200 // 变化的防抖时间（毫秒）
  }}
/>

Manual Performance Control

手动性能控制

tsx

import { useThree } from '@react-three/fiber';

function PerformanceMonitor() {
  const { performance } = useThree();
  
  useFrame(() => {
    // Check current performance
    if (performance.current < 1) {
      // System is under stress, reduce complexity
    }
  });
  
  // Trigger performance drop
  const triggerRegress = () => {
    performance.regress();  // Temporarily lower DPR
  };
}

tsx

import { useThree } from '@react-three/fiber';

function PerformanceMonitor() {
  const { performance } = useThree();
  
  useFrame(() => {
    // 检查当前性能
    if (performance.current < 1) {
      // 系统处于高负载，降低复杂度
    }
  });
  
  // 触发性能降级
  const triggerRegress = () => {
    performance.regress();  // 临时降低DPR
  };
}

Lazy Loading

懒加载

Code Splitting with Suspense

使用Suspense进行代码分割

tsx

import { Suspense, lazy } from 'react';

const HeavyModel = lazy(() => import('./HeavyModel'));

function Scene() {
  return (
    <Suspense fallback={<SimpleLoader />}>
      <HeavyModel />
    </Suspense>
  );
}

tsx

import { Suspense, lazy } from 'react';

const HeavyModel = lazy(() => import('./HeavyModel'));

function Scene() {
  return (
    <Suspense fallback={<SimpleLoader />}>
      <HeavyModel />
    </Suspense>
  );
}

Progressive Loading

渐进式加载

tsx

import { useGLTF } from '@react-three/drei';

function Model() {
  // Preload in background
  useGLTF.preload('/model.glb');
  
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

// Preload before component mounts
useEffect(() => {
  useGLTF.preload('/next-model.glb');
}, []);

tsx

import { useGLTF } from '@react-three/drei';

function Model() {
  // 在后台预加载
  useGLTF.preload('/model.glb');
  
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

// 在组件挂载前预加载
useEffect(() => {
  useGLTF.preload('/next-model.glb');
}, []);

View-Based Loading

基于视图的加载

tsx

import { useInView } from 'react-intersection-observer';

function LazySection() {
  const { ref, inView } = useInView({
    triggerOnce: true,
    rootMargin: '200px'  // Start loading 200px before visible
  });
  
  return (
    <group ref={ref}>
      {inView && <HeavyContent />}
    </group>
  );
}

tsx

import { useInView } from 'react-intersection-observer';

function LazySection() {
  const { ref, inView } = useInView({
    triggerOnce: true,
    rootMargin: '200px'  // 可见前200px开始加载
  });
  
  return (
    <group ref={ref}>
      {inView && <HeavyContent />}
    </group>
  );
}

Memory Management

内存管理

Dispose Unused Resources

释放未使用资源

tsx

// Manual disposal
useEffect(() => {
  return () => {
    geometry.dispose();
    material.dispose();
    texture.dispose();
  };
}, []);

// Drei helper for GLTF
import { useGLTF } from '@react-three/drei';

useEffect(() => {
  return () => {
    useGLTF.clear('/model.glb');
  };
}, []);

tsx

// 手动释放
useEffect(() => {
  return () => {
    geometry.dispose();
    material.dispose();
    texture.dispose();
  };
}, []);

// Drei的GLTF辅助工具
import { useGLTF } from '@react-three/drei';

useEffect(() => {
  return () => {
    useGLTF.clear('/model.glb');
  };
}, []);

Texture Optimization

纹理优化

tsx

import { useTexture } from '@react-three/drei';
import * as THREE from 'three';

// Compress and optimize
const texture = useTexture('/texture.jpg', (tex) => {
  tex.minFilter = THREE.LinearMipmapLinearFilter;
  tex.generateMipmaps = true;
  tex.anisotropy = 4;  // Lower = faster, higher = sharper
});

// Use compressed formats (KTX2)
import { useKTX2 } from '@react-three/drei';
const texture = useKTX2('/texture.ktx2');

tsx

import { useTexture } from '@react-three/drei';
import * as THREE from 'three';

// 压缩和优化
const texture = useTexture('/texture.jpg', (tex) => {
  tex.minFilter = THREE.LinearMipmapLinearFilter;
  tex.generateMipmaps = true;
  tex.anisotropy = 4;  // 值越低速度越快，值越高清晰度越高
});

// 使用压缩格式（KTX2）
import { useKTX2 } from '@react-three/drei';
const texture = useKTX2('/texture.ktx2');

Profiling

性能分析

Stats Panel

统计面板

tsx

import { Stats } from '@react-three/drei';

<Canvas>
  <Stats />  {/* FPS, MS, MB counters */}
  <Scene />
</Canvas>

tsx

import { Stats } from '@react-three/drei';

<Canvas>
  <Stats />  {/* FPS、MS、MB计数器 */}
  <Scene />
</Canvas>

Performance Panel

性能面板

tsx

import { Perf } from 'r3f-perf';

<Canvas>
  <Perf 
    position="top-left"
    showGraph          // Show FPS graph
    minimal={false}    // Full or minimal view
  />
  <Scene />
</Canvas>

tsx

import { Perf } from 'r3f-perf';

<Canvas>
  <Perf 
    position="top-left"
    showGraph          // 显示FPS图表
    minimal={false}    // 完整或极简视图
  />
  <Scene />
</Canvas>

Manual Profiling

手动性能分析

tsx

import { useThree } from '@react-three/fiber';

function ProfileInfo() {
  const { gl } = useThree();
  
  useEffect(() => {
    const info = gl.info;
    console.log({
      drawCalls: info.render.calls,
      triangles: info.render.triangles,
      points: info.render.points,
      lines: info.render.lines,
      textures: info.memory.textures,
      geometries: info.memory.geometries
    });
  });
  
  return null;
}

tsx

import { useThree } from '@react-three/fiber';

function ProfileInfo() {
  const { gl } = useThree();
  
  useEffect(() => {
    const info = gl.info;
    console.log({
      drawCalls: info.render.calls,
      triangles: info.render.triangles,
      points: info.render.points,
      lines: info.render.lines,
      textures: info.memory.textures,
      geometries: info.memory.geometries
    });
  });
  
  return null;
}

Frame Time Measurement

帧时间测量

tsx

function FrameProfiler() {
  const frameTimeRef = useRef<number[]>([]);
  
  useFrame(() => {
    const start = performance.now();
    
    // ... your logic ...
    
    const elapsed = performance.now() - start;
    frameTimeRef.current.push(elapsed);
    
    if (frameTimeRef.current.length > 60) {
      const avg = frameTimeRef.current.reduce((a, b) => a + b) / 60;
      console.log(`Avg frame time: ${avg.toFixed(2)}ms`);
      frameTimeRef.current = [];
    }
  });
  
  return null;
}

tsx

function FrameProfiler() {
  const frameTimeRef = useRef<number[]>([]);
  
  useFrame(() => {
    const start = performance.now();
    
    // ... 你的逻辑 ...
    
    const elapsed = performance.now() - start;
    frameTimeRef.current.push(elapsed);
    
    if (frameTimeRef.current.length > 60) {
      const avg = frameTimeRef.current.reduce((a, b) => a + b) / 60;
      console.log(`平均帧时间: ${avg.toFixed(2)}ms`);
      frameTimeRef.current = [];
    }
  });
  
  return null;
}

Common Bottlenecks

常见性能瓶颈

Symptom	Likely Cause	Fix
Low FPS, high draw calls	Too many meshes	Instance, merge, or LOD
Low FPS, few draw calls	Heavy shaders/materials	Simplify shaders, use cheaper materials
Stuttering on load	Large assets	Lazy load, compress, use LOD
Memory growth	No disposal	Dispose on unmount
Mobile issues	High DPR, AA	Limit DPR, disable antialias

症状	可能原因	修复方案
低FPS，绘制调用多	网格数量过多	使用实例化、合并或LOD
低FPS，绘制调用少	着色器/材质过重	简化着色器，使用更轻量化的材质
加载时卡顿	资源过大	懒加载、压缩、使用LOD
内存增长	未释放资源	卸载时释放资源
移动端问题	高DPR、抗锯齿	限制DPR，禁用抗锯齿

Optimization Checklist

优化检查清单

markdown

[ ] Draw calls < 100 for complex scenes
[ ] Instancing for repeated objects
[ ] LOD for large/distant objects
[ ] Geometry merged where possible
[ ] Textures compressed (KTX2/Basis)
[ ] DPR capped at 2
[ ] Lazy loading for heavy assets
[ ] Proper disposal on unmount
[ ] Frustum culling enabled
[ ] Shadows optimized or disabled

markdown

[ ] 复杂场景绘制调用 < 100
[ ] 重复对象使用实例化
[ ] 大型/远距离对象使用LOD
[ ] 尽可能合并几何
[ ] 纹理已压缩（KTX2/Basis）
[ ] DPR上限设为2
[ ] 重型资源使用懒加载
[ ] 卸载时正确释放资源
[ ] 启用视锥体剔除
[ ] 阴影已优化或禁用

File Structure

文件结构

r3f-performance/
├── SKILL.md
├── references/
│   ├── profiling-guide.md      # Deep profiling techniques
│   ├── mobile-optimization.md  # Mobile-specific tips
│   └── large-scenes.md         # Handling massive scenes
└── scripts/
    ├── utils/
    │   ├── lod-helper.ts       # LOD setup utilities
    │   ├── merge-helper.ts     # Geometry merging
    │   └── perf-monitor.ts     # Performance monitoring
    └── presets/
        ├── mobile.ts           # Mobile-optimized Canvas config
        └── desktop.ts          # Desktop-optimized Canvas config

r3f-performance/
├── SKILL.md
├── references/
│   ├── profiling-guide.md      # 深度性能分析技巧
│   ├── mobile-optimization.md  # 移动端专属优化技巧
│   └── large-scenes.md         # 处理超大型场景
└── scripts/
    ├── utils/
    │   ├── lod-helper.ts       # LOD设置工具
    │   ├── merge-helper.ts     # 几何合并工具
    │   └── perf-monitor.ts     # 性能监控工具
    └── presets/
        ├── mobile.ts           # 移动端优化Canvas配置
        └── desktop.ts          # 桌面端优化Canvas配置

Reference

参考资料

```
references/profiling-guide.md
```
— Deep profiling with browser DevTools
```
references/mobile-optimization.md
```
— Mobile-specific optimization
```
references/large-scenes.md
```
— Handling 100k+ object scenes

```
references/profiling-guide.md
```
— 浏览器DevTools深度性能分析
```
references/mobile-optimization.md
```
— 移动端专属优化
```
references/large-scenes.md
```
— 处理10万+对象的场景