Package org.lwjgl.vulkan

Class EXTSampleLocations

java.lang.Object

org.lwjgl.vulkan.EXTSampleLocations

public class EXTSampleLocations
extends Object

This extension allows an application to modify the locations of samples within a pixel used in rasterization. Additionally, it allows applications to specify different sample locations for each pixel in a group of adjacent pixels, which can increase antialiasing quality (particularly if a custom resolve shader is used that takes advantage of these different locations).

It is common for implementations to optimize the storage of depth values by storing values that can be used to reconstruct depth at each sample location, rather than storing separate depth values for each sample. For example, the depth values from a single triangle may be represented using plane equations. When the depth value for a sample is needed, it is automatically evaluated at the sample location. Modifying the sample locations causes the reconstruction to no longer evaluate the same depth values as when the samples were originally generated, thus the depth aspect of a depth/stencil attachment must be cleared before rendering to it using different sample locations.

Some implementations may need to evaluate depth image values while performing image layout transitions. To accommodate this, instances of the VkSampleLocationsInfoEXT structure can be specified for each situation where an explicit or automatic layout transition has to take place. VkSampleLocationsInfoEXT can be chained from VkImageMemoryBarrier structures to provide sample locations for layout transitions performed by CmdWaitEvents and CmdPipelineBarrier calls, and VkRenderPassSampleLocationsBeginInfoEXT can be chained from VkRenderPassBeginInfo to provide sample locations for layout transitions performed implicitly by a render pass instance.

Name String

VK_EXT_sample_locations

Extension Type

Device extension

Registered Extension Number

144

Revision

1

Extension and Version Dependencies

VK_KHR_get_physical_device_properties2 or Version 1.1

Contact

• Daniel Rakos drakos-amd

Other Extension Metadata

Last Modified Date

2017-08-02

Contributors

• Mais Alnasser, AMD
• Matthaeus G. Chajdas, AMD
• Maciej Jesionowski, AMD
• Daniel Rakos, AMD
• Slawomir Grajewski, Intel
• Jeff Bolz, NVIDIA
• Bill Licea-Kane, Qualcomm

Field Summary

Fields

Modifier and Type	Field	Description
static final int	VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT	Extends VkDynamicState.
static final String	VK_EXT_SAMPLE_LOCATIONS_EXTENSION_NAME	The extension name.
static final int	VK_EXT_SAMPLE_LOCATIONS_SPEC_VERSION	The extension specification version.
static final int	VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT	Extends VkImageCreateFlagBits.
static final int	VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT	Extends VkStructureType.
static final int	VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT	Extends VkStructureType.
static final int	VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT	Extends VkStructureType.
static final int	VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT	Extends VkStructureType.
static final int	VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT	Extends VkStructureType.

Method Summary

Modifier and Type	Method	Description
static void	nvkCmdSetSampleLocationsEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, long pSampleLocationsInfo)	Unsafe version of: CmdSetSampleLocationsEXT
static void	nvkGetPhysicalDeviceMultisamplePropertiesEXT(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, int samples, long pMultisampleProperties)	Unsafe version of: GetPhysicalDeviceMultisamplePropertiesEXT
static void	vkCmdSetSampleLocationsEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, VkSampleLocationsInfoEXT pSampleLocationsInfo)	Set sample locations dynamically for a command buffer.
static void	vkGetPhysicalDeviceMultisamplePropertiesEXT(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice, int samples, VkMultisamplePropertiesEXT pMultisampleProperties)	Report sample count specific multisampling capabilities of a physical device.

Methods inherited from class java.lang.Object

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

Field Details

VK_EXT_SAMPLE_LOCATIONS_SPEC_VERSION

public static final int VK_EXT_SAMPLE_LOCATIONS_SPEC_VERSION

The extension specification version.

See Also:

• Constant Field Values

VK_EXT_SAMPLE_LOCATIONS_EXTENSION_NAME

public static final String VK_EXT_SAMPLE_LOCATIONS_EXTENSION_NAME

The extension name.

See Also:

• Constant Field Values

VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT

public static final int VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT

Extends VkImageCreateFlagBits.

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT

public static final int VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT
• STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT
• STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT
• STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT
• STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT

public static final int VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT
• STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT
• STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT
• STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT
• STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT

public static final int VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT
• STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT
• STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT
• STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT
• STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT

public static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT
• STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT
• STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT
• STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT
• STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT

public static final int VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT
• STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT
• STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT
• STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT
• STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT

See Also:

• Constant Field Values

VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT

public static final int VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT

Extends VkDynamicState.

See Also:

• Constant Field Values

Method Details

nvkCmdSetSampleLocationsEXT

public static void nvkCmdSetSampleLocationsEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
 long pSampleLocationsInfo)

Unsafe version of: CmdSetSampleLocationsEXT

vkCmdSetSampleLocationsEXT

public static void vkCmdSetSampleLocationsEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
 VkSampleLocationsInfoEXT pSampleLocationsInfo)

Set sample locations dynamically for a command buffer.

C Specification

To dynamically set the sample locations used for rasterization, call:

 void vkCmdSetSampleLocationsEXT(
     VkCommandBuffer                             commandBuffer,
     const VkSampleLocationsInfoEXT*             pSampleLocationsInfo);

Description

This command sets the custom sample locations for subsequent drawing commands when drawing using shader objects, or when the graphics pipeline is created with DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT set in VkPipelineDynamicStateCreateInfo::pDynamicStates, and when the VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable property of the bound graphics pipeline is TRUE. Otherwise, this state is specified by the VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsInfo values used to create the currently active pipeline.

Valid Usage

• If VkPhysicalDeviceSampleLocationsPropertiesEXT::variableSampleLocations is FALSE then the current render pass must have been begun by specifying a VkRenderPassSampleLocationsBeginInfoEXT structure whose pPostSubpassSampleLocations member contains an element with a subpassIndex matching the current subpass index and the sampleLocationsInfo member of that element must match the sample locations state pointed to by pSampleLocationsInfo

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle
• pSampleLocationsInfo must be a valid pointer to a valid VkSampleLocationsInfoEXT structure
• 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

See Also

VkSampleLocationsInfoEXT

Parameters:

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

pSampleLocationsInfo - the sample locations state to set.

nvkGetPhysicalDeviceMultisamplePropertiesEXT

public static void nvkGetPhysicalDeviceMultisamplePropertiesEXT(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice,
 int samples,
 long pMultisampleProperties)

Unsafe version of: GetPhysicalDeviceMultisamplePropertiesEXT

vkGetPhysicalDeviceMultisamplePropertiesEXT

public static void vkGetPhysicalDeviceMultisamplePropertiesEXT(org.lwjgl.vulkan.VkPhysicalDevice physicalDevice,
 int samples,
 VkMultisamplePropertiesEXT pMultisampleProperties)

Report sample count specific multisampling capabilities of a physical device.

C Specification

To query additional multisampling capabilities which may be supported for a specific sample count, beyond the minimum capabilities described for Limits above, call:

 void vkGetPhysicalDeviceMultisamplePropertiesEXT(
     VkPhysicalDevice                            physicalDevice,
     VkSampleCountFlagBits                       samples,
     VkMultisamplePropertiesEXT*                 pMultisampleProperties);

Valid Usage (Implicit)

• physicalDevice must be a valid VkPhysicalDevice handle
• samples must be a valid VkSampleCountFlagBits value
• pMultisampleProperties must be a valid pointer to a VkMultisamplePropertiesEXT structure

See Also

VkMultisamplePropertiesEXT

Parameters:

physicalDevice - the physical device from which to query the additional multisampling capabilities.

samples - a VkSampleCountFlagBits value specifying the sample count to query capabilities for.

pMultisampleProperties - a pointer to a VkMultisamplePropertiesEXT structure in which information about additional multisampling capabilities specific to the sample count is returned.