HORIZON HASKELLDocslts/ghc-9.14.x45dd5372026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 45dd537 · 2026-10-11

Modulevulkan-3.27GHC2021

Vulkan.Extensions.VK_EXT_discard_rectangles

Name

VK_EXT_discard_rectangles - device extension

VK_EXT_discard_rectangles

Name String

VK_EXT_discard_rectangles

Extension Type

Device extension

Registered Extension Number

100

Revision

2

Ratification Status

Ratified

Extension and Version Dependencies

VK_KHR_get_physical_device_properties2

or

Vulkan Version 1.1

Contact

Other Extension Metadata

Last Modified Date

2023-01-18

Interactions and External Dependencies

  • Interacts with VK_KHR_device_group

  • Interacts with Vulkan 1.1

Contributors

  • Daniel Koch, NVIDIA

  • Jeff Bolz, NVIDIA

Description

This extension provides additional orthogonally aligned “discard rectangles” specified in framebuffer-space coordinates that restrict rasterization of all points, lines, and triangles.

From zero to an implementation-dependent limit (specified by maxDiscardRectangles) number of discard rectangles can be operational at once. When one or more discard rectangles are active, rasterized fragments can either survive if the fragment is within any of the operational discard rectangles (DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT mode) or be rejected if the fragment is within any of the operational discard rectangles (DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT mode).

These discard rectangles operate orthogonally to the existing scissor test functionality. The discard rectangles can be different for each physical device in a device group by specifying the device mask and setting discard rectangle dynamic state.

Version 2 of this extension introduces new dynamic states DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT and DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT, and the corresponding functions cmdSetDiscardRectangleEnableEXT and cmdSetDiscardRectangleModeEXT. Applications that use these dynamic states must ensure the implementation advertises at least specVersion 2 of this extension.

New Commands

New Structures

New Enums

New Bitmasks

New Enum Constants

Version History

  • Revision 2, 2023-01-18 (Piers Daniell)

    • Add dynamic states for discard rectangle enable/disable and mode.

  • Revision 1, 2016-12-22 (Piers Daniell)

    • Internal revisions

See Also

No cross-references are available

Document Notes

For more information, see the Vulkan Specification.

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

  • 6 types
  • 3 values
  • Packagevulkan-3.27
  • Exports13
  • LanguageGHC2021
  • LicenceBSD-3-Clause
  • SourceVK_EXT_discard_rectangles.hs
valuecmdSetDiscardRectangleEXT
  1. :: MonadIO io
  2. => CommandBuffer

    commandBuffer is the command buffer into which the command will be recorded.

  3. -> "firstDiscardRectangle" ::: Word32

    firstDiscardRectangle is the index of the first discard rectangle whose state is updated by the command.

  4. -> "discardRectangles" ::: Vector Rect2D

    pDiscardRectangles is a pointer to an array of Rect2D structures specifying discard rectangles.

  5. -> io ()
#

vkCmdSetDiscardRectangleEXT - Set discard rectangles dynamically for a command buffer

Description

The discard rectangle taken from element i of pDiscardRectangles replace the current state for the discard rectangle at index firstDiscardRectangle + i, for i in [0, discardRectangleCount).

This command sets the discard rectangles for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_DISCARD_RECTANGLE_EXT set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineDiscardRectangleStateCreateInfoEXT::pDiscardRectangles values used to create the currently active pipeline.

Valid Usage

  • The x and y member of offset in each Rect2D element of pDiscardRectangles must be greater than or equal to 0

  • Evaluation of (offset.x + extent.width) in each Rect2D element of pDiscardRectangles must not cause a signed integer addition overflow

  • Evaluation of (offset.y + extent.height) in each Rect2D element of pDiscardRectangles must not cause a signed integer addition overflow

  • If this command is recorded in a secondary command buffer with CommandBufferInheritanceViewportScissorInfoNV::viewportScissor2D enabled, then this function must not be called

Valid Usage (Implicit)

  • pDiscardRectangles must be a valid pointer to an array of discardRectangleCount Rect2D structures

  • commandBuffer must be in the recording state

  • The CommandPool that commandBuffer was allocated from must support QUEUE_GRAPHICS_BIT operations

  • This command must only be called outside of a video coding scope

  • discardRectangleCount must be greater than 0

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary Secondary

Both

Outside

VK_QUEUE_GRAPHICS_BIT

State

Conditional Rendering

vkCmdSetDiscardRectangleEXT is not affected by conditional rendering

See Also

VK_EXT_discard_rectangles, CommandBuffer, Rect2D

valuecmdSetDiscardRectangleEnableEXT
  1. :: MonadIO io
  2. => CommandBuffer

    commandBuffer is the command buffer into which the command will be recorded.

  3. -> "discardRectangleEnable" ::: Bool

    discardRectangleEnable specifies whether discard rectangles are enabled or not.

  4. -> io ()
#

vkCmdSetDiscardRectangleEnableEXT - Enable discard rectangles dynamically for a command buffer

Description

This command sets the discard rectangle enable for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is implied by the PipelineDiscardRectangleStateCreateInfoEXT::discardRectangleCount value used to create the currently active pipeline, where a non-zero discardRectangleCount implicitly enables discard rectangles, otherwise they are disabled.

Valid Usage

  • The VK_EXT_discard_rectangles extension must be enabled, and the implementation must support at least specVersion 2 of this extension

Valid Usage (Implicit)

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary Secondary

Both

Outside

VK_QUEUE_GRAPHICS_BIT

State

Conditional Rendering

vkCmdSetDiscardRectangleEnableEXT is not affected by conditional rendering

See Also

VK_EXT_discard_rectangles, Bool32, CommandBuffer

valuecmdSetDiscardRectangleModeEXT
  1. :: MonadIO io
  2. => CommandBuffer

    commandBuffer is the command buffer into which the command will be recorded.

  3. -> DiscardRectangleModeEXT

    discardRectangleMode specifies the discard rectangle mode for all discard rectangles, either inclusive or exclusive.

  4. -> io ()
#

vkCmdSetDiscardRectangleModeEXT - Sets the discard rectangle mode dynamically for a command buffer

Description

This command sets the discard rectangle mode for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the PipelineDiscardRectangleStateCreateInfoEXT::discardRectangleMode value used to create the currently active pipeline.

Valid Usage

  • The VK_EXT_discard_rectangles extension must be enabled, and the implementation must support at least specVersion 2 of this extension

Valid Usage (Implicit)

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary Secondary

Both

Outside

VK_QUEUE_GRAPHICS_BIT

State

Conditional Rendering

vkCmdSetDiscardRectangleModeEXT is not affected by conditional rendering

See Also

VK_EXT_discard_rectangles, CommandBuffer, DiscardRectangleModeEXT

datadata PhysicalDeviceDiscardRectanglePropertiesEXT
#

VkPhysicalDeviceDiscardRectanglePropertiesEXT - Structure describing discard rectangle limits that can be supported by an implementation

Description

If the PhysicalDeviceDiscardRectanglePropertiesEXT structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Structure Chaining

Extends the structure

See Also

VK_EXT_discard_rectangles, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata PipelineDiscardRectangleStateCreateInfoEXT
#

VkPipelineDiscardRectangleStateCreateInfoEXT - Structure specifying discard rectangle

Description

If the DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is enabled for a pipeline, the pDiscardRectangles member is ignored. If the DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT dynamic state is not enabled for the pipeline the presence of this structure in the GraphicsPipelineCreateInfo chain, and a discardRectangleCount greater than zero, implicitly enables discard rectangles in the pipeline, otherwise discard rectangles must enabled or disabled by cmdSetDiscardRectangleEnableEXT. If the DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT dynamic state is enabled for the pipeline, the discardRectangleMode member is ignored, and the discard rectangle mode must be set by cmdSetDiscardRectangleModeEXT.

When this structure is included in the pNext chain of GraphicsPipelineCreateInfo, it defines parameters of the discard rectangle test. If the DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state is not enabled, and this structure is not included in the pNext chain, it is equivalent to specifying this structure with a discardRectangleCount of 0. If all DYNAMIC_STATE_DISCARD_RECTANGLE_EXT, DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT, and DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT dynamic states are enabled, the application can omit this structure from the pNext chain of GraphicsPipelineCreateInfo and still use discard rectangles by setting all state dynamically. In this case cmdSetDiscardRectangleEXT must be called to set the discard rectangle for all indices [0, maxDiscardRectangles) before drawing with discard rectangles enabled. Individual discard rectangles can be made ineffective by setting their Rect2D::extent.width and Rect2D::extent.height to zero.

Structure Chaining

Extends the structure

See Also

VK_EXT_discard_rectangles, DiscardRectangleModeEXT, PipelineDiscardRectangleStateCreateFlagsEXT, Rect2D, StructureType

Constructors

Instances4Show, FromCStruct, ToCStruct, Zero
newtypenewtype PipelineDiscardRectangleStateCreateFlagsEXT
#

VkPipelineDiscardRectangleStateCreateFlagsEXT - Reserved for future use

Description

PipelineDiscardRectangleStateCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

VK_EXT_discard_rectangles, Flags, PipelineDiscardRectangleStateCreateInfoEXT

Constructors

Instances8Eq, Ord, Read, Show, Bits, FiniteBits, …
newtypenewtype DiscardRectangleModeEXT
#

VkDiscardRectangleModeEXT - Specify the discard rectangle mode

Description

See Also

VK_EXT_discard_rectangles, PipelineDiscardRectangleStateCreateInfoEXT, cmdSetDiscardRectangleModeEXT

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero