org.lwjgl.vulkan

Class EXTDiscardRectangles

java.lang.Object

org.lwjgl.vulkan.EXTDiscardRectangles

public class EXTDiscardRectangles
extends java.lang.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.

Name String

VK_EXT_discard_rectangles

Extension Type

Device extension

Registered Extension Number

100

Revision

1

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_KHR_get_physical_device_properties2

Contact

• Piers Daniell pdaniell-nv

Last Modified Date

2016-12-22

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 and Description
static int	VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT VkDiscardRectangleModeEXT - Specify the discard rectangle mode
static int	VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT VkDiscardRectangleModeEXT - Specify the discard rectangle mode
static int	VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT Extends VkDynamicState.
static java.lang.String	VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME The extension name.
static int	VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION The extension specification version.
static int	VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT Extends VkStructureType.
static int	VK_STRUCTURE_TYPE_PIPELINE_DISCARD_RECTANGLE_STATE_CREATE_INFO_EXT Extends VkStructureType.

Method Summary

Modifier and Type	Method and Description
static void	nvkCmdSetDiscardRectangleEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, int firstDiscardRectangle, int discardRectangleCount, long pDiscardRectangles) Unsafe version of: CmdSetDiscardRectangleEXT
static void	vkCmdSetDiscardRectangleEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, int firstDiscardRectangle, VkRect2D.Buffer pDiscardRectangles) Set discard rectangles dynamically.

Methods inherited from class java.lang.Object

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

Field Detail

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 java.lang.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.

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 a fragment within any discard rectangle satisfies the test.
• DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that a fragment not within any of the discard rectangles satisfies the test.

See Also

VkPipelineDiscardRectangleStateCreateInfoEXT

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 a fragment within any discard rectangle satisfies the test.
• DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT specifies that a fragment not within any of the discard rectangles satisfies the test.

See Also

VkPipelineDiscardRectangleStateCreateInfoEXT

See Also:

Constant Field Values

Method Detail

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.

C Specification

If the pipeline state object was created with the DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state enabled, the discard rectangles are dynamically set and changed with the command:

 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 index firstDiscardRectangle + i, for i in [0, discardRectangleCount).

Valid Usage

• The bound graphics pipeline must have been created with the DYNAMIC_STATE_DISCARD_RECTANGLE_EXT dynamic state enabled
• 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

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
• 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	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics

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.