体积脚本 API

在高清渲染管线 (High Definition Render Pipeline, HDRP) 中，由体积控制场景中的环境设置。为了使您能够在运行时控制体积，HDRP 提供了 API 用于通过 C# 脚本创建、访问和编辑体积。本页介绍了如何使用脚本 API，并提供了一些示例来帮助您入门。您可能会注意到，体积覆盖（例如雾效）实际上继承自 VolumeComponent 类。为与用户界面一致并避免与 Volume 组件混淆，文档内将这些称为“体积覆盖”而不是“体积组件”。

修改现有的体积

体积将体积覆盖存储在体积配置文件中。因此，要修改体积覆盖的属性，必须首先获取体积配置文件。有两种方式可以做到这一点：

共享的体积配置文件访问

一种方法是访问体积的共享配置文件。您可以通过体积的 sharedProfile 属性来执行此操作。这为您提供了对体积配置文件资源实例的引用。如果修改此体积配置文件：

• HDRP 会将您所做的所有更改应用于使用此体积配置文件资源的每个体积。

• 您所做的修改会影响实际的体积配置文件资源，这意味着当您退出运行模式时不会重置所做的更改。

注意，如果体积不引用体积配置文件资源，则 sharedProfile 属性可以返回 null。

拥有的体积配置文件访问

另一种方法是克隆体积配置文件资源。这种方法的好处是您所做的修改只会影响您从中克隆体积配置文件的 Volume 组件，而不会影响使用同一体积配置文件资源的任何其他体积。为此，请使用体积的 profile 属性。这将返回对体积配置文件的新实例的引用（如果尚未创建）。如果您已经修改体积的 sharedProfile，则所做的任何更改都将复制到新实例中。如果修改此体积配置文件：

• HDRP 仅将更改应用于特定的体积。
• 当您退出运行模式时不会重置所做的更改。
• 不再需要重复的体积配置文件时由您自己负责销毁该配置文件。

请注意，您可以使用此属性为体积分配不同的体积配置文件。

更改体积配置文件属性

引用体积配置文件后，可以更改其中任何体积覆盖的属性。这与在 Inspector 中更改属性的方式相似。

首先，您需要使用配置文件上的通用 TryGet<> 函数来获取特定的体积覆盖。如果体积配置文件不包含特定的体积覆盖，并且 TryGet<> 函数返回 false，则可以使用 Add<> 函数来添加体积覆盖。

引用体积覆盖后，可以访问和修改其公共属性。为了使属性对场景产生影响，您需要指定它已被覆盖。这使得 HDRP 使用您指定的值，而不是使用默认值。体积覆盖中的每个属性都由两部分组成：

• 包含覆盖状态的布尔值。这是 overrideState。
• 属性的值本身。这是 value。

将属性的 overrideState 设置为 true 后，即可更改 value。

下面的示例更改了雾效体积覆盖的 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;

淡化体积

基于距离的体积混合非常适合用于许多设计用例，但您可能希望根据应用程序中的事件手动触发淡入/淡出效果。为此，请更新体积的 weight 属性。下面的示例在 MonoBehaviour 的 Update 方法中随时间改变 weight 属性。此示例根据应用程序启动以来的时间 Sin 函数使体积淡入和淡出，但您可以使用任何方法来更新 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);
        }
    }
}