From 89efd160afcc2bb8e1bba6bdc29f1668207b2fe1 Mon Sep 17 00:00:00 2001 From: Brandon Jones Date: Tue, 2 Jun 2020 15:00:36 -0700 Subject: [PATCH 1/8] Documenting render pass creation and descriptors --- spec/index.bs | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) diff --git a/spec/index.bs b/spec/index.bs index 59e88b4e80..649f4b5729 100644 --- a/spec/index.bs +++ b/spec/index.bs @@ -3128,6 +3128,38 @@ dictionary GPUCommandEncoderDescriptor : GPUObjectDescriptorBase { }; +## Pass Encoding ## {#command-encoder-pass-encoding} + +### beginRenderPass(descriptor) ### {#GPUCommandEncoder-beginRenderPass} + +
+ |this|: of type {{GPUCommandEncoder}}. + + **Arguments:** + - {{GPURenderPassDescriptor}} |descriptor| + + **Returns:** GPURenderPassEncoder + + Begins encoding a render pass described by |descriptor|. + + On the [=Device timeline=], the following steps occur: + + - If the [$GPUCommandEncoder.beginRenderPass/Valid Usage$] rules are met: + + - Set |this|.{{GPUCommandEncoder/[[state]]}} to {{encoder state/encoding a render pass}}. + +
+ Valid Usage + + Given the argument {{GPURenderPassDescriptor}} |descriptor|, the following validation rules apply: + + 1. |this|.{{GPUCommandEncoder/[[state]]}} must be {{encoder state/open}}. + 1. |descriptor| must meet the + [$GPURenderPassDescriptor/Valid Usage|GPURenderPassDescriptor Valid Usage$] rules. + +
+
+ ## Copy Commands ## {#copy-commands} ### GPUTextureDataLayout ### {#gpu-texture-data-layout} @@ -3898,6 +3930,38 @@ dictionary GPURenderPassDescriptor : GPUObjectDescriptorBase { }; +
+ : colorAttachments + :: + The set of {{GPURenderPassColorAttachmentDescriptor}} values in this sequence defines which + color attachments will be output to when executing this render pass. + + : depthStencilAttachment + :: + The {{GPURenderPassDepthStencilAttachmentDescriptor}} value that defines the depth/stencil + attachment that will be output to and tested against when executing this render pass. + + : occlusionQuerySet + :: + Issue: Describe this dictionary member +
+ +
+ Valid Usage + + Given a {{GPURenderPassDescriptor}} |this| the following validation rules apply: + + 1. |this|.{{GPURenderPassDescriptor/colorAttachments}}.length must greater than `0` or + |this|.{{GPURenderPassDescriptor/depthStencilAttachment}} must not be `null`. + 1. For each |colorAttachment| in |this|.{{GPURenderPassDescriptor/colorAttachments}}: + + 1. |colorAttachment| must meet the [$GPURenderPassColorAttachmentDescriptor/Valid Usage|GPURenderPassColorAttachmentDescriptor Valid Usage$] rules. + + 1. If |this|.{{GPURenderPassDescriptor/depthStencilAttachment}} is not `null`: + + 1. |this|.{{GPURenderPassDescriptor/depthStencilAttachment}} must meet the [$GPURenderPassDepthStencilAttachmentDescriptor/Valid Usage|GPURenderPassDepthStencilAttachmentDescriptor Valid Usage$] rules. +
+ #### Color Attachments #### {#color-attachments} +
+ : attachment + :: + A {{GPUTextureView}} describing the texture [=subresource=] the [=pipeline=] will output to + for this color attachment. + + : resolveTarget + :: + A {{GPUTextureView}} describing the texture [=subresource=] that will receive the resolved + output for this color attachment if {{GPURenderPassColorAttachmentDescriptor/attachment}} is + multisampled. + + : loadValue + :: + Issue: Describe this dictionary member + + : storeOp + :: + Issue: Describe this dictionary member +
+ +
+ Valid Usage + + Given a {{GPURenderPassColorAttachmentDescriptor}} |this| the following validation rules + apply: + + 1. |this|.{{GPURenderPassColorAttachmentDescriptor/attachment}} must have a renderable color format. + 1. If |this|.{{GPURenderPassColorAttachmentDescriptor/resolveTarget}} is not `null`: + + 1. |this|.{{GPURenderPassColorAttachmentDescriptor/attachment}} must be multisampled. + 1. |this|.{{GPURenderPassColorAttachmentDescriptor/resolveTarget}} must not be multisampled. + 1. Issue: Describe the remainder of resolveTarget validation + + 1. Otherwise |this|.{{GPURenderPassColorAttachmentDescriptor/attachment}} must not be multisampled. + + Issue: Describe the remaining validation rules for this type. +
+ #### Depth/Stencil Attachments #### {#depth-stencil-attachments} +
+ : attachment + :: + A {{GPUTextureView}} describing the texture [=subresource=] the [=pipeline=] will output to + and read from for this depth/stencil attachment. + + : depthLoadValue + :: + Issue: Describe this dictionary member + + : depthStoreOp + :: + Issue: Describe this dictionary member + + : depthReadOnly + :: + Indicates that the depth component of the attachment is read only. + + : stencilLoadValue + :: + Issue: Describe this dictionary member + + : stencilStoreOp + :: + Issue: Describe this dictionary member + + : stencilReadOnly + :: + Indicates that the stencil component of the attachment is read only. +
+ +
+ Valid Usage + + Given a {{GPURenderPassDepthStencilAttachmentDescriptor}} |this| the following validation + rules apply: + + 1. |this|.{{GPURenderPassDepthStencilAttachmentDescriptor/attachment}} must have a renderable depth or stencil format. + + Issue: Describe the remaining validation rules for this type. +
+ ### Load & Store Operations ### {#load-and-store-ops} +{{GPUTextureView}} has the following internal slots: + +
+ : \[[texture]] + :: + The {{GPUTexture}} into which this is a view. + + : \[[descriptor]] + :: + The {{GPUTextureViewDescriptor}} describing this texture view. + + All optional fields of {{GPUTextureViewDescriptor}} are defined. +
+ ### Texture View Creation ### {#texture-view-creation}