r3fの周辺ライブラリ学習メモ

2024/6/21

@react-three/drei

dreiはReact Three Fiber(r3f)のライブラリで、r3f用の便利なヘルパー関数やコンポーネントを提供してくれるライブラリ。

リポジトリ - https://github.com/pmndrs/drei

たくさんの機能があり、ここに用途や使い方などをまとめていく。

AccumulativeShadowsとRandomizedLight

指定したフレーム数の影を平面のオブジェクト上に蓄積してリアルで滑らかなソフトシャドウを作る。パーフォーマンスの面で優れている。

主にRandaomizedLightコンポーネントと組み合わせて使う。

RandomizedLight コンポーネントは、複数のライトのセットを揺らして、リアルなレイキャストのような影とアンビエントオクルージョンを作り出す。

<AccumulativeShadows
  temporal
  frames={100}
  alphaTest={0.85}
  scale={10}
  position={[0, 0, 0]}
>
  <RandomizedLight
    amount={8}
    radius={10}
    intensity={1}
    ambient={0.5}
    position={[5, 5, -10]}
    bias={0.001}
  />
</AccumulativeShadows>

AccumulativeShadows

主なプロパティ
- temporal: フレームごとに影を蓄積するかどうかを指定します。trueにすると高品質な影になりますが、計算コストが高くなる。
- frames: 蓄積するフレーム数を指定します。フレーム数が多いほど影が滑らかになるが、その分だけ時間がかかる。
- alphaTest: 閾値以下のアルファピクセルを削除
- scale: 平面のスケール
RandomizedLight

主なプロパティ
- amount: 光源の数。
- radius: ライトのjiggleの値、値が大きいほど柔らかい光になる
- intensity: 光の強度。
- ambient: アンビエントオクルージョン。
- position: 光源の位置。
- bias: シャドウのバイアスを設定。シャドウのアーティファクトを防ぐために使用。

Center

境界ボックスを計算し、それに応じて子要素をセンタリング。

<Center top left>
  <mesh />
</Center>

Decal

ThreeのDecalGeometryを抽象化したもの。デフォルトでは親メッシュをデカールサーフェスとして使用。

デカールボックスはサーフェスと交差する必要があり、交差しない場合は表示されない。

<mesh>
  <sphereGeometry />
  <meshBasicMaterial />
  <Decal
    debug // デバッグ用
    position={[0, 0, 0]}
    rotation={[0, 0, 0]}
    scale={1}
  >
    <meshBasicMaterial map={texture} polygonOffset polygonOffsetFactor={-1} />
  </Decal>
</mesh>

ScrollControls

ScrollControlsは、canvasの前面にHTMLスクロールコンテナを作成する。

<Scroll>コンポーネント内に置かれた要素はスクロールの影響を受ける。

useScrollHookを使うことで、スクロールオフセットなどのデータを取得することができる。

<ScrollControls pages={3} damping={0.1}>
  {/* 以下のCanvasコンテンツはスクロールしないが、useScrollを受け取る */}
  <SomeModel />
  <Scroll>
    {/*以下のCanvasコンテンツはスクロール */}
    <Foo position={[0, 0, 0]} />
    <Foo position={[0, viewport.height, 0]} />
    <Foo position={[0, viewport.height * 1, 0]} />
  </Scroll>
  <Scroll html>
    {/* 以下のCanvasコンテンツはスクロール */}
    <h1>html in here (optional)</h1>
    <h1 style={{ top: '100vh' }}>second page</h1>
    <h1 style={{ top: '200vh' }}>third page</h1>
  </Scroll>
</ScrollControls>

function Foo(props) {
  const ref = useRef()
  const data = useScroll()
  useFrame(() => {
    // data.offset = 現在のスクロール位置、0から1の間で変化し、減衰される
    // data.delta = 現在のデルタ値、0から1の間で変化し、減衰される

    // スクロールバーが開始位置にあるときに0になり、
    // スクロール距離の1/3に達するまで1に増加する
    const a = data.range(0, 1 / 3)
    // スクロール距離の1/3に達すると増加し始め、
    // 2/3に達すると1に到達する
    const b = data.range(1 / 3, 1 / 3)
    // 両端に0.1のマージン
    const c = data.range(1 / 3, 1 / 3, 0.1)
    // 選択された範囲で0-1-0の間で移動
    const d = data.curve(1 / 3, 1 / 3)
    // 両端に0.1のマージン
    const e = data.curve(1 / 3, 1 / 3, 0.1)
    // オフセットが範囲内にある場合はtrueを返し、範囲外の場合はfalseを返す
    const f = data.visible(2 / 3, 1 / 3)
    // visible関数にはマージンも指定できる
    const g = data.visible(2 / 3, 1 / 3, 0.1)
  })
  return <mesh ref={ref} {...props} />
}

プロパティ

eps:number 精度
horizontal:boolean 水平スクロール
infinite:boolean 無限スクロール
pages:number スクロールエリアの長さを定義、各ページは高さ100%
distance:number スクロールバーの移動距離を増加させる係数
damping:number 摩擦の係数
maxSpeed:number 最大速度を制限

Billboard

常にカメラを向いている<group />を追加する。

<Billboard
  follow={true}
  lockX={false}
  lockY={false}
  lockZ={false} // z軸の回転をロック (default=false)
>
  <Text fontSize={1}>I'm a billboard</Text>
</Billboard>

maath

three.js向けの数学ヘルパーのライブラリ

リポジトリ - https://github.com/pmndrs/maath

Easing

Game Programming Gems 4 Chapter 1.10に基づくUnity-smooth-damping関数。これらは、THREE.Vector2D、3D、4D、オイラー（最短経路）、Matrix4、Quaternion、Colorにプリミティブ化された、高速で、リフレッシュレートに依存しない、中断可能なアニメーションプリミティブです。

easingを使うことで、様々な動きにイージングをつけることができる。

import {
  damp, // for string
  damp2, // for Vector2
  damp3, // for Vector3
  damp4, // for Vector4
  dampE, // for Euler
  dampM, // for Matrix4
  dampQ, // for Quaternion
  dampS, // for Spherical
  dampC, // for Color
} from "maath/easing";

useFrame((state, delta) => {
  // mesh.positionを[0, 1, 2]に
  damp3(mesh.position, [0, 1, 2], 0.25, delta);

  // マテリアルの色を変化
  dampC(mesh.material.color, "green", 0.25, delta);

  // mesh.rotationを[Math.PI / 2, 0, 0]に
  dampE(mesh.rotation, [Math.PI / 2, 0, 0], 0.25, delta);
});

back

r3fの周辺ライブラリ 学習メモ