用途
Three.js Fundamentals 面向 Three.js 3D 场景搭建的基础环节,用于在创建 3D 场景、创建相机、配置渲染器时提供参考。文档以代码示例和 API 说明的形式,覆盖从初始化到动画循环、窗口适配、资源清理等常见流程。
主要能力
快速上手
文档给出一个最小可运行示例:从 "three" 导入模块,创建 Scene、PerspectiveCamera(视野 75、宽高比取窗口比例、近裁剪面 0.1、远裁剪面 1000)和 WebGLRenderer(开启 antialias),设置渲染尺寸与像素比(受 devicePixelRatio 限制上限 2),将 canvas 追加到 body;随后创建 BoxGeometry 与 MeshStandardMaterial 组成 Mesh,加入 AmbientLight 与 DirectionalLight,设置相机位置,编写 requestAnimationFrame 动画循环旋转立方体并渲染,同时监听 resize 事件更新相机宽高比与渲染尺寸。
核心类
- Scene:容纳 3D 对象、灯光与相机;可设置 background(纯色、纹理、立方体贴图)、environment 环境贴图(用于 PBR)、fog(线性 Fog 或指数 FogExp2)。
- 相机:PerspectiveCamera(透视,模拟人眼,修改 fov/aspect/near/far 后需调用 updateProjectionMatrix)、OrthographicCamera(无透视畸变,适合 2D/等距)、ArrayCamera(多视口子相机)、CubeCamera(渲染环境贴图用于反射,需配合 WebGLCubeRenderTarget)。
- WebGLRenderer:可指定已有 canvas、antialias、alpha、powerPreference、preserveDrawingBuffer;支持 setSize、setPixelRatio、toneMapping(如 ACESFilmicToneMapping)与 toneMappingExposure、outputColorSpace(sRGB,r152+)、shadowMap(如 PCFSoftShadowMap)、setClearColor 与 render。
- Object3D:所有 3D 对象的基类(Mesh、Group、Light、Camera 均继承);包含 position/rotation/quaternion/scale 变换,getWorldPosition/getWorldQuaternion/getWorldDirection 世界变换,add/remove/parent/children 层级,visible 可见性,layers 图层,traverse 遍历,以及 matrixAutoUpdate、updateMatrix、updateMatrixWorld 矩阵更新。
- Group:用于组织对象的空容器,可整体变换。
- Mesh:几何体与材质的组合,支持多材质数组、castShadow/receiveShadow、frustumCulled 视锥剔除、renderOrder 渲染顺序。
坐标系与数学工具
- 坐标系统:右手坐标系,+X 向右、+Y 向上、+Z 朝向观察者;可用 AxesHelper 显示坐标轴(红 X、绿 Y、蓝 Z)。
- Vector3:set/copy/clone,add/sub/multiply/multiplyScalar/divideScalar/normalize/negate/clamp/lerp,length/lengthSq/distanceTo/dot/cross/angleTo,applyMatrix4/applyQuaternion/project/unproject。
- Matrix4:identity/copy/clone,makeTranslation/makeRotationX 等/ makeRotationFromQuaternion/makeScale,compose/decompose,multiply/premultiply/invert/transpose,makePerspective/makeOrthographic/lookAt。
- Quaternion:setFromEuler/setFromAxisAngle/setFromRotationMatrix,multiply/slerp/normalize/invert。
- Euler:指定旋转顺序(XYZ、YXZ、ZXY、XZY、YZX、ZYX),可由四元数或矩阵转换。
- Color:支持十六进制、颜色名、rgb 字符串、# 十六进制;setHex/setRGB/setHSL,lerp/multiply/multiplyScalar。
- MathUtils:clamp、lerp、mapLinear、degToRad、radToDeg、randFloat、randInt、smoothstep、smootherstep。
常见模式
- 资源释放:依次 dispose 几何体、材质(含材质数组)、纹理,从场景移除对象,最后 renderer.dispose()。
- Clock 动画计时:用 getDelta 获取帧间隔、getElapsedTime 获取总时长,使旋转速度不受帧率影响。
- 响应式画布:窗口尺寸变化时更新相机 aspect、调用 updateProjectionMatrix、renderer.setSize 与 setPixelRatio。
- LoadingManager:提供 onStart/onLoad/onProgress/onError 回调,可传给 TextureLoader、GLTFLoader 等加载器。
性能建议
限制 draw call(合并几何体、实例化、纹理图集);默认启用视锥剔除并确保包围盒正确;使用 THREE.LOD 按距离切换细节层级;对象池复用对象;避免在循环中调用 getWorldPosition(缓存结果);文档示例使用 mergeGeometries 合并静态几何体,并按距离为 LOD 添加不同细节层级。
使用方式
资料以技能文档形式提供,包含可直接参考的 JavaScript 代码示例(使用 ES 模块从 "three" 导入,部分工具从 three/examples/jsm 导入)。安装命令、包管理配置和具体运行环境要求暂未提供。
适用场景
适合需要搭建 Three.js 3D 场景、创建和配置相机、初始化渲染器、组织 Object3D 层级、进行坐标与向量/矩阵/四元数运算,以及处理资源释放、动画循环、窗口缩放与加载管理的开发场景。
限制
资料为 Three.js 基础概念与 API 参考,未说明收费、平台支持范围、浏览器兼容性细节或性能基准数据。几何体、材质、光照等更深入的内容在此文档中仅以“See Also”指向 threejs-geometry、threejs-materials、threejs-lighting 等关联文档,未在本文展开。许可证与官方支持信息暂未提供。