05｜相机与控制

/**
 * 透视相机 — 模拟人眼
 *
 * 近大远小，适合 3D 场景、游戏、真实感渲染。
 *
 * PerspectiveCamera(fov, aspect, near, far)
 *   fov    — 视场角（度），越大视野越广，透视变形越强
 *   aspect — 宽高比（宽/高），窗口变化时需要同步更新
 *   near   — 近裁剪面，比这更近的物体不显示
 *   far    — 远裁剪面，比这更远的物体不显示
 */
const perspectiveCamera = new THREE.PerspectiveCamera(50, aspect, 0.1, 100)
perspectiveCamera.position.set(5, 5, 10)
perspectiveCamera.lookAt(0, 0, 0)

/**
 * 正交相机 — 无透视效果
 *
 * 远近一样大，适合 CAD、建筑预览、2D 游戏、策略游戏俯视角。
 *
 * OrthographicCamera(left, right, top, bottom, near, far)
 *   left/right — 可视范围的左右边界
 *   top/bottom — 可视范围的上下边界
 *   near/far   — 近/远裁剪面
 *
 * 注意：需要保持宽高比与屏幕一致，否则物体会被拉伸变形
 */
const frustumSize = 10
const orthographicCamera = new THREE.OrthographicCamera(
  -frustumSize * aspect / 2,   // left
  frustumSize * aspect / 2,    // right
  frustumSize / 2,             // top
  -frustumSize / 2,            // bottom
  0.1,                         // near
  100                          // far
)

/**
 * Near/Far 最佳实践
 *
 * Near/Far 比值不要超过 1000:1
 *   太大 → 深度精度下降（远处物体 z-fighting）
 *   太小 → 近处或远处物体被裁掉
 *
 * 解决方案：对数深度缓冲
 *   renderer.logarithmicDepthBuffer = true
 *   近处精度高，远处精度低，完美解决超大范围场景
 */
renderer.logarithmicDepthBuffer = true  // 太空场景等超大范围

/**
 * CameraHelper — 相机辅助可视化
 *
 * 显示相机的视锥体：
 *   - 近裁剪面（小矩形）
 *   - 远裁剪面（大矩形）
 *   - 连接线（表示视锥范围）
 *
 * 透视相机 Helper → 锥体（金字塔形）
 * 正交相机 Helper → 长方体（盒子形）
 */
const perspectiveHelper = new THREE.CameraHelper(perspectiveCamera)
scene.add(perspectiveHelper)

const orthographicHelper = new THREE.CameraHelper(orthographicCamera)
scene.add(orthographicHelper)
orthographicHelper.visible = false  // 默认隐藏

/**
 * OrbitControls — 轨道控制器
 *
 * 让用户可以用鼠标拖拽旋转、缩放、平移视角
 *
 * 常用属性：
 *   enableDamping   — 启用阻尼（惯性），让旋转更平滑
 *   dampingFactor   — 阻尼系数（0~1），越小惯性越大
 *   target          — 控制器的焦点位置（相机围绕这个点旋转）
 *   enableZoom      — 是否允许缩放（默认 true）
 *   enableRotate    — 是否允许旋转（默认 true）
 *   enablePan       — 是否允许平移（默认 true）
 */
const controls = new OrbitControls(camera, canvas)
controls.enableDamping = true
controls.dampingFactor = 0.05
controls.target.set(0, 0, 0)
controls.enableZoom = true    // 滚轮缩放
controls.enableRotate = true  // 左键拖拽旋转
controls.enablePan = true     // 右键拖拽平移

/**
 * 窗口大小变化时，必须同步更新相机参数
 *
 * 透视相机：更新 aspect（宽高比）
 * 正交相机：更新 left/right（保持宽高比）
 * 否则画面会被拉伸变形
 */
window.addEventListener('resize', () => {
  const aspect = window.innerWidth / window.innerHeight

  // 透视相机：更新 aspect
  perspectiveCamera.aspect = aspect
  perspectiveCamera.updateProjectionMatrix()

  // 正交相机：更新 left/right
  orthographicCamera.left = -frustumSize * aspect / 2
  orthographicCamera.right = frustumSize * aspect / 2
  orthographicCamera.updateProjectionMatrix()
})