Package org.lwjgl.vulkan

Class EXTDiscardRectangles

java.lang.Object

org.lwjgl.vulkan.EXTDiscardRectangles

public class EXTDiscardRectangles
extends Object

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.

Name String

VK_EXT_discard_rectangles

Extension Type

Device extension

Registered Extension Number

100

Revision

2

Extension and Version Dependencies

VK_KHR_get_physical_device_properties2 or Version 1.1

Contact

• Piers Daniell pdaniell-nv

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

Field Summary

Fields

Modifier and Type	Field	Description
static final int	VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT	VkDiscardRectangleModeEXT - Specify the discard rectangle mode
static final int	VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT	VkDiscardRectangleModeEXT - Specify the discard rectangle mode
static final int	VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT	Extends VkDynamicState.
static final int	VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT	Extends VkDynamicState.
static final int	VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT	Extends VkDynamicState.
static final String	VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME	The extension name.
static final int	VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION	The extension specification version.
static final int	VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT	Extends VkStructureType.
static final int	VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT	Extends VkStructureType.

Method Summary

Modifier and Type	Method	Description
static void	nvkCmdSetDiscardRectangleEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, int firstDiscardRectangle, int discardRectangleCount, long pDiscardRectangles)	Unsafe version of: CmdSetDiscardRectangleEXT
static void	vkCmdSetDiscardRectangleEnableEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, boolean discardRectangleEnable)	Enable discard rectangles dynamically for a command buffer.
static void	vkCmdSetDiscardRectangleEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, int firstDiscardRectangle, VkRect2D.Buffer pDiscardRectangles)	Set discard rectangles dynamically for a command buffer.
static void	vkCmdSetDiscardRectangleModeEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, int discardRectangleMode)	Sets the discard rectangle mode dynamically for a command buffer.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION

public static final int VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION

The extension specification version.

See Also:

• Constant Field Values

VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME

public static final String VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME

The extension name.

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT

public static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT
• STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT

public static final int VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT
• STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT

See Also:

• Constant Field Values

VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT

public static final int VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT

Extends VkDynamicState.

Enum values:

• DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
• DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT
• DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT

See Also:

• Constant Field Values

VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT

public static final int VK_DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT

Extends VkDynamicState.

Enum values:

• DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
• DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT
• DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT

See Also:

• Constant Field Values

VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT

public static final int VK_DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT

Extends VkDynamicState.

Enum values:

• DYNAMIC_STATE_DISCARD_RECTANGLE_EXT
• DYNAMIC_STATE_DISCARD_RECTANGLE_ENABLE_EXT
• DYNAMIC_STATE_DISCARD_RECTANGLE_MODE_EXT

See Also:

• Constant Field Values

VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT

public static final int VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT

VkDiscardRectangleModeEXT - Specify the discard rectangle mode

Description

• DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT specifies that the discard rectangle test is inclusive.
• DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that the discard rectangle test is exclusive.

See Also

VkPipelineDiscardRectangleStateCreateInfoEXT, CmdSetDiscardRectangleModeEXT

See Also:

• Constant Field Values

VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT

public static final int VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT

VkDiscardRectangleModeEXT - Specify the discard rectangle mode

Description

• DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT specifies that the discard rectangle test is inclusive.
• DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that the discard rectangle test is exclusive.

See Also

VkPipelineDiscardRectangleStateCreateInfoEXT, CmdSetDiscardRectangleModeEXT

See Also:

• Constant Field Values

Method Details

nvkCmdSetDiscardRectangleEXT

public static void nvkCmdSetDiscardRectangleEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
 int firstDiscardRectangle,
 int discardRectangleCount,
 long pDiscardRectangles)

Unsafe version of: CmdSetDiscardRectangleEXT

Parameters:

discardRectangleCount - the number of discard rectangles whose state are updated by the command.

vkCmdSetDiscardRectangleEXT

public static void vkCmdSetDiscardRectangleEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
 int firstDiscardRectangle,
 VkRect2D.Buffer pDiscardRectangles)

Set discard rectangles dynamically for a command buffer.

C Specification

To dynamically set the discard rectangles, call:

 void vkCmdSetDiscardRectangleEXT(
     VkCommandBuffer                             commandBuffer,
     uint32_t                                    firstDiscardRectangle,
     uint32_t                                    discardRectangleCount,
     const VkRect2D*                             pDiscardRectangles);

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 VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineDiscardRectangleStateCreateInfoEXT::pDiscardRectangles values used to create the currently active pipeline.

Valid Usage

• The sum of firstDiscardRectangle and discardRectangleCount must be less than or equal to VkPhysicalDeviceDiscardRectanglePropertiesEXT::maxDiscardRectangles
• The x and y member of offset in each VkRect2D element of pDiscardRectangles must be greater than or equal to 0
• Evaluation of (offset.x + extent.width) in each VkRect2D element of pDiscardRectangles must not cause a signed integer addition overflow
• Evaluation of (offset.y + extent.height) in each VkRect2D element of pDiscardRectangles must not cause a signed integer addition overflow
• If this command is recorded in a secondary command buffer with VkCommandBufferInheritanceViewportScissorInfoNV::viewportScissor2D enabled, then this function must not be called

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle
• pDiscardRectangles must be a valid pointer to an array of discardRectangleCount VkRect2D structures
• commandBuffer must be in the recording state
• The VkCommandPool that commandBuffer was allocated from must support graphics 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 VkCommandPool 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	Graphics	State

See Also

VkRect2D

Parameters:

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

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

pDiscardRectangles - a pointer to an array of VkRect2D structures specifying discard rectangles.

vkCmdSetDiscardRectangleEnableEXT

public static void vkCmdSetDiscardRectangleEnableEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
 boolean discardRectangleEnable)

Enable discard rectangles dynamically for a command buffer.

C Specification

To dynamically set whether discard rectangles are enabled, call:

 void vkCmdSetDiscardRectangleEnableEXT(
     VkCommandBuffer                             commandBuffer,
     VkBool32                                    discardRectangleEnable);

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 VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is implied by the VkPipelineDiscardRectangleStateCreateInfoEXT::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)

• commandBuffer must be a valid VkCommandBuffer handle
• commandBuffer must be in the recording state
• The VkCommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called outside of a video coding scope

Host Synchronization

• Host access to commandBuffer must be externally synchronized
• Host access to the VkCommandPool 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	Graphics	State

Parameters:

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

discardRectangleEnable - specifies whether discard rectangles are enabled or not.

vkCmdSetDiscardRectangleModeEXT

public static void vkCmdSetDiscardRectangleModeEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
 int discardRectangleMode)

Sets the discard rectangle mode dynamically for a command buffer.

C Specification

To dynamically set the discard rectangle mode, call:

 void vkCmdSetDiscardRectangleModeEXT(
     VkCommandBuffer                             commandBuffer,
     VkDiscardRectangleModeEXT                   discardRectangleMode);

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 VkPipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, this state is specified by the VkPipelineDiscardRectangleStateCreateInfoEXT::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)

• commandBuffer must be a valid VkCommandBuffer handle
• discardRectangleMode must be a valid VkDiscardRectangleModeEXT value
• commandBuffer must be in the recording state
• The VkCommandPool that commandBuffer was allocated from must support graphics operations
• This command must only be called outside of a video coding scope

Host Synchronization

• Host access to commandBuffer must be externally synchronized
• Host access to the VkCommandPool 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	Graphics	State

Parameters:

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

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