Vulkan-Docs/doc/specs/vulkan/chapters/samplers.txt

// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[[samplers]]
= Samplers

// refBegin VkSampler - Opaque handle to a sampler object

sname:VkSampler objects represent the state of an image sampler which is
used by the implementation to read image data and apply filtering and other
transformations for the shader.

Samplers are represented by sname:VkSampler handles:

include::../handles/VkSampler.txt[]

// refEnd VkSampler

// refBegin vkCreateSampler Create a new sampler object

To create a sampler object, call:

include::../protos/vkCreateSampler.txt[]

  * pname:device is the logical device that creates the sampler.
  * pname:pCreateInfo is a pointer to an instance of the
    slink:VkSamplerCreateInfo structure specifying the state of the sampler
    object.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pSampler points to a sname:VkSampler handle in which the resulting
    sampler object is returned.

include::../validity/protos/vkCreateSampler.txt[]

// refBegin VkSamplerCreateInfo - Structure specifying parameters of a newly created sampler

The sname:VkSamplerCreateInfo structure is defined as:

include::../structs/VkSamplerCreateInfo.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:flags is reserved for future use.
  * pname:magFilter is the magnification filter to apply to lookups, and
    is of type:
+
--
// refBegin VkFilter - specify filters used for texture lookups
include::../enums/VkFilter.txt[]
--
+
  * pname:minFilter is the minification filter to apply to lookups, and is
    of type elink:VkFilter.
  * pname:mipmapMode is the mipmap filter to apply to lookups as described
    in the <<textures-texel-filtering, Texel Filtering>> section, and is of
    type:
+
--
// refBegin VkSamplerMipmapMode - specify mipmap mode used for texture lookups
include::../enums/VkSamplerMipmapMode.txt[]
--
+
  * pname:addressModeU is the addressing mode for outside [0..1] range for U
    coordinate. See elink:VkSamplerAddressMode.
  * pname:addressModeV is the addressing mode for outside [0..1] range for V
    coordinate. See elink:VkSamplerAddressMode.
  * pname:addressModeW is the addressing mode for outside [0..1] range for W
    coordinate. See elink:VkSamplerAddressMode.
  * [[samplers-mipLodBias]] pname:mipLodBias is the bias to be added to
    mipmap LOD calculation and bias provided by image sampling functions in
    SPIR-V, as described in the <<textures-level-of-detail-operation,
    Level-of-Detail Operation>> section.
  * [[samplers-maxAnisotropy]] pname:anisotropyEnable is ename:VK_TRUE to
    enable anisotropic filtering, as described in the
    <<textures-texel-anisotropic-filtering, Texel Anisotropic Filtering>>
    section, or ename:VK_FALSE otherwise.
  * pname:maxAnisotropy is the anisotropy value clamp.
  * pname:compareEnable is ename:VK_TRUE to enable comparison against a
    reference value during lookups, or ename:VK_FALSE otherwise.
  ** Note: Some implementations will default to shader state if this member
     does not match.
  * pname:compareOp is the comparison function to apply to fetched data
    before filtering as described in the <<textures-depth-compare-operation,
    Depth Compare Operation>> section. See elink:VkCompareOp.
  * pname:minLod and pname:maxLod are the values used to clamp the computed
    level-of-detail value, as described in the
    <<textures-level-of-detail-operation, Level-of-Detail Operation>>
    section. pname:maxLod must: be greater than or equal to pname:minLod.
  * pname:borderColor is the predefined border color to use, as described
    in the <<textures-texel-replacement, Texel Replacement>>
    section, and is of type:
+
--
// refBegin VkBorderColor - specify border color used for texture lookups
include::../enums/VkBorderColor.txt[]
--
+
  * [[samplers-unnormalizedCoordinates]] pname:unnormalizedCoordinates
    controls whether to use unnormalized or normalized texel coordinates to
    address texels of the image. When set to ename:VK_TRUE, the range of the
    image coordinates used to lookup the texel is in the range of zero to
    the image dimensions for x, y and z. When set to ename:VK_FALSE the
    range of image coordinates is zero to one. When
    pname:unnormalizedCoordinates is ename:VK_TRUE, samplers have the
    following requirements:
  ** pname:minFilter and pname:magFilter must: be equal.
  ** pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST.
  ** pname:minLod and pname:maxLod must: be zero.
  ** pname:addressModeU and pname:addressModeV must: each
     be either ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or
     ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER.
  ** pname:anisotropyEnable must: be ename:VK_FALSE.
  ** pname:compareEnable must: be ename:VK_FALSE.
  * When pname:unnormalizedCoordinates is ename:VK_TRUE, images the sampler
    is used with in the shader have the following requirements:
  ** The pname:viewType must: be either ename:VK_IMAGE_VIEW_TYPE_1D or
     ename:VK_IMAGE_VIEW_TYPE_2D.
  ** The image view must: have a single layer and a single mip level.
  * When pname:unnormalizedCoordinates is ename:VK_TRUE, image built-in
    functions in the shader that use the sampler have the following
    requirements:
  ** The functions mustnot: use projection.
  ** The functions mustnot: use offsets.

[NOTE]
.Mapping of OpenGL to Vulkan filter modes
==================
pname:magFilter values of ename:VK_FILTER_NEAREST and ename:VK_FILTER_LINEAR
directly correspond to code:GL_NEAREST and code:GL_LINEAR magnification
filters. pname:minFilter and pname:mipmapMode combine to correspond to the
similarly named OpenGL minification filter of
code:GL_minFilter_MIPMAP_mipmapMode (e.g. pname:minFilter of
ename:VK_FILTER_LINEAR and pname:mipmapMode of
ename:VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to
code:GL_LINEAR_MIPMAP_NEAREST).

There are no Vulkan filter modes that directly correspond to OpenGL
minification filters of code:GL_LINEAR or code:GL_NEAREST, but they can: be
emulated using ename:VK_SAMPLER_MIPMAP_MODE_NEAREST, pname:minLod = 0, and
pname:maxLod = 0.25, and using pname:minFilter = ename:VK_FILTER_LINEAR or
pname:minFilter = ename:VK_FILTER_NEAREST, respectively.

Note that using a pname:maxLod of zero would cause
<<textures-texel-filtering,magnification>> to always be performed, and the
pname: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
latexmath:[$\lambda$] value to be non-zero and minification to be performed,
while still always rounding down to the base level. If the pname:minFilter
and pname:magFilter are equal, then using a pname:maxLod of zero also works.
==================

pname:addressModeU, pname:addressModeV, and pname:addressModeW must: each
have one of the following values:

// refBegin VkSamplerAddressMode - specify behavior of sampling with texture coordinates outside an image
include::../enums/VkSamplerAddressMode.txt[]

These values control the behavior of sampling with coordinates outside the
range latexmath:[$[0,1\]$] for the respective u, v, or w coordinate as defined in the
<<textures-wrapping-operation, Wrapping Operation>> section.

  * ename:VK_SAMPLER_ADDRESS_MODE_REPEAT indicates that the repeat wrap mode
    will be used.
  * ename:VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT indicates that the
    mirrored repeat wrap mode will be used.
  * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE indicates that the clamp to
    edge wrap mode will be used.
  * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER indicates that the clamp
    to border wrap mode will be used.
  * ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE indicates that
    the mirror clamp to edge wrap mode will be used. This is only valid
    if the VK_KHR_mirror_clamp_to_edge extension is enabled.

The maximum number of sampler objects which can: be simultaneously created
on a device is implementation-dependent and specified by the
<<features-limits-maxSamplerAllocationCount,pname:maxSamplerAllocationCount>>
member of the sname:VkPhysicalDeviceLimits structure. If
pname:maxSamplerAllocationCount is exceeded, fname:vkCreateSampler will
return ename:VK_ERROR_TOO_MANY_OBJECTS.

Since sname:VkSampler 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
pname:maxSamplerAllocationCount limit.

include::../validity/structs/VkSamplerCreateInfo.txt[]

// refBegin vkDestroySampler Destroy a sampler object

To destroy a sampler, call:

include::../protos/vkDestroySampler.txt[]

  * pname:device is the logical device that destroys the sampler.
  * pname:sampler is the sampler to destroy.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.

include::../validity/protos/vkDestroySampler.txt[]