r3f-geometry

React Three Fiber のジオメトリ

コンストラクターの引数やヘルパーのプロパティをコピーする前に、インストールされている Three.js、Fiber、Drei のバージョンを確認してください。例は Fiber 9／React 19 と Three.js r185 を対象としています。

表現方法を選ぶ

• 通常の形状にはネイティブの JSX ジオメトリを使います。args は Three.js のコンストラクターに対応します。変更するとジオメトリが再構築されるため、コンストラクターの入力値ではなく、トランスフォームをアニメーションさせてください。
• カスタムトポロジーには BufferGeometry を使い、大量のパーティクルにはバッファーベースの points を使います。生成した配列は安定させ、結果を再現可能にする必要がある場合は決定的な生成方法を使ってください。
• イベントに対応した宣言的なインスタンスを手軽に使うには、Drei の Instances を使います。大量のインスタンスや頻繁に更新されるインスタンスでは、インスタンスごとの React オーバーヘッドを避けるため、ネイティブのインスタンシングを参照してください。
• インスタンシングはジオメトリとマテリアルを共有し、ドローコールを削減します。別々のメッシュ間でジオメトリを共有するだけでは、ドローコールはバッチ処理されません。
• Drei の Merged は メッシュからインスタンシングの抽象化を作成するものであり、BufferGeometry オブジェクトから作成するものではありません。任意の静的ジオメトリを結合することもありません。実際に結合するには、three/addons/utils/BufferGeometryUtils.js の mergeGeometries を確認し、属性とインデックスが互換であることを確かめてください。

宣言的なインスタンス

Canvas の下に、ライティングとともにマウントします。各 Instance は、最も近い Instances プロバイダーに属します。

import { Instance, Instances } from '@react-three/drei'

export default function Example() {
  return (
    <Instances limit={3} range={3}>
      <boxGeometry args={[0.7, 0.7, 0.7]} />
      <meshStandardMaterial />
      <Instance position={[-1.2, 0, 0]} color="coral" />
      <Instance position={[0, 0, 0]} color="skyblue" />
      <Instance position={[1.2, 0, 0]} color="gold" />
    </Instances>
  )
}

カスタムバッファーと更新

• position と normal 属性のアイテムサイズは通常 3、UV のアイテムサイズは 2 です。JSX のバッファー属性は args={[typedArray, itemSize]} と正しい attach を指定して構築してください。コンストラクター引数を指定せず、array／count プロパティだけを使うのは避けてください。
• インデックスは頂点を参照します。頂点の順序によって表面の向きが決まります。法線が不連続な箇所や UV シームでは頂点を複製してください。インデックス付きの頂点では、位置だけでなくすべての属性が共有されます。
• ライティングを適用するジオメトリには法線が必要です。適切な場合は computeVertexNormals() を使ってください。シェーダーや解析的な法線を使うほうが効率よく変形を表現できる場合は、毎フレーム再計算しないでください。
• CPU でバッファーを書き換えた後は、attribute.needsUpdate = true を設定してください。バッファーが頻繁に変化する場合は、最初に GPU へアップロードする前に動的使用を指定してください。
• ジオメトリの変更によってバウンディングボックスや球体に影響が出る場合は、それらを再計算してください。GPU での頂点変位では、CPU 側のバウンディングやレイキャストは自動更新されません。
• 最新の Three.js では UV の選択は明示的です。texture.channel で uv、uv1、uv2、uv3 を選択します。AO のために uv を無条件で uv2 にコピーしないでください。
• ポインターの移動に合わせてバッファーを再構築するのは避けてください。トポロジーが固定されている場合は、代わりに属性の内容やユニフォームを変更します。

ヘルパーとトレードオフ

• Drei の Line は便利な線幅をサポートします。ネイティブの WebGL の線幅はプラットフォームによって制限されます。画面空間とワールド空間のどちらの太さにするか選ぶ際は、worldUnits を確認してください。
• 平面テキストには Drei の Text、押し出しジオメトリには Text3D を使います。現在の TextGeometry で使うのは、以前の height ではなく depth です。インストールされているヘルパーの型とフォント形式を確認してください。
• 鋭いエッジの輪郭には Edges を使い、画面空間の選択エフェクトの代わりには使わないでください。
• Bounds と Center はフレーミングやトランスフォームを変更します。アセットの読み込み後、リサイズ後、または操作後に更新するかどうかを決めてください。
• セグメント数は、シルエット、変形、視距離に応じて決めます。「高品質」な固定数が常に優れているとは限りません。
• 宣言的に作成したジオメトリは R3F が所有できます。共有またはキャッシュされたジオメトリには、共有されたライフタイムが必要です。他のインスタンスがマウントされたままの状態で、あるインスタンスから破棄しないでください。

検証

更新後のバウンディングとカリング、レイキャストのヒット位置、リソースのクリーンアップ、ドローコールを確認してください。想定するオブジェクト数でテストしてください。インスタンスが 3 つでの結果だけでは、1 万個でのパフォーマンスは判断できません。

Sources

• BufferGeometry, BufferAttribute, InstancedMesh.
• Drei Instances, Merged, Text3D.