LearnOpenGL-CN/04 Advanced OpenGL/02 Stencil testing.md

##模板测试（Stencil testing）

本文作者JoeyDeVries，由Django翻译自http://learnopengl.com

当像素着色器处理完fragment以后，模板测试（stencil test）就开始执行了，和深度测试一样，它有能力丢弃fragment。仍然保留下来的fragment进入深度测试阶段，深度测试可能丢弃更多的fragment。模板测试基于另一个缓冲，这个缓冲叫做模板缓冲（stencil buffer），我们被允许在渲染时更新它来获取有意思的效果。

模板缓冲中一个模板值（stencil value）通常含有8位大小，因此每个像素/fragment总共有256个不同的模板值（译注：8位就是1字节大小，因此和char的容量一样是256个不同值）。这样我们就能将这些模板值设置为我们链接的，然后当一个特定fragment有一个特定的模板值，我们就可以丢弃或保留fragment了。

!!! Important

    每个窗口库都需要为你设置模板缓冲。GLFW自动做了这件事，所以你不必告诉GLFW去创建它，但是其他库可能没默认创建模板库，所以一定要查看你使用的库的文档。

下面是一个模板缓冲的简单例子：

模板缓冲先清空模板缓冲中设置的零，然后开启矩形一。场景中的fragment值渲染模板值包含1的那些fragment（其他的都被丢弃）。

无论我们在渲染哪里的fragment，模板缓冲操作都允许我们把模板缓冲设置为一个特定值。改变模板缓冲的内容实际上就是对模板缓冲进行写入。在同一次（或接下来的）渲染迭代我们可以读取这些值来决定丢弃还是保留这些fragment。当使用模板缓冲的时候，你可以随心所欲，但是需要遵守下面的原则：

• 开启模板缓冲写入。
• 渲染物体，更新模板缓冲。
• 关闭模板缓冲写入。
• 渲染（其他）物体，这次基于模板缓冲内容丢弃特定fragment。

使用模板缓冲我们可以基于场景中已经绘制的fragment，来决定是否丢弃特定的fragment。

你可以开启GL_STENCIL_TEST来开启模板测试。接着所有渲染函数调用都会以这样或那样的方式影响到模板缓冲。

glEnable(GL_STENCIL_TEST);

要注意的是，像颜色和深度缓冲一样，在每次循环，你也得清空模板缓冲。

glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT);

同时，和深度测试的glDepthMask函数一样，模板缓冲也有一个相似函数。glStencilMask允许我们给模板值设置一个位遮罩（bitmask），它与模板值进行与（and）运算决定缓冲是否可写。默认设置的位遮罩都是1，这样就不会影响输出，但是如果我们设置为0x00，所有写入深度缓冲最后都是0。这和深度缓冲的glDepthMask(GL_FALSE)一样：

glStencilMask(0xFF); // Each bit is written to the stencil buffer as is
glStencilMask(0x00); // Each bit ends up as 0 in the stencil buffer (disabling writes)

大多数情况你的模板遮罩（stencil mask）写为0x00或0xFF就行，但是最好知道有一个选项可以自定义位遮罩。

###模板方程（stencil functions）

和深度测试一样，我们也有几个不同控制权，决定何时模板测试通过或失败以及它怎样影响模板缓冲。一共有两种方程可供我们使用去配置模板测试：glStencilFunc和glStencilOp。

glStencilFunc(GLenum func, GLint ref, GLuint mask)有三个参数：

• func：设置模板测试方程。这个测试方程应用到已经储存的模板值和glStencilFunc的ref值上，可用的选项是：GL_NEVER、GL_LEQUAL、GL_GREATER、GL_GEQUAL、GL_EQUAL、GL_NOTEQUAL、GL_ALWAYS。它们的语义和深度缓冲的方程相似。
• ref：指定模板测试的引用值。模板缓冲的内容会与这个值对比。
• mask：指定一个遮罩，在模板测试对比引用值和储存的模板值前，对它们进行与（and）操作。初始设置为1。

在上面简单模板的例子里，方程应该设置为：

glStencilFunc(GL_EQUAL, 1, 0xFF)

它会告诉OpenGL，无论何时，一个fragment模板值等于（GL_EQUAL）引用值1，fragment就能通过测试被绘制了，否则就会被丢弃。

但是glStencilFunc只描述了OpenGL对模板缓冲做什么，而不是我们如何更新缓冲。这就需要glStencilOp登场了。

glStencilOp(GLenum sfail, GLenum dpfail, GLenum dppass)包含三个选项，我们可以指定每个选项的动作：

• sfail：如果模板测试失败将采取的动作。
• dpfail：如果模板测试通过，但是深度测试失败时采取的动作。
• dppass：如果深度测试和模板测试都通过，将采取的动作。

每个选项都可以使用下列任何一个动作。

操作	描述
GL_KEEP	The currently stored stencil value is kept.
GL_ZERO	The stencil value is set to 0.
GL_REPLACE	The stencil value is replaced with the reference value set with glStencilFunc.
GL_INCR	The stencil value is increased by 1 if it is lower than the maximum value.
GL_INCR_WRAP	Same as GL_INCR, but wraps it back to 0 as soon as the maximum value is exceeded.
GL_DECR	The stencil value is decreased by 1 if it is higher than the minimum value.
GL_DECR_WRAP	Same as GL_DECR, but wraps it to the maximum value if it ends up lower than 0.
GL_INVERT	Bitwise inverts the current stencil buffer value.

glStencilOp函数默认设置为 (GL_KEEP, GL_KEEP, GL_KEEP) ，所以任何测试的任何结果，模板缓冲都会保留它的值。默认行为不会更新模板缓冲，所以如果你想写入模板缓冲的话，你必须像任意选项指定至少一个不同的动作。

使用glStencilFunc和glStencilOp，我们就可以指定在什么时候以及我们打算怎么样去更新模板缓冲了，我们也可以指定何时让测试通过或不通过。什么时候fragment会被抛弃。

###物体轮廓

看了前面的部分你未必能理解模板测试是如何工作的，所以我们会展示一个模板测试可以实现的一个特别的和有用的功能，叫做物体轮廓（object outlining）。

物体轮廓就像它的名字所描述的那样，它能够给每个（或一个）物体创建一个有颜色的边。在策略游戏中当你打算选择一个单位的时候它特别有用。给物体加上轮廓的步骤如下：

1. 在绘制（有轮廓的）物体前，把模板方程设置为GL_ALWAYS，用1更新物体的将被渲染的fragment。
2. 渲染物体。
3. 关闭模板写入和深度测试。
4. 每个物体放大一点点。
5. 使用一个不同的像素着色器输出一个纯颜色。
6. 再次绘制物体，但只是当它们的fragment的模板值不为1时才进行。
7. 开启模板写入和深度测试。

这个过程将每个物体的fragment模板缓冲设置为1，当我们绘制边框的时候，我们基本上绘制的是放大版本的物体和通过测试的地方，放大的版本绘制后物体就会有一个边。我们基本会使用模板缓冲丢弃所有的不是原来物体的fragment的放大的版本内容。

我们先来创建一个非常基本的像素着色器，它输出一个边框颜色。我们简单地设置一个固定的颜色值，把这个着色器命名为shaderSingleColor：

void main()
{
    outColor = vec4(0.04, 0.28, 0.26, 1.0);
}

我们只打算给两个箱子加上边框，所以我们不会对地面做什么。这样我们要先绘制地面，然后再绘制两个箱子（同时写入模板缓冲），接着我们绘制放大的箱子（同时丢弃前面已经绘制的箱子的那部分fragment）。

我们先开启模板测试，把将设置为无论何时、任何测试、通过或失败时才采取动作：

glEnable(GL_DEPTH_TEST);
glStencilOp(GL_KEEP, GL_KEEP, GL_REPLACE);

如果任何测试失败我们都什么也不做，我们简单地保持深度缓冲中当前所储存着的值。如果模板测试和深度测试都成功了，我们就将储存着的模板值替换为1，我们要用glStencilFunc来做这件事。

我们清空模板缓冲为0，为箱子的所有绘制的fragment的模板缓冲更新为1：

glStencilFunc(GL_ALWAYS, 1, 0xFF); // All fragments should update the stencil buffer
glStencilMask(0xFF); // Enable writing to the stencil buffer
normalShader.Use();
DrawTwoContainers();

使用GL_ALWAYS模板测试方程，我们确保箱子的每个fragment用模板值1更新模板缓冲。因为fragment总会通过模板测试，在我们绘制它们的地方，模板缓冲用引用值更新。

现在箱子绘制之处，模板缓冲更新为1了，我们将要绘制放大的箱子，但是这次关闭模板缓冲的写入：

glStencilFunc(GL_NOTEQUAL, 1, 0xFF);
glStencilMask(0x00); // Disable writing to the stencil buffer
glDisable(GL_DEPTH_TEST);
shaderSingleColor.Use(); 
DrawTwoScaledUpContainers();

我们把模板方程设置为GL_NOTEQUAL，它保证我们只箱子上不等于1的部分，这样只绘制前面绘制的箱子外围的那部分。注意，我们也要关闭深度测试，这样放大的的箱子也就是边框才不会被地面覆盖。

做完之后还要保证再次开启深度缓冲。

场景中的物体边框的绘制方法最后看起来像这样：

glEnable(GL_DEPTH_TEST);
glStencilOp(GL_KEEP, GL_KEEP, GL_REPLACE);  
  
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT); 
 
glStencilMask(0x00); // Make sure we don't update the stencil buffer while drawing the floor
normalShader.Use();
DrawFloor()  
  
glStencilFunc(GL_ALWAYS, 1, 0xFF); 
glStencilMask(0xFF); 
DrawTwoContainers();
  
glStencilFunc(GL_NOTEQUAL, 1, 0xFF);
glStencilMask(0x00); 
glDisable(GL_DEPTH_TEST);
shaderSingleColor.Use(); 
DrawTwoScaledUpContainers();
glStencilMask(0xFF);
glEnable(GL_DEPTH_TEST);

理解这段代码后面的模板测试的思路并不难以理解。如果还不明白尝试再仔细阅读上面的部分，尝试理解每个函数的作用，现在你已经看到了它的使用方法的例子。

这个边框的算法的结果在深度测试教程的那个场景中，看起来像这样：

在这里查看源码和着色器，看看完整的物体边框算法是怎样的。

!!! Important

    你可以看到两个箱子边框重合通常正是我们希望得到的（想想策略游戏中，我们打算选择10个单位；我们通常会希望把边界合并）。如果你想要让每个物体都有自己的边界那么你需要为每个物体清空模板缓冲，创造性地使用深度缓冲。

你目前看到的物体边框算法在一些游戏中显示备选物体（想象策略游戏）非常常用，这样的算法可以在一个模型类中轻易实现。你可以简单地在模型类设置一个布尔类型的标识来决定是否绘制边框。如果你想要更多的创造性，你可以使用后处理（post-processing）过滤比如高斯模糊来使边框看起来更自然。

除了物体边框以外，模板测试还有很多其他的应用目的，比如在后视镜中绘制纹理，这样它会很好的适合镜子的形状，比如使用一种叫做shadow volumes的模板缓冲技术渲染实时阴影。模板缓冲在我们的已扩展的OpenGL工具箱中给我们提供了另一种好用工具。