vulkan-3.0.0.0: Bindings to the Vulkan graphics API.

Safe HaskellNone
LanguageHaskell2010

Graphics.Vulkan.Core10.Pass

Synopsis

Documentation

createFramebuffer :: PokeChain a => Device -> FramebufferCreateInfo a -> ("allocator" ::: Maybe AllocationCallbacks) -> IO Framebuffer Source #

vkCreateFramebuffer - Create a new framebuffer object

Parameters

  • Device is the logical device that creates the framebuffer.
  • pCreateInfo is a pointer to a FramebufferCreateInfo structure describing additional information about framebuffer creation.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.
  • pFramebuffer is a pointer to a Framebuffer handle in which the resulting framebuffer object is returned.

Valid Usage

Valid Usage (Implicit)

Return Codes

Success
Failure

See Also

AllocationCallbacks, Device, Framebuffer, FramebufferCreateInfo

withFramebuffer :: PokeChain a => Device -> FramebufferCreateInfo a -> Maybe AllocationCallbacks -> (Framebuffer -> IO r) -> IO r Source #

A safe wrapper for createFramebuffer and destroyFramebuffer using bracket

The allocated value must not be returned from the provided computation

destroyFramebuffer :: Device -> Framebuffer -> ("allocator" ::: Maybe AllocationCallbacks) -> IO () Source #

vkDestroyFramebuffer - Destroy a framebuffer object

Parameters

  • Device is the logical device that destroys the framebuffer.
  • Framebuffer is the handle of the framebuffer to destroy.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • All submitted commands that refer to Framebuffer must have completed execution

Valid Usage (Implicit)

Host Synchronization

  • Host access to Framebuffer must be externally synchronized

See Also

AllocationCallbacks, Device, Framebuffer

createRenderPass :: PokeChain a => Device -> RenderPassCreateInfo a -> ("allocator" ::: Maybe AllocationCallbacks) -> IO RenderPass Source #

vkCreateRenderPass - Create a new render pass object

Parameters

  • Device is the logical device that creates the render pass.
  • pCreateInfo is a pointer to a RenderPassCreateInfo structure describing the parameters of the render pass.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.
  • pRenderPass is a pointer to a RenderPass handle in which the resulting render pass object is returned.

Valid Usage (Implicit)

Return Codes

Success
Failure

See Also

AllocationCallbacks, Device, RenderPass, RenderPassCreateInfo

withRenderPass :: PokeChain a => Device -> RenderPassCreateInfo a -> Maybe AllocationCallbacks -> (RenderPass -> IO r) -> IO r Source #

A safe wrapper for createRenderPass and destroyRenderPass using bracket

The allocated value must not be returned from the provided computation

destroyRenderPass :: Device -> RenderPass -> ("allocator" ::: Maybe AllocationCallbacks) -> IO () Source #

vkDestroyRenderPass - Destroy a render pass object

Parameters

  • Device is the logical device that destroys the render pass.
  • RenderPass is the handle of the render pass to destroy.
  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • All submitted commands that refer to RenderPass must have completed execution

Valid Usage (Implicit)

Host Synchronization

  • Host access to RenderPass must be externally synchronized

See Also

AllocationCallbacks, Device, RenderPass

getRenderAreaGranularity :: Device -> RenderPass -> IO ("granularity" ::: Extent2D) Source #

vkGetRenderAreaGranularity - Returns the granularity for optimal render area

Parameters

  • Device is the logical device that owns the render pass.
  • RenderPass is a handle to a render pass.
  • pGranularity is a pointer to a Extent2D structure in which the granularity is returned.

Description

The conditions leading to an optimal renderArea are:

  • the offset.x member in renderArea is a multiple of the width member of the returned Extent2D (the horizontal granularity).
  • the offset.y member in renderArea is a multiple of the height of the returned Extent2D (the vertical granularity).
  • either the offset.width member in renderArea is a multiple of the horizontal granularity or offset.x+offset.width is equal to the width of the Framebuffer in the RenderPassBeginInfo.
  • either the offset.height member in renderArea is a multiple of the vertical granularity or offset.y+offset.height is equal to the height of the Framebuffer in the RenderPassBeginInfo.

Subpass dependencies are not affected by the render area, and apply to the entire image subresources attached to the framebuffer as specified in the description of automatic layout transitions. Similarly, pipeline barriers are valid even if their effect extends outside the render area.

Valid Usage (Implicit)

See Also

Device, Extent2D, RenderPass

data AttachmentDescription Source #

VkAttachmentDescription - Structure specifying an attachment description

Description

If the attachment uses a color format, then loadOp and storeOp are used, and stencilLoadOp and stencilStoreOp are ignored. If the format has depth and/or stencil components, loadOp and storeOp apply only to the depth data, while stencilLoadOp and stencilStoreOp define how the stencil data is handled. loadOp and stencilLoadOp define the load operations that execute as part of the first subpass that uses the attachment. storeOp and stencilStoreOp define the store operations that execute as part of the last subpass that uses the attachment.

The load operation for each sample in an attachment happens-before any recorded command which accesses the sample in the first subpass where the attachment is used. Load operations for attachments with a depth/stencil format execute in the PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT pipeline stage. Load operations for attachments with a color format execute in the PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.

The store operation for each sample in an attachment happens-after any recorded command which accesses the sample in the last subpass where the attachment is used. Store operations for attachments with a depth/stencil format execute in the PIPELINE_STAGE_LATE_FRAGMENT_TESTS_BIT pipeline stage. Store operations for attachments with a color format execute in the PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT pipeline stage.

If an attachment is not used by any subpass, then loadOp, storeOp, stencilStoreOp, and stencilLoadOp are ignored, and the attachment’s memory contents will not be modified by execution of a render pass instance.

The load and store operations apply on the first and last use of each view in the render pass, respectively. If a view index of an attachment is not included in the view mask in any subpass that uses it, then the load and store operations are ignored, and the attachment’s memory contents will not be modified by execution of a render pass instance.

During a render pass instance, input/color attachments with color formats that have a component size of 8, 16, or 32 bits must be represented in the attachment’s format throughout the instance. Attachments with other floating- or fixed-point color formats, or with depth components may be represented in a format with a precision higher than the attachment format, but must be represented with the same range. When such a component is loaded via the loadOp, it will be converted into an implementation-dependent format used by the render pass. Such components must be converted from the render pass format, to the format of the attachment, before they are resolved or stored at the end of a render pass instance via storeOp. Conversions occur as described in Numeric Representation and Computation and Fixed-Point Data Conversions.

If Flags includes ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT, then the attachment is treated as if it shares physical memory with another attachment in the same render pass. This information limits the ability of the implementation to reorder certain operations (like layout transitions and the loadOp) such that it is not improperly reordered against other uses of the same physical memory via a different attachment. This is described in more detail below.

If a render pass uses multiple attachments that alias the same device memory, those attachments must each include the ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit in their attachment description flags. Attachments aliasing the same memory occurs in multiple ways:

  • Multiple attachments being assigned the same image view as part of framebuffer creation.
  • Attachments using distinct image views that correspond to the same image subresource of an image.
  • Attachments using views of distinct image subresources which are bound to overlapping memory ranges.

Note

Render passes must include subpass dependencies (either directly or via a subpass dependency chain) between any two subpasses that operate on the same attachment or aliasing attachments and those subpass dependencies must include execution and memory dependencies separating uses of the aliases, if at least one of those subpasses writes to one of the aliases. These dependencies must not include the DEPENDENCY_BY_REGION_BIT if the aliases are views of distinct image subresources which overlap in memory.

Multiple attachments that alias the same memory must not be used in a single subpass. A given attachment index must not be used multiple times in a single subpass, with one exception: two subpass attachments can use the same attachment index if at least one use is as an input attachment and neither use is as a resolve or preserve attachment. In other words, the same view can be used simultaneously as an input and color or depth/stencil attachment, but must not be used as multiple color or depth/stencil attachments nor as resolve or preserve attachments. The precise set of valid scenarios is described in more detail below.

If a set of attachments alias each other, then all except the first to be used in the render pass must use an initialLayout of IMAGE_LAYOUT_UNDEFINED, since the earlier uses of the other aliases make their contents undefined. Once an alias has been used and a different alias has been used after it, the first alias must not be used in any later subpasses. However, an application can assign the same image view to multiple aliasing attachment indices, which allows that image view to be used multiple times even if other aliases are used in between.

Note

Once an attachment needs the ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT bit, there should be no additional cost of introducing additional aliases, and using these additional aliases may allow more efficient clearing of the attachments on multiple uses via ATTACHMENT_LOAD_OP_CLEAR.

Valid Usage

Valid Usage (Implicit)

See Also

AttachmentDescriptionFlags, AttachmentLoadOp, AttachmentStoreOp, Format, ImageLayout, RenderPassCreateInfo, SampleCountFlagBits

Constructors

AttachmentDescription 

Fields

Instances
Show AttachmentDescription Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

Storable AttachmentDescription Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

FromCStruct AttachmentDescription Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

ToCStruct AttachmentDescription Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

Zero AttachmentDescription Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

data AttachmentReference Source #

Constructors

AttachmentReference 

Fields

Instances
Show AttachmentReference Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

Storable AttachmentReference Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

FromCStruct AttachmentReference Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

ToCStruct AttachmentReference Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

Zero AttachmentReference Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

data SubpassDescription Source #

VkSubpassDescription - Structure specifying a subpass description

Description

Each element of the pInputAttachments array corresponds to an input attachment index in a fragment shader, i.e. if a shader declares an image variable decorated with a InputAttachmentIndex value of X, then it uses the attachment provided in pInputAttachments[X]. Input attachments must also be bound to the pipeline in a descriptor set. If the attachment member of any element of pInputAttachments is ATTACHMENT_UNUSED, the application must not read from the corresponding input attachment index. Fragment shaders can use subpass input variables to access the contents of an input attachment at the fragment’s (x, y, layer) framebuffer coordinates. Input attachments must not be used by any subpasses within a renderpass that enables render pass transform.

Each element of the pColorAttachments array corresponds to an output location in the shader, i.e. if the shader declares an output variable decorated with a Location value of X, then it uses the attachment provided in pColorAttachments[X]. If the attachment member of any element of pColorAttachments is ATTACHMENT_UNUSED, writes to the corresponding location by a fragment are discarded.

If pResolveAttachments is not NULL, each of its elements corresponds to a color attachment (the element in pColorAttachments at the same index), and a multisample resolve operation is defined for each attachment. At the end of each subpass, multisample resolve operations read the subpass’s color attachments, and resolve the samples for each pixel within the render area to the same pixel location in the corresponding resolve attachments, unless the resolve attachment index is ATTACHMENT_UNUSED.

Similarly, if SubpassDescriptionDepthStencilResolve::pDepthStencilResolveAttachment is not NULL and does not have the value ATTACHMENT_UNUSED, it corresponds to the depth/stencil attachment in pDepthStencilAttachment, and multisample resolve operations for depth and stencil are defined by SubpassDescriptionDepthStencilResolve::depthResolveMode and SubpassDescriptionDepthStencilResolve::stencilResolveMode, respectively. At the end of each subpass, multisample resolve operations read the subpass’s depth/stencil attachment, and resolve the samples for each pixel to the same pixel location in the corresponding resolve attachment. If SubpassDescriptionDepthStencilResolve::depthResolveMode is RESOLVE_MODE_NONE, then the depth component of the resolve attachment is not written to and its contents are preserved. Similarly, if SubpassDescriptionDepthStencilResolve::stencilResolveMode is RESOLVE_MODE_NONE, then the stencil component of the resolve attachment is not written to and its contents are preserved. SubpassDescriptionDepthStencilResolve::depthResolveMode is ignored if the Format of the pDepthStencilResolveAttachment does not have a depth component. Similarly, SubpassDescriptionDepthStencilResolve::stencilResolveMode is ignored if the Format of the pDepthStencilResolveAttachment does not have a stencil component.

If the image subresource range referenced by the depth/stencil attachment is created with IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT, then the multisample resolve operation uses the sample locations state specified in the sampleLocationsInfo member of the element of the RenderPassSampleLocationsBeginInfoEXT::pPostSubpassSampleLocations for the subpass.

If pDepthStencilAttachment is NULL, or if its attachment index is ATTACHMENT_UNUSED, it indicates that no depth/stencil attachment will be used in the subpass.

The contents of an attachment within the render area become undefined at the start of a subpass S if all of the following conditions are true:

  • The attachment is used as a color, depth/stencil, or resolve attachment in any subpass in the render pass.
  • There is a subpass S1 that uses or preserves the attachment, and a subpass dependency from S1 to S.
  • The attachment is not used or preserved in subpass S.

Once the contents of an attachment become undefined in subpass S, they remain undefined for subpasses in subpass dependency chains starting with subpass S until they are written again. However, they remain valid for subpasses in other subpass dependency chains starting with subpass S1 if those subpasses use or preserve the attachment.

Valid Usage

Valid Usage (Implicit)

  • PipelineBindPoint must be a valid PipelineBindPoint value
  • If inputAttachmentCount is not 0, pInputAttachments must be a valid pointer to an array of inputAttachmentCount valid AttachmentReference structures
  • If colorAttachmentCount is not 0, pColorAttachments must be a valid pointer to an array of colorAttachmentCount valid AttachmentReference structures
  • If colorAttachmentCount is not 0, and pResolveAttachments is not NULL, pResolveAttachments must be a valid pointer to an array of colorAttachmentCount valid AttachmentReference structures
  • If pDepthStencilAttachment is not NULL, pDepthStencilAttachment must be a valid pointer to a valid AttachmentReference structure
  • If preserveAttachmentCount is not 0, pPreserveAttachments must be a valid pointer to an array of preserveAttachmentCount uint32_t values

See Also

AttachmentReference, PipelineBindPoint, RenderPassCreateInfo, SubpassDescriptionFlags

Constructors

SubpassDescription 

Fields

data SubpassDependency Source #

VkSubpassDependency - Structure specifying a subpass dependency

Description

If srcSubpass is equal to dstSubpass then the SubpassDependency describes a subpass self-dependency, and only constrains the pipeline barriers allowed within a subpass instance. Otherwise, when a render pass instance which includes a subpass dependency is submitted to a queue, it defines a memory dependency between the subpasses identified by srcSubpass and dstSubpass.

If srcSubpass is equal to SUBPASS_EXTERNAL, the first synchronization scope includes commands that occur earlier in submission order than the cmdBeginRenderPass used to begin the render pass instance. Otherwise, the first set of commands includes all commands submitted as part of the subpass instance identified by srcSubpass and any load, store or multisample resolve operations on attachments used in srcSubpass. In either case, the first synchronization scope is limited to operations on the pipeline stages determined by the source stage mask specified by srcStageMask.

If dstSubpass is equal to SUBPASS_EXTERNAL, the second synchronization scope includes commands that occur later in submission order than the cmdEndRenderPass used to end the render pass instance. Otherwise, the second set of commands includes all commands submitted as part of the subpass instance identified by dstSubpass and any load, store or multisample resolve operations on attachments used in dstSubpass. In either case, the second synchronization scope is limited to operations on the pipeline stages determined by the destination stage mask specified by dstStageMask.

The first access scope is limited to access in the pipeline stages determined by the source stage mask specified by srcStageMask. It is also limited to access types in the source access mask specified by srcAccessMask.

The second access scope is limited to access in the pipeline stages determined by the destination stage mask specified by dstStageMask. It is also limited to access types in the destination access mask specified by dstAccessMask.

The availability and visibility operations defined by a subpass dependency affect the execution of image layout transitions within the render pass.

Note

For non-attachment resources, the memory dependency expressed by subpass dependency is nearly identical to that of a MemoryBarrier (with matching srcAccessMask and dstAccessMask parameters) submitted as a part of a cmdPipelineBarrier (with matching srcStageMask and dstStageMask parameters). The only difference being that its scopes are limited to the identified subpasses rather than potentially affecting everything before and after.

For attachments however, subpass dependencies work more like a ImageMemoryBarrier defined similarly to the MemoryBarrier above, the queue family indices set to QUEUE_FAMILY_IGNORED, and layouts as follows:

  • The equivalent to oldLayout is the attachment’s layout according to the subpass description for srcSubpass.
  • The equivalent to newLayout is the attachment’s layout according to the subpass description for dstSubpass.

Valid Usage

Valid Usage (Implicit)

See Also

AccessFlags, DependencyFlags, PipelineStageFlags, RenderPassCreateInfo

Constructors

SubpassDependency 

Fields

Instances
Show SubpassDependency Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

Storable SubpassDependency Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

FromCStruct SubpassDependency Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

ToCStruct SubpassDependency Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

Zero SubpassDependency Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

data RenderPassCreateInfo (es :: [Type]) Source #

VkRenderPassCreateInfo - Structure specifying parameters of a newly created render pass

Description

Note

Care should be taken to avoid a data race here; if any subpasses access attachments with overlapping memory locations, and one of those accesses is a write, a subpass dependency needs to be included between them.

Valid Usage

  • If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not ATTACHMENT_UNUSED, it must be less than attachmentCount

Valid Usage (Implicit)

See Also

AttachmentDescription, RenderPassCreateFlags, StructureType, SubpassDependency, SubpassDescription, createRenderPass

Constructors

RenderPassCreateInfo 

Fields

Instances
Extensible RenderPassCreateInfo Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

Show (Chain es) => Show (RenderPassCreateInfo es) Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

PeekChain es => FromCStruct (RenderPassCreateInfo es) Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

PokeChain es => ToCStruct (RenderPassCreateInfo es) Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

es ~ ([] :: [Type]) => Zero (RenderPassCreateInfo es) Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

data FramebufferCreateInfo (es :: [Type]) Source #

VkFramebufferCreateInfo - Structure specifying parameters of a newly created framebuffer

Description

Applications must ensure that all accesses to memory that backs image subresources used as attachments in a given renderpass instance either happen-before the load operations for those attachments, or happen-after the store operations for those attachments.

For depth/stencil attachments, each aspect can be used separately as attachments and non-attachments as long as the non-attachment accesses are also via an image subresource in either the IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL layout or the IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL layout, and the attachment resource uses whichever of those two layouts the image accesses do not. Use of non-attachment aspects in this case is only well defined if the attachment is used in the subpass where the non-attachment access is being made, or the layout of the image subresource is constant throughout the entire render pass instance, including the initialLayout and finalLayout.

Note

These restrictions mean that the render pass has full knowledge of all uses of all of the attachments, so that the implementation is able to make correct decisions about when and how to perform layout transitions, when to overlap execution of subpasses, etc.

It is legal for a subpass to use no color or depth/stencil attachments, and rather use shader side effects such as image stores and atomics to produce an output. In this case, the subpass continues to use the width, height, and layers of the framebuffer to define the dimensions of the rendering area, and the rasterizationSamples from each pipeline’s PipelineMultisampleStateCreateInfo to define the number of samples used in rasterization; however, if PhysicalDeviceFeatures::variableMultisampleRate is FALSE, then all pipelines to be bound with a given zero-attachment subpass must have the same value for PipelineMultisampleStateCreateInfo::rasterizationSamples.

Valid Usage

  • attachmentCount must be equal to the attachment count specified in RenderPass

Valid Usage (Implicit)

See Also

FramebufferCreateFlags, ImageView, RenderPass, StructureType, createFramebuffer

Constructors

FramebufferCreateInfo 

Fields

Instances
Extensible FramebufferCreateInfo Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

Show (Chain es) => Show (FramebufferCreateInfo es) Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

PeekChain es => FromCStruct (FramebufferCreateInfo es) Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

PokeChain es => ToCStruct (FramebufferCreateInfo es) Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass

es ~ ([] :: [Type]) => Zero (FramebufferCreateInfo es) Source # 
Instance details

Defined in Graphics.Vulkan.Core10.Pass