Package 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.

VK_EXT_discard_rectangles

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

Other Extension Metadata

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	Description
static int	VK_DISCARD_RECTANGLE_MODE_EXCLUSIVE_EXT 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 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	vkCmdSetDiscardRectangleEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, int firstDiscardRectangle, VkRect2D.Buffer pDiscardRectangles)	Set discard rectangles dynamically for a command buffer.

Methods inherited from class java.lang.Object

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

Field Detail

VK_EXT_DISCARD_RECTANGLES_SPEC_VERSION

The extension specification version.

VK_EXT_DISCARD_RECTANGLES_EXTENSION_NAME

The extension name.

VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DISCARD_RECTANGLE_PROPERTIES_EXT, 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

VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT

Extends VkDynamicState.

VK_DISCARD_RECTANGLE_MODE_INCLUSIVE_EXT, 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

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 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 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
• 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
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.