vkCreateSampler - Create a new sampler object

Parameters

• device is the logical device that creates the sampler.

• pCreateInfo is a pointer to a SamplerCreateInfo structure specifying the state of the sampler object.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pSampler is a pointer to a Sampler handle in which the resulting sampler object is returned.

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_TOO_MANY_OBJECTS

See Also

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 first argument. To just extract the pair pass (,) as the first argument.

vkDestroySampler - Destroy a sampler object

Parameters

• device is the logical device that destroys the sampler.

• sampler is the sampler to destroy.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

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

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. If maxSamplerAllocationCount is exceeded, createSampler will return ERROR_TOO_MANY_OBJECTS.

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

• maxLod must be greater than or equal to minLod
• If the anisotropic sampling 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 sampler Y′CBCR conversion’s features 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
• The sampler reduction mode must be set to SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE if sampler Y′CBCR conversion is enabled
• 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 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 borderColor is set to one of BORDER_COLOR_FLOAT_CUSTOM_EXT or BORDER_COLOR_INT_CUSTOM_EXT, then a SamplerCustomBorderColorCreateInfoEXT must be present in the pNext chain
• 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

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

Bool32, BorderColor, CompareOp, Filter, SamplerAddressMode, SamplerCreateFlags, SamplerMipmapMode, StructureType, createSampler