Unity ShaderGraph Custom Function & Node 제작 가이드

개요

• Unity ShaderGraph에서 Custom Function & Custom Node 제작 방법을 설명합니다.
• Custom Function은 별도 hlsl 텍스트 파일을 참조하는 방식 기반으로 기본적인 네이밍 규칙 및 ShaderGraph와 연동 방법을 설명합니다.
• Custom Node은 내장 노드와 같이 별도 노드를 제작하는 방법을 설명합니다.

*Unity 2022.3.38f1 기준 정보입니다.

 

Custom Function HLSL 제작 및 연동

ShaderGraph에서 Custom Function 노드 생성 후, hlsl 텍스트 파일을 참조 할 수 있습니다.

Custom Function 노드에서 직접 셰이더 코드를 작성 할 수 있지만, 에디터에서 코드 작성하는 것이 편합니다.

 

hlsl 코드 기본 구조

다음, Custom Function에 사용되는 hlsl 코드 기본 구조입니다.

1. ifndef 코드는 보통 중복 include 선언 방지용 디파인문입니다, 구지 안써도 상관 없지만 해당 hlsl 파일을 다른 파일에서 include 선언 대응용으로 작성합니다.
2. 함수 네이밍은 "함수이름_half" & "함수이름_float" 2가지를 작성합니다. 함수 네이밍은 자유롭게 작성해도 상관 없습니다, 함수 이름 뒤에 자료형은 반드시 아래 규칙과 동일하게 작성 필요합니다.

 

함수 자료형은 Custom Function Node의 Precision(정밀도) 메뉴와 연동되는 부분이며 Single로 세팅하는 경우 "함수이름_float" 함수가 호출되는 방식입니다.

 

일반적으로 2가지 자료형 함수를 전부 작성하기 때문에 아래와 같이 기능 구현 부분을 별도 함수로 분리하면 코드 관리 효율이 증가합니다.
(구현 내용 자료형은 define문으로 관리 가능)

 

Custom Function 노드에 HLSL 연동하기

다음, Custom Function 노드에 hlsl 연동 과정입니다. 이 부분에서 규칙이 맞지 않으면 에러가 발생하니 참고합니다.

1. Source 항목에 hlsl 파일을 참조합니다.
2. Name 항목에 hlsl에 구현한 함수 이름을 작성합니다, 이때 _float & _half 자료형 글자를 제외하고 작성합니다.
3. Inputs & Outputs 항목에 함수 인자 값과 동일한 자료형으로 세팅합니다. 
   이름은 자유롭게 작성해도 되지만 자료형은 완벽히 동일해야합니다.

 

위 과정까지 진행하면 Custom Function이 정상 동작됩니다.

 

 

텍스처 샘플링 Custom Function 제작

다음, ShaderGraph가 아닌 Custon Function에서 텍스처 샘플링하는 방법 설명합니다.

 

기존에 작성하던 hlsl파일에 다른 함수를 추가로 작성해서 사용 가능합니다, CustomFunction에서 Name 항목에 작성한 함수 이름을 호출하는 방식입니다.

hlsl 파일에서는 샘플링을 위한 다른 hlsl 파일을 include 및 샘플링 코드를 작성합니다.

 

일반적으로 텍스처 파라미터는 Texture2D & TEXTURE2D 자료형을 사용하지만, 위 코드에서는 UnityTexture2D 자료형을 사용합니다. UnityTexture2D 자료형은 Custom Function 노드 파라미터 항목의 Texture2D와 연동되는 구조체 변수입니다.

 

UnityTexture2D 구조체에는 Texture2D와 SamplerState 변수 등이 포함되어 있어, 텍스처의 샘플러 정보가 같이 전달됩니다. UnityTexture2D.tex & .samplerstate 코드 작성으로 사용 가능합니다.

*변수 이름을 "texture" & "sampler" 문자를 사용하면 에러 발생합니다.

 

마지막 노드 연동 부분입니다, Custom Function 노드 부분은 앞선 내용과 동일하며, 그 외 텍스처 노드에서 UV 정보를 꺼내서 제작한 노드에 사용합니다.

여기서 언급한 UV 정보는 Material GUI에 보이는 Tile & Offset 값입니다.

 

 

텍스처 샘플링 Custom Function 제작 - 별도 샘플러 사용

다음, 앞선 내용과 동일하지만 텍스처 샘플링 정보가 아닌 별도 샘플링 정보를 사용하는 방법입니다.

 

hlsl 코드는 UnityTexture2D가 아닌 TEXTURE2D & SAMPLER 자료형을 사용합니다.

 

Custom Function 노드에서는 Bare Texture2D & Bare Sampler State 자료형을 사용합니다.

 

마지막으로 아래와 같이 노드 연결하면 동작합니다.

 

 

 

Custom Node 제작

Create Node에서 검색되며 활용 가능한 Custom Node 제작 방법 설명합니다.

Custom Function과 같이 노드 제작 후 별도 세팅 필요 없이 내장 노드와 같이 사용 가능 한 것이 장점입니다.

하지만 복잡한 기능은 제작하기 어렵습니다.

 

Assembly Definition Reference 생성

먼저 Custom Node 제작에 필요한 API는 URP Internal로 구현되어 있어 기본적으로 함수 접근이 되지 않습니다.

그래서 URP 패키지 내부 코드로 인식될 수 있는 Assembly Difinition Reference 기능을 활용합니다.

1. 프로젝트 Assets 폴더 내부에 "Editor" 폴더 생성합니다. (이름 틀리면 안됩니다)
2. Project탭에서 아래 메뉴를 통해 Assembly Difinition Reference파일을 생성 후 Unity.ShaderGraph.Editor을 선택합니다.
   • Project/Create/Assembly Difinition Reference 

 

 

스크립트 생성 & 기본 구현

"노드이름"+"Node 이름으로 C# 스크립트를 생성합니다.

 

아래는 Grayscale 커스텀 노드 스크립트입니다. 코드 작성 방법은 매우 까다롭기 때문에 자세한 문법은 생략하고 중요 규칙만 설명합니다. 다른 코드 예제는 URP 패키지를 참고하세요.

1. 클래스 이름 & Node 이름 문자열 규칙이 일치해야합니다.
2. static string 클래스에서 노드에 표시되는 input & output을 설정합니다.
3. static string 클래스 return 값은 셰이더 코드 문자열입니다. 즉 이 부분에 문자열로 셰이더 코드를 작성해야합니다.
4. 셰이더 문자열 코드를 ShaderGraph Core부분에서 파싱해서 코드 생성 방식으로 동작합니다.
5. 이곳에 작성하는 셰이더 코드는 문법이 조금 다릅니다. $precision은 float을 의미합니다, $precision3은 float3을 의미합니다.
6. dot, mul과 같은 기초 연산 함수는 기본적으로 지원하지만, 그외 include가 필요하거나 커스텀 함수 작성은 매우 복잡합니다. 

using System.Reflection;
using UnityEngine;

namespace UnityEditor.ShaderGraph
{
    [Title("CustomNode", "GrayscaleColor")]     // Create Node 계층
    class GrayscaleColorNode : CodeFunctionNode
    {
        public GrayscaleColorNode()
        {
            name = "GrayscaleColor";        // Node 이름
        }

        protected override MethodInfo GetFunctionToConvert()
        {
            return GetType().GetMethod("GrayscaleColor", BindingFlags.Static | BindingFlags.NonPublic);
        }

        static string GrayscaleColor(
            [Slot(0, Binding.None)] ColorRGB color,
            [Slot(1, Binding.None)] out Vector1 Out)
        {
            return 
@"
{
    $precision luma = dot(color, $precision3(0.2126729, 0.7151522, 0.0721750));
    Out = luma.x;
}
";
        }
    }
}