vkCreateSampler - Create a new sampler object

Valid Usage

• There must be less than PhysicalDeviceLimits::maxSamplerAllocationCount 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_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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.

Note

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.

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 set to SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
• If samplerFilterMinmax is not enabled and the pNext chain includes a SamplerReductionModeCreateInfo structure, then the sampler reduction mode must be set to SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
• If samplerMirrorClampToEdge 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_EXT, 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 OpaqueCaptureDescriptorDataCreateInfoEXT, SamplerBlockMatchWindowCreateInfoQCOM, SamplerBorderColorComponentMappingCreateInfoEXT, SamplerCubicWeightsCreateInfoQCOM, SamplerCustomBorderColorCreateInfoEXT, SamplerReductionModeCreateInfo, or SamplerYcbcrConversionInfo
• The sType value of each struct 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, Filter, SamplerAddressMode, SamplerCreateFlags, SamplerMipmapMode, StructureType, createSampler

VkSampler - Opaque handle to a sampler object

See Also

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

VkBorderColor - Specify border color used for texture lookups

Description

These colors are described in detail in Texel Replacement.

See Also

VK_VERSION_1_0, SamplerCreateInfo

VkFilter - Specify filters used for texture lookups

Description

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

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

See Also

VK_VERSION_1_0, SamplerCreateInfo

VkSamplerCreateFlagBits - Bitmask specifying additional parameters of sampler

Description

Note

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.

See Also

VK_VERSION_1_0, SamplerCreateFlags