06｜纹理与贴图

/**
 * TextureLoader — 加载图片纹理
 *
 * 加载一张图片，将其作为纹理贴到物体表面。
 * 图片推荐使用 2 的幂尺寸（256、512、1024），
 * 这样 GPU 可以生成 Mipmap，提升渲染性能和质量。
 */
const textureLoader = new THREE.TextureLoader()
const texture = textureLoader.load('/textures/uv-grid.jpg')

const material = new THREE.MeshStandardMaterial({
  map: texture,  // 将纹理应用到材质的 map 属性
})

/**
 * repeat — 纹理重复次数
 *
 * 设置纹理在 U/V 方向上的重复次数。
 * 必须配合 RepeatWrapping 使用，否则无效。
 */
texture.wrapS = THREE.RepeatWrapping  // 水平方向允许重复
texture.wrapT = THREE.RepeatWrapping  // 垂直方向允许重复
texture.repeat.set(4, 4)              // 水平和垂直各重复 4 次

/**
 * offset — 纹理偏移
 *
 * 移动纹理在物体表面的位置。
 * 常用于实现纹理滚动动画（如流水、传送带）。
 */
texture.offset.set(0.5, 0.3)  // 水平偏移 0.5，垂直偏移 0.3

/**
 * CubeTextureLoader — 加载立方体环境贴图
 *
 * 需要 6 张图片，分别对应立方体的 6 个面：
 * px (右), nx (左), py (上), ny (下), pz (前), nz (后)
 */
const cubeTextureLoader = new THREE.CubeTextureLoader()
const envMap = cubeTextureLoader.load([
  '/textures/skybox/px.jpg',  // 右
  '/textures/skybox/nx.jpg',  // 左
  '/textures/skybox/py.jpg',  // 上
  '/textures/skybox/ny.jpg',  // 下
  '/textures/skybox/pz.jpg',  // 前
  '/textures/skybox/nz.jpg',  // 后
])

scene.background = envMap  // 设置为场景背景（天空盒）

/**
 * 环境贴图反射
 *
 * envMap 让物体能「看到」并反射周围环境。
 * - metalness = 1.0：金属，反射环境
 * - metalness = 0.0：非金属，忽略环境
 * - roughness = 0：清晰反射（镜子）
 * - roughness = 1：模糊反射（磨砂）
 */
const metalSphere = new THREE.Mesh(
  new THREE.SphereGeometry(1, 64, 64),
  new THREE.MeshStandardMaterial({
    metalness: 1.0,
    roughness: 0.0,
    envMap: envMap,
  })
)

/**
 * RGBELoader — 加载 HDRI 环境贴图
 *
 * HDRI（High Dynamic Range Image）记录真实世界的亮度差异。
 * 与 CubeTextureLoader 的区别：
 * - CubeTexture：6 张图，立方体映射，文件小，加载快
 * - HDRI：1 张图，等距柱状投影（球面），画质高，文件大
 */
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js'

const rgbeLoader = new RGBELoader()
rgbeLoader.load('/textures/venice-sunset.hdr', (hdrTexture) => {
  hdrTexture.mapping = THREE.EquirectangularReflectionMapping
  scene.background = hdrTexture
  scene.environment = hdrTexture  // 让所有物体都能反射这个环境
})