格式

#pragma stencil_args [SARGS] [VALUE]

描述

您需要在执行 stencil 命令并通过该命令启用 模板测试（Stencil Test）才能执行此命令。

执行此命令用于配置 模板测试（Stencil Test），以及配置渲染系统写入 模板缓冲区（Stencil Buffer）的内容。通常可用于制作镜面反射和描边等效果。

字段

字段名	是否必须	字段值	描述
[SARGS]	是	ref	用于设定 参考值（Reference）。这个值将用来基于 comp 参数中定义的比较方式与 模板缓冲（Stencil Buffer）中的值进行比较。
		readMask	渲染系统在执行 模板测试（Stencil Test）时使用此参数值作为遮罩，指仅比较该遮罩换做二进制时值为 1 对应位数的值。 例如，值为 3 表示 模板测试（Stencil Test）中仅比较第 1、2 位的数值。
		writeMask	渲染系统在写入 模板缓冲（Stencil Buffer）时使用该值作为遮罩，指仅写入该遮罩换做二进制时值为 1 对应位数的值。 例如，值为 3 表示写入操作中仅包含第 1、2 位的数值。
		comp	定义每个像素的 参考值（ref）与 模板缓冲（Stencil Buffer）值的比较方式。
		pass	当像素通过 模板测试（Stencil Test）和 深度测试（Z Test）时，渲染系统在 模板缓冲区（Stencil Buffer）上执行的操作。
		fail	当像素未通过 模板测试（Stencil Test）时，渲染系统对 模板缓冲区（Stencil Buffer）执行的操作。
		zFail	当像素通过 模板测试（Stencil Test）但未通过 深度测试（Z Test）时，渲染系统对 模板缓冲区（Stencil Buffer）执行的操作。
[VALUE]	是	< 自定义参数值 >	根据 [SARGS] 字段的参数定义对应参数的值，其中： · ref 参数值为 0 至 255 之间的整数，默认值为 255。 · readMask 参数值为 0 至 255 之间的整数，默认值为 255。 · writeMask 参数值为 0 至 255 之间的整数，默认值为 255。 · comp 参数值可参阅 比较操作值 小节中 [VALUE] 字段的值，默认值为 always 。 · pass 参数值可参阅 模板测试操作 小节中 [VALUE] 字段的值，默认值为 keep。 · fail 参数值可参阅 模板测试操作 小节中 [VALUE] 字段的值，默认值为 keep。 · zFail 参数值可参阅 模板测试操作 小节中 [VALUE] 字段的值，默认值为 keep。

NOTE

如果需要多个参数（即 [SARGS] 字段和 [VALUE] 字段）配置 模板缓冲区（Stencil Buffer），请使用半角空格（即英文空格）隔开。

各个字段的关系如下：

【Shader_Common_stencil_args001.png】

比较操作值

[VALUE]	描述
greater	当像素的 参考值（ref）大于 模板缓冲区（Stencil Buffer）中的当前值时则渲染像素。
gEqual	当像素的 参考值（ref）大于或等于 模板缓冲区（Stencil Buffer）中的当前值时则渲染像素。
less	当像素的 参考值（ref）小于 模板缓冲区（Stencil Buffer）中的当前值时则渲染像素。
lEqual	当像素的 参考值（ref）小于或等于 模板缓冲区（Stencil Buffer）中的当前值时则渲染像素。
equal	当像素的 参考值（ref）等于 模板缓冲区（Stencil Buffer）中的当前值时则渲染像素。
notEqual	当像素的 参考值（ref）不等于 模板缓冲区（Stencil Buffer）中的当前值时则渲染像素。
always	使 模板测试（Stencil Test）始终成功，无论比较如何，始终渲染像素。
never	使 模板测试（Stencil Test）始终失败，无论比较如何，都不会渲染像素。

模板测试操作

[VALUE]
keep	保留 模板缓冲区（Stencil Buffer）的当前内容
zero	将 0 写入 模板缓冲区（Stencil Buffer）。
replace	将 参考值（ref）写入 模板缓冲区（Stencil Buffer）。
incrSat	增加 模板缓冲区（Stencil Buffer）中的当前值。如果该值已经是 255，则保持为 255。
decrSat	减少 模板缓冲区（Stencil Buffer）中的当前值。如果该值已经是 0，则保持为 0。
invert	对 模板缓冲区（Stencil Buffer）中当前值的所有位取反。
incrWrap	增加 模板缓冲区（Stencil Buffer）中的当前值。如果该值已经是 255，则变为 0。
decrWrap	减少 模板缓冲区（Stencil Buffer）中的当前值。如果该值已经是 0，则变为 255。

代码示例

//您可以拆分逐个参数进行赋值;
#pragma stencil_args ref 0

//您也可以同时赋值多个参数，但是每个参数之间需要用半角空格间隔开;
#pragma stencil_args comp equal pass incrSat