Volume のスクリプティング API

HD レンダーパイプライン (High Definition Render Pipeline、HDRP) では、Volume (ボリューム) がシーンの環境を制御します。ランタイム時に Volume を制御できるよう、HDRP は C# スクリプティングを介して Volume を作成、アクセス、および編集できる API を提供します。このページでは、スクリプティング API の使用方法を解説し、使い始めるにあたって役立つ例を紹介します。Fog などの Volume Override が実際に VolumeComponent クラスから継承されていることに気づくでしょう。ドキュメントでは UI との一貫性を保ち Volume コンポーネントと混乱しないよう、これらを Volume コンポーネントではなく Volume Override (ボリュームオーバーライド) と呼びます。

既存の Volume の変更

Volumes は、Volume Profile 内に Volume Override を格納しています。そこで Volume Override のプロパティーを変更するには、まずは Volume Profile を取得する必要があります。この方法は 2 つあります。

共有 Volume Profile へアクセス

まず 1 つ目の方法は、Volume の共有 Profile にアクセスする方法です。これは Volume の sharedProfile プロパティーから行います。Volume Profile アセットのインスタンスを参照できます。この Volume Profile を変更する場合、

HDRP はこの Volume Profile アセットを使うすべての Volume に変更を適用します。
変更は実際の Volume Profile アセットに影響を与えます。つまり、再生モードを終了してもリセットしません。

Volume が Volume Profile アセットを参照しない場合、sharedProfile プロパティーが null を返す場合がありますので注意してください。

所有する Volume Profile へアクセス

2 つ目の方法は、Volume Profile アセットをクローンする方法です。この利点は、Volume Profile をクローンする Volume コンポーネントのみに影響を与え、同じ Volume Profile アセットを使うその他の Volume には影響を与えないことです。これは、Volume の profile プロパティーを使って行います。これは Volume Profile の新しいインスタンスの参照を返します (まだ作成されていない場合)。既に Volume の sharedProfile を変更している場合は、先の変更が新しいインスタンスにコピーされます。この Volume Profile を変更する場合、以下に注意してください。

HDRP は特定の Volume にのみ変更を適用します。
再生モードを終了すると変更はリセットします。
不要になった際には、自身の責任で Volume Profile の複製を破棄してください。

このプロパティーを使って異なる Volume Profile を Volume に割り当てることができます。

Volume Profile プロパティーの変更

Volume Profile への参照があるときには、中のすべての Volume Override のプロパティーを変更できます。これは Inspector でプロパティーを変更する方法に似ています。

まずジェネリック TryGet<> 関数をプロファイルで使って特定の Volume Override を取得する必要があります。Volume Profile に特定の Volume Override が含まれておらず、TryGet<> 関数が false を返す場合は、 Add<> 関数を使って Volume Override を追加します。

Volume Override への参照があるときには、パブリックプロパティーにアクセスおよび変更できます。シーンでプロパティーに効果を持たせるには、オーバーライドされたことを特定する必要があります。そうすると、HDRP がデフォルト値ではなく指定された値を使います。Volume Override のすべてのプロパティーは、二部構成になっています。

オーバーライドステートを含むブール、overrideState
プロパティー値そのもの、value

プロパティーの overrideState を true に設定したら、value を変更できます。

次の例は、Fog Volume Override の enabled プロパティーを変更します。

using UnityEngine.Rendering;
using UnityEngine.Rendering.HighDefinition;


public Volume m_Volume;
public bool enableFog;
public bool overrideFog;


VolumeProfile profile = m_Volume.sharedProfile;
if (!profile.TryGet<Fog>(out var fog))
{
    fog = profile.Add<Fog>(false);
}

fog.enabled.overrideState = overrideFog;
fog.enabled.value = enableFog;

Volume のフェード

距離ベースの Volume のブレンドは、多くのデザインのユースケースに便利ですが、アプリケーション内のイベントベースでフェードイン、フェードアウトエフェクトを手動で発生させたい場合があるでしょう。その場合は、Volume の weight プロパティーを更新します。下の例では、MonoBehaviour の Update メソッドで経時的にウェイトプロパティーを変更します。アプリケーションが開始してからの時間の Sin に基づいて Volume をフェードイン、およびフェードアウトしますが、好きなメソッドを使って weight を更新することができます。

using UnityEngine;
using UnityEngine.Rendering;

public class VolumeWeightSin : MonoBehaviour
{
    Volume m_Volume;
    void Update()
    {
        if (m_Volume != null)
        {
            m_Volume.weight = Mathf.Sin(Time.realtimeSinceStartup);
        }
    }
}