r3f-geometry
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseReact Three Fiber Geometry
React Three Fiber 几何体
Quick Start
快速开始
tsx
import { Canvas } from '@react-three/fiber'
function Scene() {
return (
<Canvas>
<ambientLight />
<mesh position={[0, 0, 0]}>
<boxGeometry args={[1, 1, 1]} />
<meshStandardMaterial color="hotpink" />
</mesh>
</Canvas>
)
}tsx
import { Canvas } from '@react-three/fiber'
function Scene() {
return (
<Canvas>
<ambientLight />
<mesh position={[0, 0, 0]}>
<boxGeometry args={[1, 1, 1]} />
<meshStandardMaterial color="hotpink" />
</mesh>
</Canvas>
)
}Built-in Geometries
内置几何体
All Three.js geometries are available as JSX elements. The prop passes constructor arguments.
args所有Three.js几何体都可以作为JSX元素使用。属性用于传递构造函数参数。
argsBasic Shapes
基础形状
tsx
// BoxGeometry(width, height, depth, widthSegments, heightSegments, depthSegments)
<boxGeometry args={[1, 1, 1]} />
<boxGeometry args={[2, 1, 0.5, 2, 2, 2]} />
// SphereGeometry(radius, widthSegments, heightSegments, phiStart, phiLength, thetaStart, thetaLength)
<sphereGeometry args={[1, 32, 32]} />
<sphereGeometry args={[1, 64, 64]} /> // High quality
<sphereGeometry args={[1, 32, 32, 0, Math.PI]} /> // Hemisphere
// PlaneGeometry(width, height, widthSegments, heightSegments)
<planeGeometry args={[10, 10]} />
<planeGeometry args={[10, 10, 32, 32]} /> // Subdivided for displacement
// CircleGeometry(radius, segments, thetaStart, thetaLength)
<circleGeometry args={[1, 32]} />
<circleGeometry args={[1, 32, 0, Math.PI]} /> // Semicircle
// CylinderGeometry(radiusTop, radiusBottom, height, radialSegments, heightSegments, openEnded)
<cylinderGeometry args={[1, 1, 2, 32]} />
<cylinderGeometry args={[0, 1, 2, 32]} /> // Cone
<cylinderGeometry args={[1, 1, 2, 6]} /> // Hexagonal prism
// ConeGeometry(radius, height, radialSegments, heightSegments, openEnded)
<coneGeometry args={[1, 2, 32]} />
// TorusGeometry(radius, tube, radialSegments, tubularSegments, arc)
<torusGeometry args={[1, 0.4, 16, 100]} />
// TorusKnotGeometry(radius, tube, tubularSegments, radialSegments, p, q)
<torusKnotGeometry args={[1, 0.4, 100, 16, 2, 3]} />
// RingGeometry(innerRadius, outerRadius, thetaSegments, phiSegments)
<ringGeometry args={[0.5, 1, 32]} />tsx
// BoxGeometry(width, height, depth, widthSegments, heightSegments, depthSegments)
<boxGeometry args={[1, 1, 1]} />
<boxGeometry args={[2, 1, 0.5, 2, 2, 2]} />
// SphereGeometry(radius, widthSegments, heightSegments, phiStart, phiLength, thetaStart, thetaLength)
<sphereGeometry args={[1, 32, 32]} />
<sphereGeometry args={[1, 64, 64]} /> // 高质量
<sphereGeometry args={[1, 32, 32, 0, Math.PI]} /> // 半球体
// PlaneGeometry(width, height, widthSegments, heightSegments)
<planeGeometry args={[10, 10]} />
<planeGeometry args={[10, 10, 32, 32]} /> // 细分用于位移效果
// CircleGeometry(radius, segments, thetaStart, thetaLength)
<circleGeometry args={[1, 32]} />
<circleGeometry args={[1, 32, 0, Math.PI]} /> // 半圆
// CylinderGeometry(radiusTop, radiusBottom, height, radialSegments, heightSegments, openEnded)
<cylinderGeometry args={[1, 1, 2, 32]} />
<cylinderGeometry args={[0, 1, 2, 32]} /> // 圆锥体
<cylinderGeometry args={[1, 1, 2, 6]} /> // 六角棱柱
// ConeGeometry(radius, height, radialSegments, heightSegments, openEnded)
<coneGeometry args={[1, 2, 32]} />
// TorusGeometry(radius, tube, radialSegments, tubularSegments, arc)
<torusGeometry args={[1, 0.4, 16, 100]} />
// TorusKnotGeometry(radius, tube, tubularSegments, radialSegments, p, q)
<torusKnotGeometry args={[1, 0.4, 100, 16, 2, 3]} />
// RingGeometry(innerRadius, outerRadius, thetaSegments, phiSegments)
<ringGeometry args={[0.5, 1, 32]} />Advanced Shapes
高级形状
tsx
// CapsuleGeometry(radius, length, capSegments, radialSegments)
<capsuleGeometry args={[0.5, 1, 4, 16]} />
// Polyhedrons
<dodecahedronGeometry args={[1, 0]} /> // radius, detail
<icosahedronGeometry args={[1, 0]} />
<octahedronGeometry args={[1, 0]} />
<tetrahedronGeometry args={[1, 0]} />
// Higher detail = more subdivisions
<icosahedronGeometry args={[1, 4]} /> // Approximates spheretsx
// CapsuleGeometry(radius, length, capSegments, radialSegments)
<capsuleGeometry args={[0.5, 1, 4, 16]} />
// 多面体
<dodecahedronGeometry args={[1, 0]} /> // radius, detail
<icosahedronGeometry args={[1, 0]} />
<octahedronGeometry args={[1, 0]} />
<tetrahedronGeometry args={[1, 0]} />
// 更高的detail值 = 更多细分
<icosahedronGeometry args={[1, 4]} /> // 近似球体Path-Based Shapes
基于路径的形状
tsx
import * as THREE from 'three'
// LatheGeometry - revolve points around Y axis
function LatheShape() {
const points = [
new THREE.Vector2(0, 0),
new THREE.Vector2(0.5, 0),
new THREE.Vector2(0.5, 0.5),
new THREE.Vector2(0.3, 1),
new THREE.Vector2(0, 1),
]
return (
<mesh>
<latheGeometry args={[points, 32]} />
<meshStandardMaterial color="gold" side={THREE.DoubleSide} />
</mesh>
)
}
// TubeGeometry - extrude along a curve
function TubeShape() {
const curve = new THREE.CatmullRomCurve3([
new THREE.Vector3(-2, 0, 0),
new THREE.Vector3(-1, 1, 0),
new THREE.Vector3(1, -1, 0),
new THREE.Vector3(2, 0, 0),
])
return (
<mesh>
<tubeGeometry args={[curve, 64, 0.2, 8, false]} />
<meshStandardMaterial color="blue" />
</mesh>
)
}
// ExtrudeGeometry - extrude a 2D shape
function ExtrudedShape() {
const shape = new THREE.Shape()
shape.moveTo(0, 0)
shape.lineTo(1, 0)
shape.lineTo(1, 1)
shape.lineTo(0, 1)
shape.lineTo(0, 0)
const extrudeSettings = {
steps: 2,
depth: 0.5,
bevelEnabled: true,
bevelThickness: 0.1,
bevelSize: 0.1,
bevelSegments: 3,
}
return (
<mesh>
<extrudeGeometry args={[shape, extrudeSettings]} />
<meshStandardMaterial color="purple" />
</mesh>
)
}tsx
import * as THREE from 'three'
// LatheGeometry - 围绕Y轴旋转点集
function LatheShape() {
const points = [
new THREE.Vector2(0, 0),
new THREE.Vector2(0.5, 0),
new THREE.Vector2(0.5, 0.5),
new THREE.Vector2(0.3, 1),
new THREE.Vector2(0, 1),
]
return (
<mesh>
<latheGeometry args={[points, 32]} />
<meshStandardMaterial color="gold" side={THREE.DoubleSide} />
</mesh>
)
}
// TubeGeometry - 沿曲线挤出
function TubeShape() {
const curve = new THREE.CatmullRomCurve3([
new THREE.Vector3(-2, 0, 0),
new THREE.Vector3(-1, 1, 0),
new THREE.Vector3(1, -1, 0),
new THREE.Vector3(2, 0, 0),
])
return (
<mesh>
<tubeGeometry args={[curve, 64, 0.2, 8, false]} />
<meshStandardMaterial color="blue" />
</mesh>
)
}
// ExtrudeGeometry - 挤出2D形状
function ExtrudedShape() {
const shape = new THREE.Shape()
shape.moveTo(0, 0)
shape.lineTo(1, 0)
shape.lineTo(1, 1)
shape.lineTo(0, 1)
shape.lineTo(0, 0)
const extrudeSettings = {
steps: 2,
depth: 0.5,
bevelEnabled: true,
bevelThickness: 0.1,
bevelSize: 0.1,
bevelSegments: 3,
}
return (
<mesh>
<extrudeGeometry args={[shape, extrudeSettings]} />
<meshStandardMaterial color="purple" />
</mesh>
)
}Drei Shape Helpers
Drei 形状助手
@react-three/drei provides convenient shape components.
tsx
import {
Box, Sphere, Plane, Circle, Cylinder, Cone,
Torus, TorusKnot, Ring, Capsule, Dodecahedron,
Icosahedron, Octahedron, Tetrahedron, RoundedBox
} from '@react-three/drei'
function DreiShapes() {
return (
<>
{/* All shapes accept mesh props directly */}
<Box args={[1, 1, 1]} position={[-3, 0, 0]}>
<meshStandardMaterial color="red" />
</Box>
<Sphere args={[0.5, 32, 32]} position={[-1, 0, 0]}>
<meshStandardMaterial color="blue" />
</Sphere>
<Cylinder args={[0.5, 0.5, 1, 32]} position={[1, 0, 0]}>
<meshStandardMaterial color="green" />
</Cylinder>
{/* RoundedBox - box with rounded edges */}
<RoundedBox
args={[1, 1, 1]} // width, height, depth
radius={0.1} // border radius
smoothness={4} // smoothness of rounded edges
position={[3, 0, 0]}
>
<meshStandardMaterial color="orange" />
</RoundedBox>
</>
)
}@react-three/drei 提供了便捷的形状组件。
tsx
import {
Box, Sphere, Plane, Circle, Cylinder, Cone,
Torus, TorusKnot, Ring, Capsule, Dodecahedron,
Icosahedron, Octahedron, Tetrahedron, RoundedBox
} from '@react-three/drei'
function DreiShapes() {
return (
<>
{/* 所有形状都直接接受网格属性 */}
<Box args={[1, 1, 1]} position={[-3, 0, 0]}>
<meshStandardMaterial color="red" />
</Box>
<Sphere args={[0.5, 32, 32]} position={[-1, 0, 0]}>
<meshStandardMaterial color="blue" />
</Sphere>
<Cylinder args={[0.5, 0.5, 1, 32]} position={[1, 0, 0]}>
<meshStandardMaterial color="green" />
</Cylinder>
{/* RoundedBox - 带圆角的立方体 */}
<RoundedBox
args={[1, 1, 1]} // 宽、高、深
radius={0.1} // 圆角半径
smoothness={4} // 圆角平滑度
position={[3, 0, 0]}
>
<meshStandardMaterial color="orange" />
</RoundedBox>
</>
)
}Custom BufferGeometry
自定义BufferGeometry
Basic Custom Geometry
基础自定义几何体
tsx
import { useMemo, useRef } from 'react'
import * as THREE from 'three'
function CustomTriangle() {
const geometry = useMemo(() => {
const geo = new THREE.BufferGeometry()
// Vertices (3 floats per vertex: x, y, z)
const vertices = new Float32Array([
-1, -1, 0, // vertex 0
1, -1, 0, // vertex 1
0, 1, 0, // vertex 2
])
// Normals (pointing toward camera)
const normals = new Float32Array([
0, 0, 1,
0, 0, 1,
0, 0, 1,
])
// UVs
const uvs = new Float32Array([
0, 0,
1, 0,
0.5, 1,
])
geo.setAttribute('position', new THREE.BufferAttribute(vertices, 3))
geo.setAttribute('normal', new THREE.BufferAttribute(normals, 3))
geo.setAttribute('uv', new THREE.BufferAttribute(uvs, 2))
return geo
}, [])
return (
<mesh geometry={geometry}>
<meshStandardMaterial color="cyan" side={THREE.DoubleSide} />
</mesh>
)
}tsx
import { useMemo, useRef } from 'react'
import * as THREE from 'three'
function CustomTriangle() {
const geometry = useMemo(() => {
const geo = new THREE.BufferGeometry()
// 顶点(每个顶点3个浮点数:x, y, z)
const vertices = new Float32Array([
-1, -1, 0, // 顶点0
1, -1, 0, // 顶点1
0, 1, 0, // 顶点2
])
// 法线(指向相机)
const normals = new Float32Array([
0, 0, 1,
0, 0, 1,
0, 0, 1,
])
// UV坐标
const uvs = new Float32Array([
0, 0,
1, 0,
0.5, 1,
])
geo.setAttribute('position', new THREE.BufferAttribute(vertices, 3))
geo.setAttribute('normal', new THREE.BufferAttribute(normals, 3))
geo.setAttribute('uv', new THREE.BufferAttribute(uvs, 2))
return geo
}, [])
return (
<mesh geometry={geometry}>
<meshStandardMaterial color="cyan" side={THREE.DoubleSide} />
</mesh>
)
}Indexed Geometry
索引化几何体
tsx
function CustomQuad() {
const geometry = useMemo(() => {
const geo = new THREE.BufferGeometry()
// 4 vertices for a quad
const vertices = new Float32Array([
-1, -1, 0, // 0: bottom-left
1, -1, 0, // 1: bottom-right
1, 1, 0, // 2: top-right
-1, 1, 0, // 3: top-left
])
// Indices to form 2 triangles
const indices = new Uint16Array([
0, 1, 2, // triangle 1
0, 2, 3, // triangle 2
])
const normals = new Float32Array([
0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1,
])
const uvs = new Float32Array([
0, 0, 1, 0, 1, 1, 0, 1,
])
geo.setAttribute('position', new THREE.BufferAttribute(vertices, 3))
geo.setAttribute('normal', new THREE.BufferAttribute(normals, 3))
geo.setAttribute('uv', new THREE.BufferAttribute(uvs, 2))
geo.setIndex(new THREE.BufferAttribute(indices, 1))
return geo
}, [])
return (
<mesh geometry={geometry}>
<meshStandardMaterial color="lime" side={THREE.DoubleSide} />
</mesh>
)
}tsx
function CustomQuad() {
const geometry = useMemo(() => {
const geo = new THREE.BufferGeometry()
// 四边形的4个顶点
const vertices = new Float32Array([
-1, -1, 0, // 0: 左下角
1, -1, 0, // 1: 右下角
1, 1, 0, // 2: 右上角
-1, 1, 0, // 3: 左上角
])
// 用于构成2个三角形的索引
const indices = new Uint16Array([
0, 1, 2, // 三角形1
0, 2, 3, // 三角形2
])
const normals = new Float32Array([
0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1,
])
const uvs = new Float32Array([
0, 0, 1, 0, 1, 1, 0, 1,
])
geo.setAttribute('position', new THREE.BufferAttribute(vertices, 3))
geo.setAttribute('normal', new THREE.BufferAttribute(normals, 3))
geo.setAttribute('uv', new THREE.BufferAttribute(uvs, 2))
geo.setIndex(new THREE.BufferAttribute(indices, 1))
return geo
}, [])
return (
<mesh geometry={geometry}>
<meshStandardMaterial color="lime" side={THREE.DoubleSide} />
</mesh>
)
}Dynamic Geometry
动态几何体
tsx
import { useRef } from 'react'
import { useFrame } from '@react-three/fiber'
function WavyPlane() {
const meshRef = useRef()
useFrame(({ clock }) => {
const positions = meshRef.current.geometry.attributes.position
const time = clock.elapsedTime
for (let i = 0; i < positions.count; i++) {
const x = positions.getX(i)
const y = positions.getY(i)
positions.setZ(i, Math.sin(x * 2 + time) * Math.cos(y * 2 + time) * 0.5)
}
positions.needsUpdate = true
meshRef.current.geometry.computeVertexNormals()
})
return (
<mesh ref={meshRef} rotation={[-Math.PI / 2, 0, 0]}>
<planeGeometry args={[10, 10, 32, 32]} />
<meshStandardMaterial color="royalblue" side={THREE.DoubleSide} />
</mesh>
)
}tsx
import { useRef } from 'react'
import { useFrame } from '@react-three/fiber'
function WavyPlane() {
const meshRef = useRef()
useFrame(({ clock }) => {
const positions = meshRef.current.geometry.attributes.position
const time = clock.elapsedTime
for (let i = 0; i < positions.count; i++) {
const x = positions.getX(i)
const y = positions.getY(i)
positions.setZ(i, Math.sin(x * 2 + time) * Math.cos(y * 2 + time) * 0.5)
}
positions.needsUpdate = true
meshRef.current.geometry.computeVertexNormals()
})
return (
<mesh ref={meshRef} rotation={[-Math.PI / 2, 0, 0]}>
<planeGeometry args={[10, 10, 32, 32]} />
<meshStandardMaterial color="royalblue" side={THREE.DoubleSide} />
</mesh>
)
}Drei Instancing
Drei 实例化
Efficient rendering of many identical objects.
高效渲染大量相同对象。
Instances Component
Instances组件
tsx
import { Instances, Instance } from '@react-three/drei'
import { useFrame } from '@react-three/fiber'
import { useRef } from 'react'
function InstancedBoxes() {
const count = 1000
return (
<Instances limit={count} range={count}>
<boxGeometry args={[0.5, 0.5, 0.5]} />
<meshStandardMaterial />
{Array.from({ length: count }, (_, i) => (
<AnimatedInstance key={i} index={i} />
))}
</Instances>
)
}
function AnimatedInstance({ index }) {
const ref = useRef()
// Random initial position
const position = useMemo(() => [
(Math.random() - 0.5) * 20,
(Math.random() - 0.5) * 20,
(Math.random() - 0.5) * 20,
], [])
const color = useMemo(() =>
['red', 'blue', 'green', 'yellow', 'purple'][index % 5],
[index])
useFrame(({ clock }) => {
const t = clock.elapsedTime
ref.current.rotation.x = t + index
ref.current.rotation.y = t * 0.5 + index
})
return (
<Instance
ref={ref}
position={position}
color={color}
scale={0.5 + Math.random() * 0.5}
/>
)
}tsx
import { Instances, Instance } from '@react-three/drei'
import { useFrame } from '@react-three/fiber'
import { useRef } from 'react'
function InstancedBoxes() {
const count = 1000
return (
<Instances limit={count} range={count}>
<boxGeometry args={[0.5, 0.5, 0.5]} />
<meshStandardMaterial />
{Array.from({ length: count }, (_, i) => (
<AnimatedInstance key={i} index={i} />
))}
</Instances>
)
}
function AnimatedInstance({ index }) {
const ref = useRef()
// 随机初始位置
const position = useMemo(() => [
(Math.random() - 0.5) * 20,
(Math.random() - 0.5) * 20,
(Math.random() - 0.5) * 20,
], [])
const color = useMemo(() =>
['red', 'blue', 'green', 'yellow', 'purple'][index % 5],
[index])
useFrame(({ clock }) => {
const t = clock.elapsedTime
ref.current.rotation.x = t + index
ref.current.rotation.y = t * 0.5 + index
})
return (
<Instance
ref={ref}
position={position}
color={color}
scale={0.5 + Math.random() * 0.5}
/>
)
}Merged Geometry
合并几何体
For static instances, merge geometry for best performance:
tsx
import { Merged } from '@react-three/drei'
import { useMemo } from 'react'
import * as THREE from 'three'
function MergedMeshes() {
// Create geometries to merge
const meshes = useMemo(() => ({
Sphere: new THREE.SphereGeometry(0.5, 32, 32),
Box: new THREE.BoxGeometry(1, 1, 1),
Cone: new THREE.ConeGeometry(0.5, 1, 32),
}), [])
return (
<Merged meshes={meshes}>
{({ Sphere, Box, Cone }) => (
<>
<Sphere position={[-2, 0, 0]} color="red" />
<Sphere position={[-2, 2, 0]} color="orange" />
<Box position={[0, 0, 0]} color="blue" />
<Box position={[0, 2, 0]} color="cyan" />
<Cone position={[2, 0, 0]} color="green" />
<Cone position={[2, 2, 0]} color="lime" />
</>
)}
</Merged>
)
}对于静态实例,合并几何体以获得最佳性能:
tsx
import { Merged } from '@react-three/drei'
import { useMemo } from 'react'
import * as THREE from 'three'
function MergedMeshes() {
// 创建要合并的几何体
const meshes = useMemo(() => ({
Sphere: new THREE.SphereGeometry(0.5, 32, 32),
Box: new THREE.BoxGeometry(1, 1, 1),
Cone: new THREE.ConeGeometry(0.5, 1, 32),
}), [])
return (
<Merged meshes={meshes}>
{({ Sphere, Box, Cone }) => (
<>
<Sphere position={[-2, 0, 0]} color="red" />
<Sphere position={[-2, 2, 0]} color="orange" />
<Box position={[0, 0, 0]} color="blue" />
<Box position={[0, 2, 0]} color="cyan" />
<Cone position={[2, 0, 0]} color="green" />
<Cone position={[2, 2, 0]} color="lime" />
</>
)}
</Merged>
)
}Points (Particle Systems)
点(粒子系统)
Basic Points
基础点
tsx
import { Points, Point, PointMaterial } from '@react-three/drei'
function ParticleField() {
const count = 5000
return (
<Points limit={count}>
<PointMaterial
transparent
vertexColors
size={0.05}
sizeAttenuation
depthWrite={false}
/>
{Array.from({ length: count }, (_, i) => (
<Point
key={i}
position={[
(Math.random() - 0.5) * 10,
(Math.random() - 0.5) * 10,
(Math.random() - 0.5) * 10,
]}
color={`hsl(${Math.random() * 360}, 100%, 50%)`}
/>
))}
</Points>
)
}tsx
import { Points, Point, PointMaterial } from '@react-three/drei'
function ParticleField() {
const count = 5000
return (
<Points limit={count}>
<PointMaterial
transparent
vertexColors
size={0.05}
sizeAttenuation
depthWrite={false}
/>
{Array.from({ length: count }, (_, i) => (
<Point
key={i}
position={[
(Math.random() - 0.5) * 10,
(Math.random() - 0.5) * 10,
(Math.random() - 0.5) * 10,
]}
color={`hsl(${Math.random() * 360}, 100%, 50%)`}
/>
))}
</Points>
)
}Buffer-Based Points (High Performance)
基于Buffer的点(高性能)
tsx
import { useMemo, useRef } from 'react'
import { useFrame } from '@react-three/fiber'
import * as THREE from 'three'
function BufferParticles() {
const count = 10000
const pointsRef = useRef()
const { positions, colors } = useMemo(() => {
const positions = new Float32Array(count * 3)
const colors = new Float32Array(count * 3)
for (let i = 0; i < count; i++) {
positions[i * 3] = (Math.random() - 0.5) * 10
positions[i * 3 + 1] = (Math.random() - 0.5) * 10
positions[i * 3 + 2] = (Math.random() - 0.5) * 10
colors[i * 3] = Math.random()
colors[i * 3 + 1] = Math.random()
colors[i * 3 + 2] = Math.random()
}
return { positions, colors }
}, [])
useFrame(({ clock }) => {
pointsRef.current.rotation.y = clock.elapsedTime * 0.1
})
return (
<points ref={pointsRef}>
<bufferGeometry>
<bufferAttribute
attach="attributes-position"
count={count}
array={positions}
itemSize={3}
/>
<bufferAttribute
attach="attributes-color"
count={count}
array={colors}
itemSize={3}
/>
</bufferGeometry>
<pointsMaterial size={0.05} vertexColors sizeAttenuation />
</points>
)
}tsx
import { useMemo, useRef } from 'react'
import { useFrame } from '@react-three/fiber'
import * as THREE from 'three'
function BufferParticles() {
const count = 10000
const pointsRef = useRef()
const { positions, colors } = useMemo(() => {
const positions = new Float32Array(count * 3)
const colors = new Float32Array(count * 3)
for (let i = 0; i < count; i++) {
positions[i * 3] = (Math.random() - 0.5) * 10
positions[i * 3 + 1] = (Math.random() - 0.5) * 10
positions[i * 3 + 2] = (Math.random() - 0.5) * 10
colors[i * 3] = Math.random()
colors[i * 3 + 1] = Math.random()
colors[i * 3 + 2] = Math.random()
}
return { positions, colors }
}, [])
useFrame(({ clock }) => {
pointsRef.current.rotation.y = clock.elapsedTime * 0.1
})
return (
<points ref={pointsRef}>
<bufferGeometry>
<bufferAttribute
attach="attributes-position"
count={count}
array={positions}
itemSize={3}
/>
<bufferAttribute
attach="attributes-color"
count={count}
array={colors}
itemSize={3}
/>
</bufferGeometry>
<pointsMaterial size={0.05} vertexColors sizeAttenuation />
</points>
)
}Lines
线条
Basic Line
基础线条
tsx
import { Line } from '@react-three/drei'
function BasicLine() {
const points = [
[0, 0, 0],
[1, 1, 0],
[2, 0, 0],
[3, 1, 0],
]
return (
<Line
points={points}
color="red"
lineWidth={2}
/>
)
}tsx
import { Line } from '@react-three/drei'
function BasicLine() {
const points = [
[0, 0, 0],
[1, 1, 0],
[2, 0, 0],
[3, 1, 0],
]
return (
<Line
points={points}
color="red"
lineWidth={2}
/>
)
}Curved Line
曲线
tsx
import { CatmullRomLine, QuadraticBezierLine, CubicBezierLine } from '@react-three/drei'
function CurvedLines() {
return (
<>
{/* Smooth curve through points */}
<CatmullRomLine
points={[[0, 0, 0], [1, 1, 0], [2, 0, 0], [3, 1, 0]]}
color="blue"
lineWidth={2}
segments={64}
/>
{/* Quadratic bezier */}
<QuadraticBezierLine
start={[0, 0, 0]}
mid={[1, 2, 0]}
end={[2, 0, 0]}
color="green"
lineWidth={2}
/>
{/* Cubic bezier */}
<CubicBezierLine
start={[0, 0, 0]}
midA={[0.5, 2, 0]}
midB={[1.5, -1, 0]}
end={[2, 0, 0]}
color="purple"
lineWidth={2}
/>
</>
)
}tsx
import { CatmullRomLine, QuadraticBezierLine, CubicBezierLine } from '@react-three/drei'
function CurvedLines() {
return (
<>
{/* 平滑曲线穿过点集 */}
<CatmullRomLine
points={[[0, 0, 0], [1, 1, 0], [2, 0, 0], [3, 1, 0]]}
color="blue"
lineWidth={2}
segments={64}
/>
{/* 二次贝塞尔曲线 */}
<QuadraticBezierLine
start={[0, 0, 0]}
mid={[1, 2, 0]}
end={[2, 0, 0]}
color="green"
lineWidth={2}
/>
{/* 三次贝塞尔曲线 */}
<CubicBezierLine
start={[0, 0, 0]}
midA={[0.5, 2, 0]}
midB={[1.5, -1, 0]}
end={[2, 0, 0]}
color="purple"
lineWidth={2}
/>
</>
)
}Dashed Line
虚线
tsx
<Line
points={[[0, 0, 0], [5, 0, 0]]}
color="white"
lineWidth={2}
dashed
dashScale={50}
dashSize={0.5}
dashOffset={0}
gapSize={0.2}
/>tsx
<Line
points={[[0, 0, 0], [5, 0, 0]]}
color="white"
lineWidth={2}
dashed
dashScale={50}
dashSize={0.5}
dashOffset={0}
gapSize={0.2}
/>Edges and Wireframe
边缘线与线框
tsx
import { Edges } from '@react-three/drei'
function BoxWithEdges() {
return (
<mesh>
<boxGeometry />
<meshStandardMaterial color="orange" />
<Edges
scale={1.1}
threshold={15} // Display edges with angle > 15 degrees
color="black"
/>
</mesh>
)
}
// Wireframe material
function WireframeBox() {
return (
<mesh>
<boxGeometry />
<meshBasicMaterial color="cyan" wireframe />
</mesh>
)
}tsx
import { Edges } from '@react-three/drei'
function BoxWithEdges() {
return (
<mesh>
<boxGeometry />
<meshStandardMaterial color="orange" />
<Edges
scale={1.1}
threshold={15} // 显示角度>15度的边缘
color="black"
/>
</mesh>
)
}
// 线框材质
function WireframeBox() {
return (
<mesh>
<boxGeometry />
<meshBasicMaterial color="cyan" wireframe />
</mesh>
)
}Text Geometry
文本几何体
Using Drei Text3D
使用Drei Text3D
tsx
import { Text3D, Center } from '@react-three/drei'
function Text3DExample() {
return (
<Center>
<Text3D
font="/fonts/helvetiker_regular.typeface.json"
size={1}
height={0.2}
curveSegments={12}
bevelEnabled
bevelThickness={0.02}
bevelSize={0.02}
bevelOffset={0}
bevelSegments={5}
>
Hello R3F
<meshStandardMaterial color="gold" />
</Text3D>
</Center>
)
}tsx
import { Text3D, Center } from '@react-three/drei'
function Text3DExample() {
return (
<Center>
<Text3D
font="/fonts/helvetiker_regular.typeface.json"
size={1}
height={0.2}
curveSegments={12}
bevelEnabled
bevelThickness={0.02}
bevelSize={0.02}
bevelOffset={0}
bevelSegments={5}
>
Hello R3F
<meshStandardMaterial color="gold" />
</Text3D>
</Center>
)
}Geometry Utilities
几何体工具
Center Geometry
居中几何体
tsx
import { Center } from '@react-three/drei'
function CenteredModel() {
return (
<Center>
<mesh>
<boxGeometry args={[2, 1, 0.5]} />
<meshStandardMaterial />
</mesh>
</Center>
)
}
// With options
<Center top left> {/* Align to top-left */}
<Model />
</Center>
// Get bounding info
<Center onCentered={({ width, height, depth, boundingBox }) => {
console.log('Dimensions:', width, height, depth)
}}>
<Model />
</Center>tsx
import { Center } from '@react-three/drei'
function CenteredModel() {
return (
<Center>
<mesh>
<boxGeometry args={[2, 1, 0.5]} />
<meshStandardMaterial />
</mesh>
</Center>
)
}
// 带选项
<Center top left> {/* 对齐到左上角 */}
<Model />
</Center>
// 获取边界信息
<Center onCentered={({ width, height, depth, boundingBox }) => {
console.log('尺寸:', width, height, depth)
}}>
<Model />
</Center>Compute Bounds
计算边界
tsx
import { useBounds, Bounds } from '@react-three/drei'
function FitToView() {
return (
<Bounds fit clip observe margin={1.2}>
<SelectToZoom />
</Bounds>
)
}
function SelectToZoom() {
const bounds = useBounds()
return (
<mesh
onClick={(e) => {
e.stopPropagation()
bounds.refresh(e.object).fit()
}}
>
<boxGeometry />
<meshStandardMaterial />
</mesh>
)
}tsx
import { useBounds, Bounds } from '@react-three/drei'
function FitToView() {
return (
<Bounds fit clip observe margin={1.2}>
<SelectToZoom />
</Bounds>
)
}
function SelectToZoom() {
const bounds = useBounds()
return (
<mesh
onClick={(e) => {
e.stopPropagation()
bounds.refresh(e.object).fit()
}}
>
<boxGeometry />
<meshStandardMaterial />
</mesh>
)
}Performance Tips
性能优化技巧
- Reuse geometries: Same geometry instance = better batching
- Use Instances: For many identical objects
- Merge static meshes: Use for static scenes
<Merged> - Appropriate segment counts: Balance quality vs performance
- Dispose unused geometry: R3F handles this automatically
tsx
// Good segment counts
<sphereGeometry args={[1, 32, 32]} /> // Standard quality
<sphereGeometry args={[1, 64, 64]} /> // High quality
<sphereGeometry args={[1, 16, 16]} /> // Performance mode
// Reuse geometry
const sharedGeometry = useMemo(() => new THREE.BoxGeometry(), [])
<mesh geometry={sharedGeometry} position={[0, 0, 0]} />
<mesh geometry={sharedGeometry} position={[2, 0, 0]} />
<mesh geometry={sharedGeometry} position={[4, 0, 0]} />- 重用几何体:相同的几何体实例 = 更好的批处理效果
- 使用Instances:用于大量相同对象
- 合并静态网格:对静态场景使用
<Merged> - 合适的分段数:平衡质量与性能
- 释放未使用的几何体:R3F会自动处理
tsx
// 合适的分段数
<sphereGeometry args={[1, 32, 32]} /> // 标准质量
<sphereGeometry args={[1, 64, 64]} /> // 高质量
<sphereGeometry args={[1, 16, 16]} /> // 性能模式
// 重用几何体
const sharedGeometry = useMemo(() => new THREE.BoxGeometry(), [])
<mesh geometry={sharedGeometry} position={[0, 0, 0]} />
<mesh geometry={sharedGeometry} position={[2, 0, 0]} />
<mesh geometry={sharedGeometry} position={[4, 0, 0]} />See Also
另请参阅
- - JSX elements and refs
r3f-fundamentals - - Materials for meshes
r3f-materials - - Custom vertex manipulation
r3f-shaders
- - JSX元素与引用
r3f-fundamentals - - 网格材质
r3f-materials - - 自定义顶点操作
r3f-shaders