볼륨 스크립팅 API

고해상도 렌더 파이프라인(HDRP)에서 볼륨은 씬의 환경 설정을 제어합니다. 런타임 시 볼륨을 제어할 수 있도록 HDRP는 C# 스크립팅을 통해 볼륨을 생성, 액세스, 편집하는 데 사용할 수 있는 API를 제공합니다. 이 페이지에서는 스크립팅 API를 사용하는 방법을 설명하며 시작하는 데 도움이 될 예시를 제공합니다. 안개와 같은 볼륨 오버라이드는 실제로 VolumeComponent 클래스에서 상속합니다. 이 문서에서는 사용자 인터페이스와 일치시키고 Volume 컴포넌트와 혼동하지 않도록 이를 Volume 컴포넌트가 아닌 볼륨 오버라이드라고 부릅니다.

기존 볼륨 수정

볼륨은 볼륨 프로파일에 볼륨 오버라이드를 저장합니다. 따라서 볼륨 오버라이드의 프로퍼티를 수정하려면 먼저 볼륨 프로파일을 검색해서 가져와야 합니다. 이렇게 하는 데 두 가지 방법이 있습니다.

공유 볼륨 프로파일 액세스

한 가지 방법은 볼륨의 공유 프로파일에 액세스하는 것입니다. 이 작업은 볼륨의 sharedProfile 프로퍼티를 통해 수행합니다. 이렇게 하면 볼륨 프로파일 에셋의 인스턴스에 레퍼런스가 제공됩니다. 이 볼륨 프로파일을 수정하려면 다음을 수행합니다.

HDRP는 이 볼륨 프로파일 에셋을 사용하는 모든 볼륨에 모든 변경 사항을 적용합니다.
수정 사항은 실제 볼륨 프로파일 에셋에 영향을 미치므로 플레이 모드를 종료할 때 초기화하지 않습니다.

sharedProfile 프로퍼티는 볼륨이 볼륨 프로파일 에셋을 참조하지 않는 경우 null을 반환할 수 있습니다.

자체 볼륨 프로파일 액세스

다른 방법은 볼륨 프로파일 에셋을 복제하는 것입니다. 이 방법의 장점은 수정 사항이 볼륨 프로파일을 복제하는 Volume 컴포넌트에만 영향을 미치며 동일한 볼륨 프로파일 에셋을 사용하는 다른 볼륨에는 영향을 미치지 않는다는 점입니다. 이렇게 하려면 볼륨의 profile 프로퍼티를 사용합니다. 이는 볼륨 프로파일의 새로운 인스턴스(아직 생성되지 않은 경우)에 레퍼런스를 반환합니다. 볼륨의 sharedProfile을 이미 수정한 경우 모든 변경 사항은 새로운 인스턴스로 복사됩니다. 이 볼륨 프로파일을 수정하려면 다음을 수행합니다.

HDRP는 특정 볼륨에만 변경사항을 적용합니다.
수정 사항은 플레이 모드를 종료할 때 초기화됩니다.
볼륨 프로파일 사본이 더 이상 필요하지 않을 때 이를 파기하는 책임은 전적으로 사용자에게 있습니다.

이 프로퍼티를 사용하여 볼륨에 다른 볼륨 프로파일을 할당할 수 있습니다.

볼륨 프로파일 프로퍼티 변경

볼륨 프로파일에 레퍼런스가 있으면 볼륨 오버라이드의 프로퍼티를 변경할 수 있습니다. 이는 인스펙터에서 프로퍼티를 변경하는 방법과 유사한 방법으로 작동합니다.

먼저 프로파일에서 일반 TryGet<> 함수를 사용하여 특정 볼륨 오버라이드를 검색해서 가져와야 합니다. 볼륨 프로파일에 특정 볼륨 오버라이드가 포함되어 있지 않고 TryGet<> 함수가 false를 반환하는 경우 Add<> 함수를 사용하여 볼륨 오버라이드를 추가할 수 있습니다.

볼륨 오버라이드에 레퍼런스가 있으면 공용 프로퍼티에 접근하고 수정할 수 있습니다. 프로퍼티가 씬에 영향을 주려면 오버라이드된 값을 지정해야 합니다. 이렇게 하면 HDRP는 기본값을 사용하지 않고 지정한 값을 사용합니다. 볼륨 오버라이드의 모든 프로퍼티는 다음과 같이 두 부분으로 이루어져 있습니다.

오버라이드 상태를 포함하는 부울. 여기에서는 overrideState라고 합니다.
프로퍼티 값. 여기에서는 value라고 합니다.

프로퍼티의 overrideState를 true로 설정한 다음 value를 변경할 수 있습니다.

다음 예시는 Fog 볼륨 오버라이드의 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 메서드에서 시간이 지날수록 가중치 프로퍼티를 변경합니다. 애플리케이션이 시작된 후 시간의 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);
		}
	}
}