r3f-textures

React Three Fiber のテクスチャ

まず、インストールされている Three.js、Fiber、Drei、レンダラーのバージョンを確認してください。例は Fiber 9／React 19、WebGL を使う Three.js r185 を対象としています。正しく設定済みのアセットは、すべてリセットせずにそのまま維持してください。

色とデータの違い

テクスチャの内容	カラースペースの指定
PNG/JPEG のベースカラーまたはエミッシブカラー	SRGBColorSpace
ラフネス、メタルネス、法線、AO、アルファ／マスク	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 ローダーはテクスチャのメタデータを設定します。カスタムシェーダーのユニフォームや手動で作成したテクスチャでは、明示的な指定が特に重要です。

キャッシュと所有権

• useTexture／useLoader はローダーと URL の入力値をキーにキャッシュします。同じソースから同じ Texture オブジェクトが返されることがあります。リピート、オフセット、ラッピング、フィルター、colorSpace の変更は、すべての利用側に影響する可能性があります。
• インスタンスごとに設定する場合は、Texture オブジェクトをクローンしてください。可能な場合は基になる画像を再利用し、自分が所有するクローンだけを個別に破棄してください。個々の利用側からキャッシュ済みのソースを破棄しないでください。
• レンダリング中にローダーのキャッシュをクリアしないでください。キャッシュの削除と GPU リソースの破棄は別の操作であり、そのリソースを必要とするアクティブな利用側が残っていないことを確認する必要があります。
• 毎フレーム、ユニフォーム／テクスチャオブジェクトを置き換えるのは避けてください。オフセットや所有する値を直接更新してください。需要時レンダリングでは、命令的な変更後に invalidate を呼び出してください。

UV とサンプリング

• texture.channel = 0 は uv、1 は uv1、続いて uv2 と uv3 を選択します。実際のジオメトリ属性を選んでください。AO／ライトマップで uv を uv2 にコピーする必要があるとは限りません。
• [0, 1] の範囲外でリピートするには、RepeatWrapping または MirroredRepeatWrapping が必要です。オフセット／リピート／回転はテクスチャ変換です。アトラスアニメーションでは、通常、毎フレーム React の状態を使う必要はありません。
• ラッピング、カラースペース、アップロード設定の変更には、texture.needsUpdate が必要な場合があります。オフセット／リピートの変更ではテクスチャ行列が使われるため、通常、画像データの再アップロードは必要ありません。
• ピクセルアートには、意図してニアレストフィルタリングを使用してください。縮小されるサーフェスでは、ミップマップによってちらつきを抑えられます。異方性フィルタリングは、レンダラーがサポートする最大値とシーンの要件に合わせて設定してください。
• 2 の累乗の寸法は、WebGL2 で常に必要というわけではありません。古い一律のルールではなく、画面上の占有範囲、メモリ、圧縮形式の制約、品質に合わせてテクスチャのサイズを決めてください。
• ダウンロードサイズと GPU メモリ上のサイズは異なります。対応している場合は KTX2/Basis を検討し、レンダラーの対応状況の検出とデコーダー／トランスコーダー用アセットの配置を適切に設定してください。
• glTF のカラーマップを置き換える場合は、モデルの UV／向きの規則に合わせてください。手動で読み込んだテクスチャには、通常 flipY=false が必要です。すでに設定済みの glTF マップを再度反転しないでください。

特殊なテクスチャ

• ライフサイクルが要件に合う場合は、useVideoTexture を優先してください。自動再生／ミュート、CORS、ユーザー操作、ソースのクリーンアップを確認してください。動画の解像度を変更すると、新しいテクスチャが必要になる場合があります。すべてのブラウザーで自動再生に成功するとは限りません。
• Canvas／DataTexture の内容を変更した場合は needsUpdate が必要です。データテクスチャでは、データとしてのカラースペースの意味を維持してください。フレームループ内でテクスチャを作成すると、意図的に管理していない限り、処理やリソースのリークにつながります。
• レンダーターゲットについては、オフスクリーンレンダリングを参照してください。同じターゲットへの描画中に、そのテクスチャをサンプリングしないでください。
• 適切なマッピング／PMREM ワークフローなしに通常の 2D 画像を割り当てるのではなく、環境マップはライティング用の経路（Environment／useEnvironment）で使用してください。

検証

既知のカラースウォッチ、照明を変えたときのデータマップ、テクスチャの向き、繰り返しマウント、UV 変換が異なる 2 つのコンシューマーをテストします。GPU のテクスチャ数を確認してください。これは数であり、バイト単位で正確なメモリ使用量を示すものではありません。

参考資料

• 色管理、テクスチャ。
• Drei useTexture、useVideoTexture。
• Fiber 9 のテクスチャ変更。