r3f-textures

React Three Fiber 纹理

请先检查已安装的 Three.js、Fiber、Drei 和渲染器版本。示例面向 Fiber 9 / React 19 和使用 WebGL 的 Three.js r185。请保留配置正确的资源，不要重置所有纹理。

颜色与数据

纹理内容	色彩空间标注
PNG/JPEG 基础颜色或自发光颜色	SRGBColorSpace
粗糙度、金属度、法线、AO、Alpha/遮罩	NoColorSpace
线性 HDR/EXR 光照数据	保留加载器提供的线性元数据

NoColorSpace 不等同于 LinearSRGBColorSpace：标量/向量数据没有色彩空间。不要一概将所有贴图转换为 sRGB。

加载颜色贴图

在 Canvas 内的 Suspense 下挂载。文件路径是应用资源，并非本技能提供的文件。

import { useTexture } from '@react-three/drei'
import { SRGBColorSpace } from 'three'

export default function Example() {
  const map = useTexture('/textures/checker.png', (texture) => {
    // This URL is consistently used as a color texture by all consumers.
    texture.colorSpace = SRGBColorSpace
    texture.needsUpdate = true
  })
  return (
    <mesh>
      <planeGeometry args={[3, 3]} />
      <meshStandardMaterial map={map} roughness={1} />
    </mesh>
  )
}

Fiber 会处理常见的内置颜色贴图属性，glTF 加载器也会设置纹理元数据。对于自定义着色器 uniform 或手动创建的纹理，显式标注尤为重要。

缓存与所有权

• useTexture/useLoader 会根据加载器和 URL 输入进行缓存。同一来源可能返回同一个 Texture 对象。重复、偏移、包裹、过滤和 colorSpace 的更改可能影响所有使用者。
• 请先克隆 Texture 对象，再进行实例级配置。尽可能复用底层图像；仅单独释放由你持有的克隆。不要在单个使用者中释放缓存的源对象。
• 不要在渲染期间清除加载器缓存。缓存淘汰和 GPU 资源释放是不同操作，而且必须确认没有活跃的使用者仍需要该资源。
• 避免每帧替换 uniform/纹理对象；应直接更新偏移或由你持有的值。在按需渲染循环中，命令式更改后调用 invalidate。

UV 与采样

• texture.channel = 0 选择 uv，1 选择 uv1，随后依次为 uv2 和 uv3。请选择实际的几何体属性；AO/光照贴图不再一律要求将 uv 复制到 uv2。
• 超出 [0, 1] 范围的重复需要使用 RepeatWrapping 或 MirroredRepeatWrapping。偏移/重复/旋转属于纹理变换；图集动画通常不需要每帧更新 React 状态。
• 更改包裹、色彩空间和上传配置可能需要设置 texture.needsUpdate。偏移/重复会使用纹理矩阵，通常不需要重新上传图像数据。
• 对于像素艺术，应有意使用最近邻过滤。对于缩小显示的表面，mipmap 可减少闪烁；请将各向异性上限设为渲染器支持的最大值，并结合场景需求调整。
• WebGL2 并非一律要求尺寸为 2 的幂。请根据屏幕覆盖范围、内存、压缩格式限制和画质来确定纹理尺寸，而不要遵循过时的一刀切规则。
• 下载大小不等于 GPU 内存占用。可考虑使用受支持的 KTX2/Basis；应有意配置渲染器能力检测，并托管解码器/转码器资源。
• 替换 glTF 颜色贴图时，应匹配模型的 UV/方向约定；手动加载的纹理通常需要设置 flipY=false。不要再次翻转已配置好的 glTF 贴图。

专用纹理

• 如果生命周期适合，优先使用 useVideoTexture。检查自动播放/静音、CORS、用户手势和源清理；更改视频分辨率可能需要创建新纹理。不要保证所有浏览器都能成功自动播放。
• Canvas/DataTexture 内容更改后需要设置 needsUpdate；数据纹理应保留数据的色彩空间语义。在帧循环中创建纹理会造成资源/工作泄漏，除非经过有意管理。
• 对于渲染目标，请阅读 离屏渲染。渲染到某个目标时，绝不要同时采样该目标的纹理。
• 环境贴图应通过光照路径（Environment/useEnvironment）使用，不要在缺少合适映射/PMREM 工作流的情况下将普通 2D 图像直接指定为环境贴图。

验证

测试已知的色样、不同光照下的数据贴图、纹理方向、重复挂载，以及使用不同 UV 变换的两个使用方。检查 GPU 纹理数量；它们是数量统计，并非精确到字节的内存测量值。

来源

• 颜色管理，纹理。
• Drei useTexture，useVideoTexture。
• Fiber 9 纹理变更。