Vulkan-Docs/doc/specs/vulkan/man/VkSamplerCreateInfo.txt

// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

VkSamplerCreateInfo(3)
======================

Name
----
VkSamplerCreateInfo - Structure specifying parameters of a newly created sampler

C Specification
---------------

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

The sname:VkSamplerCreateInfo structure is defined as:

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


Members
-------

  * 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::../api/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::../api/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::../api/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.


Description
-----------

[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::../api/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[]


See Also
--------

basetype:VkBool32, elink:VkBorderColor, elink:VkCompareOp, elink:VkFilter, elink:VkSamplerAddressMode, elink:VkSamplerCreateFlags, elink:VkSamplerMipmapMode, elink:VkStructureType, flink:vkCreateSampler


Document Notes
--------------

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkSamplerCreateInfo

This page is extracted from the Vulkan Specification.
Fixes and changes should be made to the Specification,not directly.

include::footer.txt[]