《Metal》官方文档翻译007--图形渲染：渲染命令编码器（下）

执行固定功能渲染命令编码器操作

使用这些MTLRenderCommandEncoder方法设置固定功能图形状态值：

• setViewport:指定屏幕坐标中的区域，虚拟3D世界的投影目的地。视口是3D，因此它包括深度值; 有关详细信息，请参阅使用视口和像素坐标系。
• setTriangleFillMode:确定是否使用lines（MTLTriangleFillModeLines
  ）或填充三角形（MTLTriangleFillModeFill）栅格化三角形和三角形条纹图元。默认值为MTLTriangleFillModeFill。
• setCullMode:并且setFrontFacingWinding:一起使用以确定是否以及如何应用剔除。您可以使用剔除在某些几何模型上进行隐藏的表面去除，例如使用填充三角形渲染的可定向球体。（如果原始图像顺时针或逆时针顺序绘制，表面可以定向。）
  • 该值setFrontFacingWinding:指示前面的图元是否以其顺时针（MTLWindingClockwise）或逆时针（MTLWindingCounterClockwise）顺序绘制顶点。默认值为MTLWindingClockwise。
  • setCullMode:的值来确定是否执行剔除（
    MTLCullModeNone，如果剔除禁用）或其中的原始类型剔除（
    MTLCullModeFront或MTLCullModeBack）。

使用以下MTLRenderCommandEncoder方法对固定功能状态更改命令进行编码：

• setScissorRect:指定2D剪刀矩形。位于指定剪刀矩形之外的碎片被丢弃。

• setDepthStencilState:如设置中所描述的深度和模板测试状态深度和模板的国家。

• setStencilReferenceValue: 指定模板参考值。

• setDepthBias:slopeScale:clamp: 指定用于将阴影贴图与片段着色器输出的深度值进行比较的调整。

• setVisibilityResultMode:offset:确定是否监控任何样品是否通过深度和模板测试。如果设置为MTLVisibilityResultModeBoolean，则如果任何样本通过深度和模板测试，则会将非零值写入由visibilityResultBuffer属性指定的缓冲区MTLRenderPassDescriptor，如创建渲染通过描述符中所述。

  您可以使用此模式执行遮挡测试。如果绘制边框并且没有样本通过，那么您可以得出结论，边界框内的任何对象都被遮挡，因此不需要渲染。

• setBlendColorRed:green:blue:alpha:指定常量混合颜色和alpha值，如在渲染管道附件描述符中配置混合中所详述的。

使用视口和像素坐标系

Metal将其归一化设备坐标（NDC）系统定义为2x2x1立方体，其中心位于（0,0,0.5）。NDC系统的x和y的左侧和底部分别指定为-1。NDC系统的x和y的右侧和顶部分别指定为+1。

视口指定从NDC到窗口坐标的转换。Metal视口是由setViewport:方法指定的3D变换MTLRenderCommandEncoder。窗口坐标的起点在左上角。在Metal中，像素中心偏移（0.5,0.5）。例如，原点的像素的中心为（0.5,0.5）; 右边相邻像素的中心是（1.5,0.5）。纹理也是如此。

执行深度和模板操作

深度和模板操作是您指定的碎片操作，如下所示：

1：指定MTLDepthStencilDescriptor包含深度/模板状态设置的自定义对象。创建自定义MTLDepthStencilDescriptor对象可能需要创建一个或两个MTLStencilDescriptor适用于前面的图元和背面图元的对象。

2：MTLDepthStencilState通过调用深度/模板状态描述符的newDepthStencilStateWithDescriptor:方法来创建一个对象MTLDevice。

3：要设置深度/模板状态，调用setDepthStencilState:的方法MTLRenderCommandEncoder与MTLDepthStencilState。

4：如果模板测试正在使用中，请调用setStencilReferenceValue:以指定模板参考值。

如果启用了深度测试，则渲染流水线状态必须包含深度附件以支持写入深度值。要执行模板测试，渲染流水线状态必须包括模板附件。要配置附件，请参阅创建和配置渲染流水线描述符。

如果您将定期更改深度/模板状态，则可能需要重新使用状态描述符对象，根据需要修改其属性值以创建更多的状态对象。

注意： 要从着色器函数中的深度格式纹理进行采样，请在着色器中实现采样操作而不使用MTLSamplerState。

使用MTLDepthStencilDescriptor对象的属性设置深度和模板状态：

• 要将深度值写入深度附件，请设置depthWriteEnabled为YES。

• depthCompareFunction指定深度测试的执行方式。如果片段的深度值未通过深度测试，则片段将被丢弃。例如，通常使用的MTLCompareFunctionLess函数会导致远离观察者的片段值（先前写入的）像素深度值，以使深度测试失败; 也就是说，该片段被认为被较早的深度值遮挡。

• 该属性frontFaceStencil和backFaceStencil每个属性都MTLStencilDescriptor为前面和后面的基元指定一个单独的对象。要对前面和后面的图元都使用相同的模版状态，可以将它们分配MTLStencilDescriptor给两者frontFaceStencil和backFaceStencil属性。要显式禁用一个或两个面的模板测试，请将相应的属性设置nil为默认值。

不需要显式禁用模板状态。Metal决定是否启用模板测试，基于模板描述符是否配置为有效的模板操作。

清单5-13显示了创建和使用MTLDepthStencilDescriptor对象创建对象的示例，MTLDepthStencilState然后将其与render命令编码器一起使用。在这个例子中，前端基元的模板状态是从frontFaceStencil深度/模板状态描述符的属性中进行访问的。对于背面原语，模板测试被明确禁用。

清单5-13 创建和使用深度/模板描述符

MTLDepthStencilDescriptor *dsDesc = [[MTLDepthStencilDescriptor alloc] init];
if (dsDesc == nil)
 exit(1);   //  if the descriptor could not be allocated
dsDesc.depthCompareFunction = MTLCompareFunctionLess;
dsDesc.depthWriteEnabled = YES;

dsDesc.frontFaceStencil.stencilCompareFunction = MTLCompareFunctionEqual;
dsDesc.frontFaceStencil.stencilFailureOperation = MTLStencilOperationKeep;
dsDesc.frontFaceStencil.depthFailureOperation = 
MTLStencilOperationIncrementClamp;
dsDesc.frontFaceStencil.depthStencilPassOperation =
                      MTLStencilOperationIncrementClamp;
dsDesc.frontFaceStencil.readMask = 0x1;
dsDesc.frontFaceStencil.writeMask = 0x1;
dsDesc.backFaceStencil = nil;
id  dsState = [device
                      newDepthStencilStateWithDescriptor:dsDesc];

[renderEnc setDepthStencilState:dsState];
[renderEnc setStencilReferenceValue:0xFF];

以下属性定义了模板测试MTLStencilDescriptor：

• readMask是一个bitmask; GPU使用模板参考值和存储的模版值来计算该掩码的按位AND。模板测试是所得到的掩蔽参考值和掩蔽的存储值之间的比较。

• writeMask 是一个掩码，通过模板操作来限制哪些模板值写入模板附件。

• stencilCompareFunction指定如何对片段执行模板测试。在清单5-13中，模板比较函数是MTLCompareFunctionEqual，因此如果掩码的参考值等于已经存储在片段位置的掩码的模板值，模板测试就会通过。

• stencilFailureOperation，depthFailureOperation并depthStencilPassOperation针对三种不同的测试结果指定对模具附件中存储的模板值做什么：如果模板测试失败，模板测试通过并且深度测试失败，或者模板和深度测试分别成功。在上述示例中，MTLStencilOperationKeep如果模板测试失败，模板值不变（），但如果模板测试通过，则模板值将增加，除非模板值已经是最大可能（MTLStencilOperationIncrementClamp）。

绘制几何图元

在建立管道状态和固定功能状态后，可以调用以下MTLRenderCommandEncoder方法绘制几何图元。这些绘制方法引用资源（如包含顶点坐标，纹理坐标，曲面法线和其他数据的缓冲区）来执行与之前建立的着色器功能和其他状态的管道MTLRenderCommandEncoder。

• drawPrimitives:vertexStart:vertexCount:instanceCount:instanceCount在连续数组元素中渲染使用顶点数据的一些基元的实例（），从索引处的数组元素处的第一个顶点开始，并以索引vertexStart的数组元素结束vertexStart + vertexCount - 1。

• drawPrimitives:vertexStart:vertexCount:与前一种方法相同，其中a instanceCount为1。

• drawIndexedPrimitives:indexCount:indexType:indexBuffer:indexBufferOffset:instanceCount:instanceCount使用MTLBuffer对象中指定的索引列表呈现一些primitives 的实例（）indexBuffer。indexCount确定索引数。索引列表从indexBufferOffset数据中的字节偏移量的索引开始indexBuffer。indexBufferOffset必须是索引大小的倍数，由索引决定indexType。

• drawIndexedPrimitives:indexCount:indexType:indexBuffer:indexBufferOffset:与以前的方法类似，其中a instanceCount为1。

对于上面列出的每个原始渲染方法，第一个输入值使用其中一个值确定原始类型MTLPrimitiveType。其他输入值确定哪些顶点用于组合图元。对于所有这些方法，instanceStart输入值决定了绘制的第一个实例，instanceCount输入值决定了绘制多少个实例。

如前所述，setTriangleFillMode:确定三角形是否被渲染为填充或线框，setCullMode:并且setFrontFacingWinding:设置确定GPU是否在渲染期间剔除三角形。有关更多信息，请参阅固定功能状态操作）。

渲染点基元时，顶点函数的着色器语言代码必须提供[[ point_size ]]属性，或者点大小未定义。

当渲染具有平坦阴影的三角形原语时，第一个顶点的属性（也称为激发顶点）用于整个三角形。顶点函数的着色器语言代码必须提供[[ flat ]]插值限定符。

有关所有Metal着色语言属性和限定词的详细信息，请参阅“ Metal着色语言指南”。

结束渲染通行证

要终止渲染遍，请调用endEncoding渲染命令编码器。在结束上一个命令编码器之后，您可以创建任何类型的新命令编码器，以将其他命令编码到命令缓冲区中。

代码示例：绘制三角形

清单5-14所示的以下步骤描述了渲染三角形的基本过程。

1：创建一个MTLCommandQueue并使用它创建一个MTLCommandBuffer。

2：创建一个MTLRenderPassDescriptor指定用作命令缓冲区中编码渲染命令的目的地的附件集合。

在此示例中，仅设置和使用第一个颜色附件。（currentTexture假定变量包含一个MTLTexture用于颜色附件的变量。）然后MTLRenderPassDescriptor用于创建一个新的MTLRenderCommandEncoder。

3：创建两个MTLBuffer对象，posBuf并且colBuf，和呼叫newBufferWithBytes:length:options:复制顶点坐标和顶点颜色数据，posData和colData分别，到缓冲存储器。

4：调用两次setVertexBuffer:offset:atIndex:方法MTLRenderCommandEncoder来指定坐标和颜色。

该方法的atIndex输入值setVertexBuffer:offset:atIndex:对应于buffer(atIndex)顶点函数的源代码中的属性。

5：MTLRenderPipelineDescriptor在流水线描述符中创建并建立顶点和碎片函数：

• 创建MTLLibrary源代码progSrc，它被假定为包含Metal着色器源代码的字符串。

• 然后调用newFunctionWithName:的方法MTLLibrary创建MTLFunction vertFunc一个表示调用的函数hello_vertex，并创建MTLFunction fragFunc一个表示调用的函数hello_fragment。

• 最后，设置vertexFunction和这些对象的fragmentFunction属性。MTLRenderPipelineDescriptorMTLFunction

6：创建一个MTLRenderPipelineState从MTLRenderPipelineDescriptor调用newRenderPipelineStateWithDescriptor:error:或类似的方法MTLDevice。然后setRenderPipelineState:的方法MTLRenderCommandEncoder使用创建流水线状态进行渲染。

7：调用附加命令的drawPrimitives:vertexStart:vertexCount:方法MTLRenderCommandEncoder来执行填充三角形（类型MTLPrimitiveTypeTriangle）的渲染。

8：调用该endEncoding方法来结束此渲染过程的编码。并调用commit的方法MTLCommandBuffer，以在设备上执行的命令。

清单5-14 绘制三角形的Metal代码

id  device = MTLCreateSystemDefaultDevice();

id  commandQueue = [device newCommandQueue];
id  commandBuffer = [commandQueue commandBuffer];

MTLRenderPassDescriptor *renderPassDesc
                           = [MTLRenderPassDescriptor renderPassDescriptor];
renderPassDesc.colorAttachments[0].texture = currentTexture;
renderPassDesc.colorAttachments[0].loadAction = MTLLoadActionClear;
renderPassDesc.colorAttachments[0].clearColor = MTLClearColorMake(0.0,1.0,1.0,1.0);
id  renderEncoder =
        [commandBuffer renderCommandEncoderWithDescriptor:renderPassDesc];

static const float posData[] = {
    0.0f, 0.33f, 0.0f, 1.f,
    -0.33f, -0.33f, 0.0f, 1.f,
    0.33f, -0.33f, 0.0f, 1.f,
};
static const float colData[] = {
    1.f, 0.f, 0.f, 1.f,
    0.f, 1.f, 0.f, 1.f,
    0.f, 0.f, 1.f, 1.f,
};
id  posBuf = [device newBufferWithBytes:posData
    length:sizeof(posData) options:nil];
id  colBuf = [device newBufferWithBytes:colorData
    length:sizeof(colData) options:nil];
[renderEncoder setVertexBuffer:posBuf offset:0 atIndex:0];
[renderEncoder setVertexBuffer:colBuf offset:0 atIndex:1];

NSError *errors;
id  library = [device newLibraryWithSource:progSrc options:nil
                       error:&errors];
id  vertFunc = [library newFunctionWithName:@"hello_vertex"];
id  fragFunc = [library newFunctionWithName:@"hello_fragment"];
MTLRenderPipelineDescriptor *renderPipelineDesc
                               = [[MTLRenderPipelineDescriptor alloc] init];
renderPipelineDesc.vertexFunction = vertFunc;
renderPipelineDesc.fragmentFunction = fragFunc;
renderPipelineDesc.colorAttachments[0].pixelFormat = currentTexture.pixelFormat;
id  pipeline = [device
         
newRenderPipelineStateWithDescriptor:renderPipelineDesc error:&errors];
[renderEncoder setRenderPipelineState:pipeline];
[renderEncoder drawPrimitives:MTLPrimitiveTypeTriangle
           vertexStart:0 vertexCount:3];
[renderEncoder endEncoding];
[commandBuffer commit];

在清单5-14中，一个MTLFunction对象代表着名的着色器函数hello_vertex。该setVertexBuffer:offset:atIndex:方法MTLRenderCommandEncoder用于指定作为参数传递的顶点资源（在这种情况下为两个缓冲区对象）hello_vertex。方法的atIndex输入值setVertexBuffer:offset:atIndex:对应于buffer(atIndex)顶点函数的源代码中的属性，如清单5-15所示。

清单5-15 相应的着色器功能声明

vertex VertexOutput hello_vertex(

const global float4 *pos_data [[ buffer(0) ]],

const global float4 *color_data [[ buffer(1) ]])

{

...

}

使用多个线程编码单个渲染通过

在某些情况下，您的应用程序的性能可能受到单个渲染通过的编码命令的单CPU工作负载的限制。然而，通过将工作负载分割为多个CPU线程上编码的多个渲染通道来尝试规避此瓶颈也可能不利地影响性能，因为每个渲染传递都需要自己的中间附件存储和加载操作来保留渲染目标内容。

而是使用一个MTLParallelRenderCommandEncoder对象来管理MTLRenderCommandEncoder共享相同命令缓冲区并渲染传递描述符的多个下级对象。并行渲染命令编码器确保附件加载和存储动作仅在整个渲染遍的开始和结束时发生，而不是在每个从属渲染命令编码器的命令集的开始和结束。使用这种架构，您可以MTLRenderCommandEncoder以安全和高性能的方式并行分配每个对象到其自己的线程。

要创建并行渲染命令编码器，请使用对象的parallelRenderCommandEncoderWithDescriptor:方法MTLCommandBuffer。要创建从属渲染命令编码器，请从要执行命令编码的每个CPU线程调用该对象的renderCommandEncoder方法MTLParallelRenderCommandEncoder一次。由相同的并行渲染命令编码器创建的所有下级命令编码器将命令编码到相同的命令缓冲区。命令按照创建渲染命令编码器的顺序编码到命令缓冲区。要结束对特定渲染命令编码器的编码，请调用其endEncoding方法MTLRenderCommandEncoder。你已经结束了对并行渲染指令编码器创建的所有渲染指令编码器编码后，调用endEncoding的方法MTLParallelRenderCommandEncoder来结束渲染通道。

清单5-16显示了MTLParallelRenderCommandEncoder创建三个MTLRenderCommandEncoder对象：rCE1，rCE2，和rCE3。

清单5-16 具有三个渲染命令编码器的并行渲染编码器

MTLRenderPassDescriptor *renderPassDesc 
                 = [MTLRenderPassDescriptor renderPassDescriptor];
renderPassDesc.colorAttachments[0].texture = currentTexture;
renderPassDesc.colorAttachments[0].loadAction = MTLLoadActionClear;
renderPassDesc.colorAttachments[0].clearColor = MTLClearColorMake(0.0,0.0,0.0,1.0);

id  parallelRCE = [commandBuffer 
              parallelRenderCommandEncoderWithDescriptor:renderPassDesc];
id  rCE1 = [parallelRCE renderCommandEncoder];
id  rCE2 = [parallelRCE renderCommandEncoder];
id  rCE3 = [parallelRCE renderCommandEncoder];

//  not shown: rCE1, rCE2, and rCE3 call methods to encode graphics commands
//
//  rCE1 commands are processed first, because it was created first
//  even though rCE2 and rCE3 end earlier than rCE1
[rCE2 endEncoding];
[rCE3 endEncoding];
[rCE1 endEncoding];

 //  all MTLRenderCommandEncoders must end before 
 MTLParallelRenderCommandEncoder
[parallelRCE endEncoding];

命令编码器调用endEncoding的顺序与命令编码和附加到的顺序无关MTLCommandBuffer。因为MTLParallelRenderCommandEncoder，MTLCommandBuffer始终包含按照下面的渲染命令编码器创建顺序的命令，如图5-6所示。

图5-6 平行渲染通过中渲染命令编码器的顺序

下一页
上一页