SamplerType

DreamShader » Parameters » SamplerType

用于设置纹理节点如何解释其纹理的元数据键：位于生成的 UMaterialExpressionTextureBase 子类上的 EMaterialSamplerType。

概要

<texture-token> <name> [ = <default> ] [ SamplerType = "<value>" [ ; <entry> … ] ] ;

(自 2.0.0 起) SamplerType 在声明上有自己的一条路径：在紧凑纹理标记或 TextureObjectParameter 上，它会成为 2.0 的 /// @sampler 指令（去掉 SAMPLERTYPE_ 前缀），并由发射器的枚举字面量匹配器解析（当没有匹配时使用 DSH8235；空值则为 DSH7222）。在纹理采样标记上（会在其使用处展开），它是反射节点的参数，在源绑定时会根据引擎目录进行检查。

适用于生成的节点派生自 UMaterialExpressionTextureBase 的每个声明：

值

17 个值。每一行是一个枚举项；行中的所有四种拼写都会选择它，比较时会去除空格、_、-、:、. 和 / 并忽略大小写 — 因此 "linear color"、"Linear-Color" 和 "linearcolor" 与 LinearColor 是同一个值。

DistanceFieldFont 或 External 没有虚拟对应项。

[!NOTE] 在纹理采样标记上，该值会根据引擎目录列出的 17 个枚举项名称进行检查 (自 2.0.0 起)。若能规范化为其中之一（SAMPLERTYPE_Normal、linear color），则会以 DSH5278 警告被接受；而 DisplayName 若不是枚举项名称 — 例如 Virtual Mask — 则会被 DSH5215。在声明上，四种拼写都可用。

[!NOTE] 枚举项列表以哨兵值 SAMPLERTYPE_MAX 结尾。它不携带 Hidden 元数据，因此在声明上 [SamplerType="SAMPLERTYPE_MAX"] 和 [SamplerType="MAX"] 会直接解析而不会报错，并写入一个并非采样器类型的值。它不是可用值。纹理采样标记所检查的目录不列出它（DSH5215）。

推断与覆盖顺序

显式的 SamplerType 始终优先：具有该值的节点完全不会运行推断。省略该键意味着该值会跟随资产 — 如果资产的压缩设置发生变化，该值也会变化。

[!NOTE] 反编译器 始终显式发出 SamplerType，即使它与推断值相同，因此当资产稍后被重新压缩时，UMaterial → .dsm → UMaterial 的往返过程不会产生偏移。

SamplerSource

UMaterialExpressionTextureSample 子类上的伴随键 — 采样使用哪个采样器状态。它仅适用于纹理采样标记，因此其值会如上所述根据目录进行检查。

默认值为 FromTextureAsset。写入枚举项名称 — [SamplerSource="Wrap_WorldGroupSettings"]；SSM_Wrap_WorldGroupSettings 会以 DSH5278 被接受。显示名称 Shared: Wrap 和 Shared: Clamp 在目录中不会规范化为任何内容，且会被 DSH5215 (自 2.0.0 起；1.x 接受它们)。

相关纹理采样键

以下是反编译器在每个纹理采样参数上发出的键，以及它视为默认值的值。它们都是普通的反射元数据。

MipValueMode 是唯一会改变节点 引脚 名称的键，因而也会改变 调用形式在活动节点上可以匹配哪些名称。

维度验证与推断

SamplerType 描述的是解释方式；纹理的 维度 是另一项独立的检查。

TextureObjectParameter 的维度由其默认值所加载的资产读出：UTextureCube → TextureCube，UTexture2DArray → Texture2DArray，UVolumeTexture → VolumeTexture，其他任何值—— 或者默认值未加载——Texture2D。

[!WARNING] 一个 TextureSampleParameterCube 若通过纯对象路径指向 2D 纹理，会干净地生成， 随后在 Unreal 的着色器编译器中失败。参见 参数节点标记。

诊断

示例

Shader(Name="Docs/M_SamplerType")
{
    Properties = {
        // Explicit: linear data, shared sampler, no slot consumed.
        TextureSampleParameter2D MaskMap = Path(Game, "Textures/T_Mask") [
            SamplerType   = "LinearColor";
            SamplerSource = "Wrap_WorldGroupSettings";
            MipValueMode  = "None";
        ];

        // Inferred: SamplerType follows the asset's compression settings.
        TextureSampleParameter2D BaseMap = Path(Game, "Textures/T_Base");

        // A 1.x spelling: accepted, with DSH5278.
        TextureSampleParameterCube Env = Path(Engine, "EngineResources/DefaultTextureCube") [
            SamplerType = "linear color"
        ];

        const Texture2D Lut = Path(Game, "Textures/T_Lut") [SamplerType = "Data"];
    }

    Settings = { Domain = "Surface"; ShadingModel = "DefaultLit"; BlendMode = "Opaque"; }
    Outputs  = { vec3 Color; Base.BaseColor = Color; }

    Graph = {
        vec2 UV = UE.TexCoord(Index = 0);
        vec4 B  = BaseMap(Coordinates = UV);
        vec4 M  = MaskMap(Coordinates = UV);
        Color = B.rgb * M.r;
    }
}

应用后的值：

MaskMap  SamplerType = SAMPLERTYPE_LinearColor  SamplerSource = SSM_Wrap_WorldGroupSettings
BaseMap  SamplerType = <AutoSetSampleType from /Game/Textures/T_Base>
Env      SamplerType = SAMPLERTYPE_LinearColor  ("linear color" normalizes to LinearColor; DSH5278)
Lut      SamplerType = SAMPLERTYPE_Data         on a TextureObject (const) node

Env 和 Lut 在函数体读取它们时应用；此 Graph 不读取，因此它们不构建任何东西。

另请参阅

• 参数 — 枢纽与决策表
• 元数据块 — 此键遵循的枚举字面量规则
• 参数节点标记 — 哪些标记会公开 SamplerType
• 紧凑类型标记 — 五个紧凑纹理标记及其回退资产
• Path(…) — 资产引用语法
• 在图表中使用参数 — MipValueMode 如何改变可调用的引脚名称
• 反编译器 — 这些键的往返保证