vkCreateSampler - Create a new sampler object

Valid Usage

• device must support at least one queue family with one of the QUEUE_COMPUTE_BIT or QUEUE_GRAPHICS_BIT capabilities

• There must be less than PhysicalDeviceLimits::maxSamplerAllocationCount Sampler objects currently created on the device
• If there are any pipelines or shaders with embedded samplers currently created on the device, there must be less than (maxSamplerAllocationCount
• (minSamplerHeapReservedRangeWithEmbedded / samplerDescriptorSize)) Sampler objects currently created on the device

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid SamplerCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pSampler must be a valid pointer to a Sampler handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_VERSION_1_0, AllocationCallbacks, Device, Sampler, SamplerCreateInfo

A convenience wrapper to make a compatible pair of calls to createSampler and destroySampler

To ensure that destroySampler is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkDestroySampler - Destroy a sampler object

Valid Usage

• All submitted commands that refer to sampler must have completed execution

• If AllocationCallbacks were provided when sampler was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when sampler was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If sampler is not NULL_HANDLE, sampler must be a valid Sampler handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If sampler is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to sampler must be externally synchronized

See Also

VK_VERSION_1_0, AllocationCallbacks, Device, Sampler

VkSamplerCreateInfo - Structure specifying parameters of a newly created sampler

Description

Mapping of OpenGL to Vulkan Filter Modes

magFilter values of FILTER_NEAREST and FILTER_LINEAR directly correspond to GL_NEAREST and GL_LINEAR magnification filters. minFilter and mipmapMode combine to correspond to the similarly named OpenGL minification filter of GL_minFilter_MIPMAP_mipmapMode (e.g. minFilter of FILTER_LINEAR and mipmapMode of SAMPLER_MIPMAP_MODE_NEAREST correspond to GL_LINEAR_MIPMAP_NEAREST).

There are no Vulkan filter modes that directly correspond to OpenGL minification filters of GL_LINEAR or GL_NEAREST, but they can be emulated using SAMPLER_MIPMAP_MODE_NEAREST, minLod = 0, and maxLod = 0.25, and using minFilter = FILTER_LINEAR or minFilter = FILTER_NEAREST, respectively.

Note that using a maxLod of zero would cause magnification to always be performed, and the magFilter to always be used. This is valid, just not an exact match for OpenGL behavior. Clamping the maximum LOD to 0.25 allows the λ value to be non-zero and minification to be performed, while still always rounding down to the base level. If the minFilter and magFilter are equal, then using a maxLod of zero also works.

The maximum number of sampler objects which can be simultaneously created on a device is implementation-dependent and specified by the maxSamplerAllocationCount member of the PhysicalDeviceLimits structure.

For historical reasons, if maxSamplerAllocationCount is exceeded, some implementations may return ERROR_TOO_MANY_OBJECTS. Exceeding this limit will result in undefined behavior, and an application should not rely on the use of the returned error code in order to identify when the limit is reached.

Since Sampler is a non-dispatchable handle type, implementations may return the same handle for sampler state vectors that are identical. In such cases, all such objects would only count once against the maxSamplerAllocationCount limit.

When this structure is used to write a descriptor via writeSamplerDescriptorsEXT, applications can give the descriptor a debug name in a similar way to naming an object, via the DebugUtilsObjectNameInfoEXT structure. However, as there is no actual object, DebugUtilsObjectNameInfoEXT must be passed via the pNext chain of this structure, with a objectType of OBJECT_TYPE_UNKNOWN and a objectHandle of NULL_HANDLE. The name is attached to the unique set of descriptor bits written by the implementation, and writing the same bits again with new debug info may rename the original descriptor.

Implementations are not prevented from returning the same bits for different descriptors. This can result in multiple different samplers mapping to the same name.

DescriptorSetAndBindingMappingEXT can also be chained in the same way when defining an embedded sampler via DescriptorSetAndBindingMappingEXT, naming the embedded sampler.

Valid Usage

• The absolute value of mipLodBias must be less than or equal to PhysicalDeviceLimits::maxSamplerLodBias

• If the VK_KHR_portability_subset extension is enabled, and PhysicalDevicePortabilitySubsetFeaturesKHR::samplerMipLodBias is FALSE, mipLodBias must be zero
• maxLod must be greater than or equal to minLod
• If the samplerAnisotropy feature is not enabled, anisotropyEnable must be FALSE
• If anisotropyEnable is TRUE, maxAnisotropy must be between 1.0 and PhysicalDeviceLimits::maxSamplerAnisotropy, inclusive
• If sampler Y′CBCR conversion is enabled and the potential format features of the sampler Y′CBCR conversion do not support FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, minFilter and magFilter must be equal to the sampler Y′CBCR conversion’s chromaFilter
• If unnormalizedCoordinates is TRUE, minFilter and magFilter must be equal
• If unnormalizedCoordinates is TRUE, mipmapMode must be SAMPLER_MIPMAP_MODE_NEAREST
• If unnormalizedCoordinates is TRUE, minLod and maxLod must be zero
• If unnormalizedCoordinates is TRUE, addressModeU and addressModeV must each be either SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER
• If unnormalizedCoordinates is TRUE, anisotropyEnable must be FALSE
• If unnormalizedCoordinates is TRUE, compareEnable must be FALSE
• If any of addressModeU, addressModeV or addressModeW are SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, borderColor must be a valid BorderColor value
• If sampler Y′CBCR conversion is enabled, addressModeU, addressModeV, and addressModeW must be SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, anisotropyEnable must be FALSE, and unnormalizedCoordinates must be FALSE
• If sampler Y′CBCR conversion is enabled and the pNext chain includes a SamplerReductionModeCreateInfo structure, then the sampler reduction mode must be SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
• If the samplerFilterMinmax feature is not enabled and the pNext chain includes a SamplerReductionModeCreateInfo structure, then the sampler reduction mode must be SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
• If the samplerMirrorClampToEdge feature is not enabled, and if the VK_KHR_sampler_mirror_clamp_to_edge extension is not enabled, addressModeU, addressModeV and addressModeW must not be SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
• If compareEnable is TRUE, compareOp must be a valid CompareOp value
• If either magFilter or minFilter is FILTER_CUBIC_EXT, anisotropyEnable must be FALSE
• If the VK_EXT_filter_cubic extension is not enabled and either magFilter or minFilter is FILTER_CUBIC_IMG, the reductionMode member of SamplerReductionModeCreateInfo must be SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
• If compareEnable is TRUE, the reductionMode member of SamplerReductionModeCreateInfo must be SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then minFilter and magFilter must be equal
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then mipmapMode must be SAMPLER_MIPMAP_MODE_NEAREST
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then minLod and maxLod must be zero
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then addressModeU and addressModeV must each be either SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then anisotropyEnable must be FALSE
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then compareEnable must be FALSE
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then unnormalizedCoordinates must be FALSE
• If the nonSeamlessCubeMap feature is not enabled, flags must not include SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT
• If borderColor is one of BORDER_COLOR_FLOAT_CUSTOM_EXT or BORDER_COLOR_INT_CUSTOM_EXT, then a SamplerCustomBorderColorCreateInfoEXT must be included in the pNext chain
• If the customBorderColors feature is not enabled, borderColor must not be BORDER_COLOR_FLOAT_CUSTOM_EXT or BORDER_COLOR_INT_CUSTOM_EXT
• If borderColor is one of BORDER_COLOR_FLOAT_CUSTOM_EXT or BORDER_COLOR_INT_CUSTOM_EXT, and SamplerCustomBorderColorCreateInfoEXT::format is not FORMAT_UNDEFINED, SamplerCustomBorderColorCreateInfoEXT::customBorderColor must be within the range of values representable in format
• The maximum number of samplers with custom border colors which can be simultaneously created on a device is implementation-dependent and specified by the maxCustomBorderColorSamplers member of the PhysicalDeviceCustomBorderColorPropertiesEXT structure
• If flags includes SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the descriptorBufferCaptureReplay feature must be enabled
• If the pNext chain includes a OpaqueCaptureDescriptorDataCreateInfoEXT structure, flags must contain SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT
• If flags includes SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then minFilter and magFilter must be FILTER_NEAREST
• If flags includes SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then mipmapMode must be SAMPLER_MIPMAP_MODE_NEAREST
• [If flags includes SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then minLod and maxLod must be zero
• If flags includes SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then addressModeU and addressModeV must each be either SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER
• If flags includes SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, and if addressModeU or addressModeV is SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, then borderColor must be BORDER_COLOR_FLOAT_TRANSPARENT_BLACK
• If flags includes SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then anisotropyEnable must be FALSE
• If flags includes SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then compareEnable must be FALSE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SAMPLER_CREATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of DebugUtilsObjectNameInfoEXT, OpaqueCaptureDescriptorDataCreateInfoEXT, SamplerBlockMatchWindowCreateInfoQCOM, SamplerBorderColorComponentMappingCreateInfoEXT, SamplerCubicWeightsCreateInfoQCOM, SamplerCustomBorderColorCreateInfoEXT, SamplerCustomBorderColorIndexCreateInfoEXT, SamplerReductionModeCreateInfo, or SamplerYcbcrConversionInfo
• The sType value of each structure in the pNext chain must be unique
• flags must be a valid combination of SamplerCreateFlagBits values
• magFilter must be a valid Filter value
• minFilter must be a valid Filter value
• mipmapMode must be a valid SamplerMipmapMode value
• addressModeU must be a valid SamplerAddressMode value
• addressModeV must be a valid SamplerAddressMode value
• addressModeW must be a valid SamplerAddressMode value

See Also

VK_VERSION_1_0, Bool32, BorderColor, CompareOp, DescriptorMappingSourceConstantOffsetEXT, DescriptorMappingSourceIndirectIndexArrayEXT, DescriptorMappingSourceIndirectIndexEXT, DescriptorMappingSourcePushIndexEXT, DescriptorMappingSourceShaderRecordIndexEXT, Filter, SamplerAddressMode, SamplerCreateFlags, SamplerMipmapMode, StructureType, createSampler, writeSamplerDescriptorsEXT

VkSampler - Opaque handle to a sampler object

See Also

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_VERSION_1_0, DescriptorDataEXT, DescriptorImageInfo, DescriptorSetLayoutBinding, ImageViewHandleInfoNVX, SamplerCaptureDescriptorDataInfoEXT, createSampler, destroySampler

VkBorderColor - Specify border color used for texture lookups

Description

• BORDER_COLOR_FLOAT_TRANSPARENT_BLACK specifies a transparent, floating-point format, black color.

• BORDER_COLOR_INT_TRANSPARENT_BLACK specifies a transparent, integer format, black color.
• BORDER_COLOR_FLOAT_OPAQUE_BLACK specifies an opaque, floating-point format, black color.
• BORDER_COLOR_INT_OPAQUE_BLACK specifies an opaque, integer format, black color.
• BORDER_COLOR_FLOAT_OPAQUE_WHITE specifies an opaque, floating-point format, white color.
• BORDER_COLOR_INT_OPAQUE_WHITE specifies an opaque, integer format, white color.
• BORDER_COLOR_FLOAT_CUSTOM_EXT specifies that a SamplerCustomBorderColorCreateInfoEXT structure is included in the SamplerCreateInfo::pNext chain containing the color data in floating-point format.
• BORDER_COLOR_INT_CUSTOM_EXT specifies that a SamplerCustomBorderColorCreateInfoEXT structure is included in the SamplerCreateInfo::pNext chain containing the color data in integer format.

These colors are described in detail in Border Replacement.

See Also

VK_VERSION_1_0, SamplerCreateInfo

VkFilter - Specify filters used for texture lookups

Description

• FILTER_NEAREST specifies nearest filtering.

• FILTER_LINEAR specifies linear filtering.
• FILTER_CUBIC_EXT specifies cubic filtering.

These filters are described in detail in Texel Filtering.

See Also

VK_VERSION_1_0, BlitImageInfo2, SamplerCreateInfo, SamplerYcbcrConversionCreateInfo, cmdBlitImage

VkSamplerMipmapMode - Specify mipmap mode used for texture lookups

Description

• SAMPLER_MIPMAP_MODE_NEAREST specifies nearest filtering.

• SAMPLER_MIPMAP_MODE_LINEAR specifies linear filtering.

These modes are described in detail in Texel Filtering.

See Also

VK_VERSION_1_0, SamplerCreateInfo

VkSamplerAddressMode - Specify behavior of sampling with texture coordinates outside an image

Description

• SAMPLER_ADDRESS_MODE_REPEAT specifies that the repeat wrap mode will be used.

• SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT specifies that the mirrored repeat wrap mode will be used.
• SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE specifies that the clamp to edge wrap mode will be used.
• SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER specifies that the clamp to border wrap mode will be used.
• SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE specifies that the mirror clamp to edge wrap mode will be used. This is only valid if the samplerMirrorClampToEdge feature is enabled, or if the VK_KHR_sampler_mirror_clamp_to_edge extension is enabled.

See Also

VK_VERSION_1_0, SamplerCreateInfo

VkSamplerCreateFlagBits - Bitmask specifying additional parameters of sampler

Description

• SAMPLER_CREATE_SUBSAMPLED_BIT_EXT specifies that the sampler will read from an image created with flags containing IMAGE_CREATE_SUBSAMPLED_BIT_EXT.

• SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT specifies that the implementation may use approximations when reconstructing a full color value for texture access from a subsampled image.
• SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT specifies that cube map edge handling is not performed.
• SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM specifies that the sampler will read from images using only OpImageSampleWeightedQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchGatherSSDQCOM, OpImageBlockMatchGatherSADQCOM, OpImageBlockMatchWindowSSDQCOM, OpImageBlockMatchWindowSADQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM.

The approximations used when SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT is specified are implementation defined. Some implementations may interpolate between fragment density levels in a subsampled image. In that case, this bit may be used to decide whether the interpolation factors are calculated per fragment or at a coarser granularity.

• SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT specifies that the sampler can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see OpaqueCaptureDescriptorDataCreateInfoEXT for more detail.

See Also

VK_VERSION_1_0, SamplerCreateFlags