ShaderLab: 패키지 요구 사항 지정하기

일부 셰이더는 동시에 여러 개의 렌더 파이프라인을 지원해야 합니다. 서브셰이더와 패스에 패키지 요구 사항을 추가하면 셰이더 코드가 설치되지 않은 패키지의 include 파일을 사용하거나 컴파일에 특정한 패키지 버전을 필요로 하는 경우 컴파일 오류가 발생하는 일을 방지할 수 있습니다.

렌더 파이프라인 호환성

PackageRequirements 블록 사용

서브셰이더나 패스의 패키지 요구 사항을 지정하려면 PackageRequirements 블록을 사용해야 합니다. ShaderLab은 서브셰이더 또는 패스당 하나의 PackageRequirements 블록을 지원하지만, 각 블록은 여러 개의 패키지 요구 사항을 지정할 수 있습니다.

참고: PackageRequirements 블록을 제공하는 경우, PackageRequirements 블록은 서브셰이더나 패스의 여타 모든 선언 전에 이루어져야 합니다.

여러 가지 방법으로 패키지 요구 사항을 선언할 수 있습니다. 각 방법은 다음과 같이 다른 동작을 제공합니다.

• “<package name>”: 서브셰이더나 패스가 모든 버전의 패키지와 작동하도록 지정합니다.
• “<package name>”: “<version restrictions>”: 서브셰이더나 패스가 패키지 버전의 하위 세트와만 작동하도록 지정합니다.
• “<package name>”: “unity=<version restrictions>”: 서브셰이더나 패스가 Unity 버전의 하위 세트와만 작동하며, 특정한 이름의 패키지를 요구하도록 지정합니다.
• “unity”:“<version restrictions>”: 서브셰이더나 패스가 Unity 버전의 하위 세트와만 작동하도록 지정합니다.

버전 제한은 버전 범위를 정의합니다. 요구된 패키지의 설치 버전이 범위 내에 없으면 패키지 요구 사항이 충족되지 않은 것입니다. 마찬가지로 요구 사항에 Unity 버전 제한이 지정된 경우, 현재 Unity 버전에도 동일한 사항이 적용됩니다. 버전 제한 구문에 대해 자세히 알아보려면 버전 구문을 참조하십시오.

서브셰이더나 패스가 프로젝트가 충족하지 않는 패키지 요구 사항을 선언하는 경우, Unity는 해당 서브셰이더나 패스를 추가 처리 및 컴파일에서 제외합니다. 프로젝트가 요구된 패키지를 포함하지 않거나, 요구된 패키지를 포함하나 호환되는 버전이 없는 경우 이러한 일이 발생합니다. 셰이더가 요구 사항을 충족하는 서브셰이더를 하나도 포함하지 않는 경우, 또는 요구 사항을 충족하는 패스를 포함하는 서브셰이더가 없는 경우 콘솔 창이 경고 메시지를 표시합니다.

버전 구문

ShaderLab 패키지 요구 사항에서, 버전은 major.minor 또는 major.minor.patch 형식을 사용합니다. major.minor만 사용하는 경우, Unity는 patch에 0을 사용합니다. 패키지 버전은 -preview 또는 -preview.n 포스트픽스를 사용할 수 있으며, 여기서 -preview는 -preview.0과 동등합니다. 프리뷰 버전은 프리뷰 외 버전보다 전에 출시되므로, 1.2.3-preview.4는 1.2.2 이후, 1.2.3 전에 출시됩니다.

여러 가지 방법으로 버전 범위를 지정할 수 있습니다. 각 방법은 다음과 같이 다른 동작을 제공합니다.

• <version>: 입력한 버전과 해당 버전 후 모든 버전을 포함합니다. 예를 들어, 1.2.3은 1.2.3으로 시작하는 모든 버전을 포함합니다.
• [<version>]: 정확한 버전을 지정합니다. 예를 들어, [1.2.3]은 버전 1.2.3만 포함합니다.
• [<version1>,<version2>]: <version1>부터 <version2>까지의 범위를 지정합니다. 대괄호를 사용하면 해당 범위가 버전에 포함되며, 소괄호를 사용하면 해당 범위가 버전에서 제외됩니다. 여는 괄호는 <version1>에 영향을 미치며, 닫는 괄호는 <version2>에 영향을 미칩니다. 예: [1.2.3,2.3.4)는 버전 1.2.3부터 버전 2.3.3까지의 모든 버전을 포함합니다.

단일 패키지에 대해 버전 범위 세트를 지정할 수도 있습니다. 개별 범위에서 버전 범위 세트를 만들려면 세미콜론으로 구분하십시오. 예를 들어, [2.0,3.4.5];[3.7];4.0은 버전 2.0.0부터 버전 3.4.5까지, 버전 3.7.0, 그리고 버전 4.0.0 이상을 포함합니다.

패키지의 버전을 설정할 때는 다음에 유의하십시오.

• 버전, 버전 범위와 버전 범위 세트에 추가 글자를 포함해서는 안 됩니다.
• 버전 범위는 비워둘 수 없습니다.
• 버전 범위 세트는 교차해서는 안 됩니다.
• Package requirements are sensitive to whitespace.

구문이 상기 사항을 준수하지 않으면 버전 제한이 잘못됩니다. 패키지 요구 사항이 잘못되는 경우 어떤 일이 발생하는지 알아보려면 오류 점검을 확인하십시오.

예제

다음 코드 예제는 서브셰이더와 패스 모두에서 패키지 요구 사항을 지정하는 방법을 나타냅니다. 서브셰이더는 “com.my.package”라는 패키지의 단일 패키지 요구 사항을 선언하며, 이 패키지의 버전 2.2.0 이상 모든 버전과 작동합니다. 서브셰이더에는 두 개의 패스가 있습니다.

• 첫 번째 패스의 요구 사항은 다음과 같습니다.

• 버전 10.2.1 - 버전 11.0의 유니버설 렌더 파이프라인 패키지

• 버전 3.2 이상의 텍스트 메시 프로 패키지

• 두 번째 패스의 요구 사항은 다음과 같습니다.

• 버전 8.0 - 버전 8.5의 고해상도 렌더 파이프라인 패키지

Shader "Examples/ExampleShader"
{
    SubShader
    {
        PackageRequirements
        {
            "com.my.package": "2.2"
        }
        Pass
        {
            PackageRequirements
            {
                "com.unity.render-pipelines.universal": "[10.2.1,11.0]"
                "com.unity.textmeshpro": "3.2"
            }
        }
        Pass
        {
            PackageRequirements
            {
                "com.unity.render-pipelines.high-definition": "[8.0,8.5]"
            }
        }
    }
}

오류 점검

절대 충족될 수 없는 패키지 요구 사항을 정의하면 셰이더 임포트 프로세스가 실패하며 오류가 발생합니다. 이 섹션은 일반적인 잘못된 패키지 요구 사항 정의의 예제를 나타냅니다.

변형된 버전 또는 빈 패키지 이름

PackageRequirements {
  "com.some.package.x": "[10.2.1,9.0]"        // Error, empty version range
  "com.some.package.y": "[10.2.1.9,11.0]"     // Error, incorrect version format
  "com.some.package.z": "[2.3,3.5],[3.0,4.0]" // Error, ranges intersect
  "com.some.package.z" : "[10.2.1,11.0]"      // Error, extra whitespace after the package name
  "" : "[2.3.4,3.4.5]"                        // Error, no package name provided
}

같은 패키지에 여러 개의 종속성 존재

PackageRequirements {
  "com.some.package.x": "[10.2.1,11.0]"
  "com.some.package.x": "[11.2.1,12.0]" // Error, dependency on "com.some.package.x" declared twice
  "unity" : "2021.2"
  "unity" : "2021.3" // Error, dependency on Unity version declared twice
}

충돌하는 종속성 선언

PackageRequirements {
  "com.some.package.x": "unity=[2021.2.1,2021.3.3]"
  "unity" : "2021.2"    // Error: Unity version requirement cannot be declared on a package and on its own simultaneously
}

서브셰이더와 패스 간 충돌하는 종속성 선언

SubShader {
  PackageRequirements {
    "com.some.package.x": "[2.3.4,3.4.5]"
    "com.some.package.z": "[1.1,3.2]"
    "unity": "2021.2"
  }
  Pass {
    PackageRequirements {
      "com.some.package.y": "[1.2.2,2.5]"               // Fine, SubShader doesn’t declare a dependency on "com.some.package.y"
      "com.some.package.z": "[2.0,3.1]"                 // Fine, SubShader dependency intersects the provided version range
      "com.some.package.x": "[1.1.1, 2.2.2]"            // Error, SubShader version range for "com.some.package.x" does not intersect the provided range
      "com.some.package.w": "unity=[2021.2.1,2021.2.5]" // Fine, SubShader dependency intersects the provided version range
      "com.some.package.u": "unity=[2020.2.1,2020.2.5]" // Error, SubShader Unity version range does not intersect the provided range
    }
  }
}