Package org.lwjgl.vulkan

Class EXTSampleLocations

java.lang.Object

org.lwjgl.vulkan.EXTSampleLocations

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

• Requires Vulkan 1.0
• Requires VK_KHR_get_physical_device_properties2

Contact

• Daniel Rakos drakos-amd

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 int	VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT	Extends VkDynamicState.
static java.lang.String	VK_EXT_SAMPLE_LOCATIONS_EXTENSION_NAME	The extension name.
static int	VK_EXT_SAMPLE_LOCATIONS_SPEC_VERSION	The extension specification version.
static int	VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT	Extends VkImageCreateFlagBits.
static int	VK_STRUCTURE_TYPE_MULTISAMPLE_PROPERTIES_EXT VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT	Extends VkStructureType.

Method Summary

Modifier and Type	Method	Description
static void	nvkCmdSetSampleLocationsEXT(VkCommandBuffer commandBuffer, long pSampleLocationsInfo)	Unsafe version of: CmdSetSampleLocationsEXT
static void	nvkGetPhysicalDeviceMultisamplePropertiesEXT(VkPhysicalDevice physicalDevice, int samples, long pMultisampleProperties)	Unsafe version of: GetPhysicalDeviceMultisamplePropertiesEXT
static void	vkCmdSetSampleLocationsEXT(VkCommandBuffer commandBuffer, VkSampleLocationsInfoEXT pSampleLocationsInfo)	Set the dynamic sample locations state.
static void	vkGetPhysicalDeviceMultisamplePropertiesEXT(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 Detail

VK_EXT_SAMPLE_LOCATIONS_SPEC_VERSION

The extension specification version.

VK_EXT_SAMPLE_LOCATIONS_EXTENSION_NAME

The extension name.

VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT

Extends VkImageCreateFlagBits.

VK_STRUCTURE_TYPE_SAMPLE_LOCATIONS_INFO_EXT, VK_STRUCTURE_TYPE_RENDER_PASS_SAMPLE_LOCATIONS_BEGIN_INFO_EXT, VK_STRUCTURE_TYPE_PIPELINE_SAMPLE_LOCATIONS_STATE_CREATE_INFO_EXT, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLE_LOCATIONS_PROPERTIES_EXT, 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

VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT

Extends VkDynamicState.

Method Detail

nvkCmdSetSampleLocationsEXT

public static void nvkCmdSetSampleLocationsEXT(VkCommandBuffer commandBuffer,
                                               long pSampleLocationsInfo)

Unsafe version of: CmdSetSampleLocationsEXT

vkCmdSetSampleLocationsEXT

public static void vkCmdSetSampleLocationsEXT(VkCommandBuffer commandBuffer,
                                              VkSampleLocationsInfoEXT pSampleLocationsInfo)

Set the dynamic sample locations state.

C Specification

The custom sample locations used for rasterization when VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsEnable is TRUE are specified by the VkPipelineSampleLocationsStateCreateInfoEXT::sampleLocationsInfo property of the bound graphics pipeline, if the pipeline was not created with DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled.

Otherwise, the sample locations used for rasterization are set by calling vkCmdSetSampleLocationsEXT:

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

Valid Usage

• The bound graphics pipeline must have been created with the DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT dynamic state enabled
• The sampleLocationsPerPixel member of pSampleLocationsInfo must equal the rasterizationSamples member of the VkPipelineMultisampleStateCreateInfo structure the bound graphics pipeline has been created with
• 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

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

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(VkPhysicalDevice physicalDevice,
                                                                int samples,
                                                                long pMultisampleProperties)

Unsafe version of: GetPhysicalDeviceMultisamplePropertiesEXT

vkGetPhysicalDeviceMultisamplePropertiesEXT

public static void vkGetPhysicalDeviceMultisamplePropertiesEXT(VkPhysicalDevice physicalDevice,
                                                               int samples,
                                                               VkMultisamplePropertiesEXT pMultisampleProperties)

Report sample count specific multisampling capabilities of a physical device.

C Specification

In addition to the minimum capabilities described for (Limits) above, implementations may support additional multisampling capabilities specific to a particular sample count.

To query additional sample count specific multisampling capabilities, 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 - the sample count to query the capabilities for.

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