Объявление и использование ключевых слов шейдера в HLSL

Эта страница содержит информацию о работе с шейдеромпрограммой, работающей на графическом процессоре. Подробнее
Просмотреть в Словарь ключевые слова в коде HLSL. Общие сведения о ключевых словах шейдеров см. в разделе Ключевые слова шейдеров. Для получения информации об объявлении и использовании ключевых слов шейдера в Shader Graph см. Ключевые слова.

В коде HLSL используйте директивы #pragma для объявления ключевых слов шейдера и директивы #if, чтобы указать, что раздел кода шейдера зависит от состояния ключевого слова шейдера. Ключевые слова шейдера можно использовать в обычных графических шейдерах (включая поверхностные шейдерыупрощенный способ написания шейдеров для встроенного конвейера рендеринга. Подробнее
См. в Словарь) и compute шейдеры.

Объявление ключевых слов шейдера

Чтобы объявить ключевые слова шейдера, используйте одну из следующих директив #pragma в коде HLSL:

Утверждение	Описание
#pragma multi_compile	Объявляет набор ключевых слов. По умолчанию эти ключевые слова имеют глобальную область действия и влияют на все этапы шейдера. Процесс сборки включает все ключевые слова из этого набора.
#pragma shader_feature	Объявляет набор ключевых слов, а также указывает компилятору компилировать варианты, в которых ни одно из этих ключевых слов не включено. По умолчанию эти ключевые слова имеют глобальную область действия и влияют на все этапы шейдера. В процессе сборки используются ключевые слова из этого набора, которые используются во время сборки.

Информацию о разнице между #pragma multi_compile и #pragma Shader_feature, а также рекомендации о том, когда какую из них использовать, см. см. ключевые слова шейдера.

Примечание. Если вы добавите шейдер в список Всегда включаемые шейдеры в графике окна настроек, Unity включает все ключевые слова из всех наборов в сборке, даже если они были объявлены с помощью #pragma Shader_feature.

Вы также можете добавить суффиксы к этим директивам, чтобы изменить их поведение:

• Добавьте _local, чтобы указать, что набор ключевых слов имеет локальную область действия и не может быть переопределен глобальными ключевыми словами; в противном случае ключевые слова имеют глобальную область действия и могут быть переопределены глобальными ключевыми словами. Дополнительные сведения см. в разделе Ключевые слова шейдера: глобальная и локальная область действия.

  Этот суффикс можно добавить к директивам #pragma multi_compile или #pragma Shader_feature; например, допустимы #pragma multi_compile_local и #pragma Shader_feature_local.

• Добавить _vertex, _fragment, _hull, _domain, _geometry или _raytracing, чтобы указать, что набор ключевых слов влияет только на данный шейдер. stage, что может уменьшить количество ненужных вариантов шейдера. Дополнительные сведения см. в разделе Ключевые слова шейдера: ключевые слова для этапа.

  Эти суффиксы можно добавить в директивы #pragma multi_compile или #pragma Shader_feature, либо отдельно, либо после _local; например, допустимы #pragma multi_compile_vertex и #pragma shaper_feature_local_fragment.

Кроме того, есть несколько «быстрых» вариантов #pragma multi_compile, которые добавляют предопределенные наборы ключевых слов. Дополнительную информацию об этом см. в разделе быстрые команды multi_compile.

Объявление набора ключевых слов

Вы объявляете ключевые слова наборами. Набор содержит взаимоисключающие ключевые слова.

Чтобы объявить набор ключевых слов, используйте директиву #pragma multi_compile или #pragma_shader_feature, за которой следует разделенный пробелом список ключевых слов.

В этом примере показано, как объявить набор из четырех ключевых слов:

#pragma multi_compile QUALITY_LOW QUALITY_MEDIUM QUALITY_HIGH QUALITY_ULTRA

Внутренне это работает с помощью директив #define. Когда Unity компилирует шейдер, он генерирует четыре варианта: один с определением QUALITY_LOW, один с определением QUALITY_MEDIUM, один с определением QUALITY_HIGH и один с определением QUALITY_ULTRA. Во время выполнения Unity использует соответствующий вариант в зависимости от того, какое из этих ключевых слов включено.

Когда вы используете #pragma shader_feature для объявления набора ключевых слов, Unity также компилирует вариант, в котором ни одно из ключевых слов в этом наборе не определено. Это позволяет вам определять поведение без использования дополнительного ключевого слова. Сокращение количества ключевых слов полезно по нескольким причинам: оно может уменьшить общее количество вариантов, компилируемых Unity, что улучшает как время сборки, так и производительность во время выполнения; он уменьшает общее количество ключевых слов, используемых шейдером, что предотвращает превышение пределов ключевых слов шейдера; а также упрощает управление состоянием ключевых слов из сценариев C#, поскольку количество ключевых слов для включения и отключения меньше.

В этом примере показано, как объявить набор, содержащий только одно ключевое слово:

#pragma shader_feature EXAMPLE_ON

Вы также можете указать Unity сделать это при использовании #pragma multi_compile. Для этого добавьте в набор «пустое» ключевое слово с именем, состоящим из одного или нескольких символов подчеркивания (_), например так:

#pragma multi_compile __ EXAMPLE_ON

Объявление нескольких наборов ключевых слов

Вы можете объявить несколько наборов ключевых слов для представления различных функций. Для этого используйте несколько директив #pragma multi_compile или #pragma_shader_feature.

В этом примере показано, как объявить один набор из четырех ключевых слов и другой набор из трех ключевых слов:

#pragma multi_compile QUALITY_LOW QUALITY_MEDIUM QUALITY_HIGH QUALITY_ULTRA #pragma multi_compile COLOR_RED COLOR_GREEN COLOR_BLUE

Ограничения

Существуют некоторые ограничения на объявление наборов ключевых слов:

• Вы не можете включать одно и то же ключевое слово более одного раза в один и тот же набор; однако вы можете объявить одно и то же ключевое слово в разных наборах.
• Вы не можете объявить один и тот же набор ключевых слов в шейдерной программе более одного раза.
• Существует ограничение на количество ключевых слов, которые может использовать шейдер. Каждое ключевое слово, объявленное в исходном файле шейдера, и его зависимости
  См. в Словарь учитываются в этом пределе. Дополнительную информацию см. в разделе ограничения ключевых слов шейдера.

Использование ключевых слов шейдера

Чтобы скомпилировать код, который используется только тогда, когда заданное ключевое слово шейдера включено, вы используете директиву #if, например:

// Declare a set of keywords #pragma multi_compile QUALITY_LOW QUALITY_MEDIUM QUALITY_HIGH QUALITY_ULTRA #if QUALITY_ULTRA // Code here is compiled for variants that are used when the keyword QUALITY_ULTRA is enabled #endif

В Unity директивы #if работают так же, как и в стандартном HLSL. Дополнительные сведения о директивах #if см. в документации по HLSL: директивы if, elif, else и endif.

Кроме того, директивы #pragma require и #pragma target могут принимать ключевые слова в качестве параметров, чтобы они применялись только к варианты, в которых заданные ключевые слова включены. Дополнительную информацию см. в разделе Нацеливание моделей шейдеров и функций GPU в HLSL.

быстрые команды для нескольких компиляций

Unity предоставляет несколько сокращенных обозначений для объявления ключевых слов шейдера.

Следующие сочетания клавиш относятся к свету, теням и картам освещения во встроенном конвейере рендеринга:

• multi_compile_fwdbase добавляет следующий набор ключевых слов: DIRECTIONAL LIGHTMAP_ON DIRLIGHTMAP_COMBINED DYNAMICLIGHTMAP_ON SHADOWS_SCREEN SHADOWS_SHADOWMASK LIGHTMAP_SHADOW_MIXING LIGHTPROBE_SH. Эти варианты необходимы для PassType.ForwardBase.
• multi_compile_fwdbasealpha добавляет следующий набор ключевых слов: DIRECTIONAL LIGHTMAP_ON DIRLIGHTMAP_COMBINED DYNAMICLIGHTMAP_ON LIGHTMAP_SHADOW_MIXING VERTEXLIGHT_ON LIGHTPROBE_SH. Эти варианты необходимы для PassType.ForwardBase.
• multi_compile_fwdadd добавляет следующий набор ключевых слов: POINT DIRECTIONAL SPOT POINT_COOKIE DIRECTIONAL_COOKIE. Эти варианты необходимы для PassType.ForwardAdd.
• multi_compile_fwdadd_fullshadows добавляет следующий набор ключевых слов: POINT DIRECTIONAL SPOT POINT_COOKIE DIRECTIONAL_COOKIE SHADOWS_DEPTH SHADOWS_SCREEN SHADOWS_CUBE SHADOWS_SOFT SHADOWS_SHADOWMASK LIGHTMAP_SHADOW_MIXING. Это то же самое, что и multi_compile_fwdadd, но добавляет возможность создавать тени в реальном времени для источников света.
• multi_compile_lightpass добавляет следующий набор ключевых слов: POINT DIRECTIONAL SPOT POINT_COOKIE DIRECTIONAL_COOKIE SHADOWS_DEPTH SHADOWS_SCREEN SHADOWS_CUBE SHADOWS_SOFT SHADOWS_SHADOWMASK LIGHTMAP_SHADOW_MIXING. По сути, это универсальный ярлык для всех функций, связанных со светом и тенями в реальном времени, кроме световых зондовхранилища световых зондов. информацию о том, как свет проходит через пространство в вашей сцене. Набор световых зондов, расположенных в заданном пространстве, может улучшить освещение движущихся объектов и статических пейзажей LOD в этом пространстве. Подробнее
  См. в Словарь.
• multi_compile_shadowcaster добавляет следующий набор ключевых слов: SHADOWS_DEPTH SHADOWS_CUBE. Эти варианты необходимы PassType.ShadowCaster.
• multi_compile_shadowcollector добавляет следующий набор ключевых слов: SHADOWS_SPLIT_SPHERES SHADOWS_SINGLE_CASCADE. Он также компилирует варианты без каких-либо из этих ключевых слов. Эти варианты необходимы для теней на экране.
• multi_compile_prepassfinal добавляет следующий набор ключевых слов: LIGHTMAP_ON DIRLIGHTMAP_COMBINED DYNAMICLIGHTMAP_ON UNITY_HDR_ON SHADOWS_SHADOWMASK LIGHTPROBE_SH. Он также компилирует варианты без каких-либо из этих ключевых слов. Эти варианты необходимы для PassType.LightPrePassFinal и PassType.Deferred .

Следующие сочетания клавиш относятся к другим настройкам:

• multi_compile_particles добавляет это ключевое слово, относящееся к встроенной системе частицкомпоненту, который моделирует текучие объекты, такие как жидкости, облака и пламя, создавая и анимируя большое количество небольших 2D-изображений в сцене. Подробнее
  См. в Словарь: SOFTPARTICLES_ON. Он также компилирует варианты без этого ключевого слова. Дополнительную информацию см. в разделе Встроенная система частиц.
• multi_compile_fog добавляет этот набор ключевых слов, относящихся к туману: FOG_LINEAR, FOG_EXP, FOG_EXP2. Он также компилирует варианты без каких-либо из этих ключевых слов. Вы можете управлять этим поведением в окне Настройки графики.
• multi_compile_instancing добавляет ключевые слова, относящиеся к созданию экземпляров. Если шейдер использует процедурное создание экземпляров, он добавляет следующий набор ключевых слов: INSTANCING_ON PROCEDURAL_ON. В противном случае добавляется это ключевое слово: INSTACING_ON. Он также компилирует варианты без каких-либо из этих ключевых слов. Вы можете управлять этим поведением в окне Настройки графики.

Большинство этих ярлыков содержат несколько ключевых слов. если вы знаете, что они не нужны проекту, вы можете использовать #pragma skip_variants, чтобы удалить некоторые из них. Например:

#pragma multi_compile_fwdadd #pragma skip_variants POINT POINT_COOKIE

Это говорит компилятору удалить ключевые слова POINT или POINT_COOKIE из других директив.