vkCreateRenderPass(3) ====================== Name ---- vkCreateRenderPass - Create a new render pass object. C Specification --------------- include::../protos/vkCreateRenderPass.txt[] Parameters ---------- pname:device:: The device with which to create the render pass object. pname:pCreateInfo:: A pointer to a structure containing information to be placed in the object. pname:pRenderPass:: A pointer to a variable which will receive the handle to the new object. Description ----------- fname:vkCreateRenderPass creates a new render pass object using the information contained in pname:pCreateInfo and the device specified in pname:device. Upon success, a handle to the new render pass object is deposited in the variable pointed to by pname:pRenderPass, pname:pCreateInfo should point to an instance of the slink:VkRenderPassCreateInfo structure, the definition of which is: include::../structs/VkRenderPassCreateInfo.txt[] A render pass is a sequence of subpasses, each of which reads from some framebuffer attachments and writes to others as color and depth/stencil. The subpasses all render to the same dimensions, and fragments for pixel (x,y,layer) in one subpass only read framebuffer contents written by earlier subpasses at that same (x,y,layer) location. It is quite common for a render pass to only contain a single subpass. Dependencies between subpasses describe ordering restrictions between them. Without dependencies, implementations may reorder or overlap execution of two subpasses. Attachments ~~~~~~~~~~~ The attachments used in the render pass are described by a slink:VkAttachmentDescription structure, defined as: include::../structs/VkAttachmentDescription.txt[] The pname:format and pname:samples members are respectively the format and the number of samples of the image that will be used for the attachment. The pname:loadOp defines how the contents of the attachment within the render area will be treated at the beginning of the render pass. A load op of ename:VK_ATTACHMENT_LOAD_OP_LOAD means the contents within the render area will be preserved; ename:VK_ATTACHMENT_LOAD_OP_CLEAR means the contents within the render area will be cleared to a uniform value; ename:VK_ATTACHMENT_LOAD_OP_DONT_CARE means the application intends to overwrite all samples in the render area without reading the initial contents, so their initial contents are unimportant. If the attachment format has both depth and stencil components, pname:loadOp applies only to the depth data, while pname:stencilLoadOp defines how the stencil data is handled. pname:stencilLoadOp is ignored for other formats. The pname:storeOp defines whether data rendered to the attachment is committed to memory at the end of the render pass. ename:VK_ATTACHMENT_STORE_OP_STORE means the data is committed to memory and will be available for reading after the render pass completes. ename:VK_ATTACHMENT_STORE_OP_DONT_CARE means the data is not needed after rendering, and may be discarded; the contents of the attachment will be undefined inside the render area. If the attachment format has both depth and stencil components, pname:storeOp applies only to the depth data, while pname:stencilStoreOp defines how the stencil data is handled. pname:stencilStoreOp is ignored for other formats. pname:initialLayout is the layout the attachment image will be in when the render pass begins. pname:finalLayout is the layout the attachment image will be transitioned to when the render pass ends. Subpasses ~~~~~~~~~ Subpasses of a render pass are described by a slink:VkSubpassDescription structure, defined as: include::../structs/VkSubpassDescription.txt[] The pname:pipelineBindPoint indicates whether this is a compute or graphics subpass. Only graphics subpasses are currently allowed. The pname:flags member is currently unused and must be zero. pname:pInputAttachments lists which of the render pass's attachments will be read in the shader in the subpass, and what layout the attachment images should be transitioned to before the subpass. pname:inputAttachmentCount indicates the number of input attachments. Input attachments must also be bound to the pipeline with a descriptor set. pname:pColorAttachments lists which of the render pass's attachments will be used as color attachments in the subpass, and what layout the attachment images should be transitioned to before the subpass. pname:colorAttachmentCount indicates the number of color attachments. Each entry in pname:pResolveAttachments corresponds to an entry in pname:pColorAttachments; either pname:pResolveAttachments must be NULL or it must have pname:colorAttachmentCount entries. If pname:pResolveAttachments is not NULL, each of its elements corresponds to a color attachment (the element in pname:pColorAttachments at the same index). At the end of each subpass, the subpass's color attachments will be resolved to the corresponding resolve attachments, unless the resolve attachment index is ename:VK_ATTACHMENT_UNUSED. The pname:depthStencilAttachment indicates which attachment will be used for depth/stencil data and the layout it should be transitioned to before the subpass. If no depth/stencil attachment is used in the subpass, the attachment index must be ename:VK_ATTACHMENT_UNUSED. The pname:pPreserveAttachments are the attachments that aren't used by a subpass, but whose contents must be preserved throughout the subpass. If the contents of an attachment are produced in one subpass and consumed in a later subpass, the attachment must be preserved in any subpasses on dependency chains from the producer to consumer. pname:preserveAttachmentCount indicates the number of preserved attachments. If a subpass uses an attachment as both an input attachment and either a color attachment or a depth/stencil attachment, all pipelines used in the subpass must disable writes to any components of the attachment format that are used as input. Dependencies ~~~~~~~~~~~~ Dependencies describe a pipeline barrier that must occur between two subpasses, usually because the destination subpass reads attachment contents written by the source subpass. Dependencies are described by sname:VkSubpassDependency structures, defined as: include::../structs/VkSubpassDependency.txt[] The pname:srcSubpass and pname:dstSubpass are producer and consumer subpasses, respectively. pname:srcSubpass must be less than or equal to pname:dstSubpass, so that the order of subpass descriptions is always a valid execution ordering, and so the dependency graph cannot have cycles. The pname:srcStageMask, pname:dstStageMask, pname:outputMask, pname:inputMask, and pname:byRegion describe the barrier, and have the same meaning as the VkCmdPipelineBarrier parameters and slink:VkMemoryBarrier members with the same names. If pname:byRegion is ename:VK_TRUE, it describes a per-region (x,y,layer) dependency, that is for each region, the pname:srcStageMask stages must have finished in pname:srcSubpass before any pname:dstStageMask stage starts in pname:dstSubpass for the same region. If pname:byRegion is ename:VK_FALSE, it describes a global dependency, that is the pname:srcStageMask stages must have finished for all regions in pname:srcSubpass before any pname:dstStageMask stage starts in pname:dstSubpass for any region. include::../validity/protos/vkCreateRenderPass.txt[] See Also -------- flink:vkCmdBeginRenderPass, flink:vkCmdEndRenderPass include::footer.txt[]