mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 06:54:14 +00:00
5a4c5e5925
* Bump API patch number from 3 to 4 for the first public update to the
spec. Add patch number to the spec title (this will be done
automatically from XML, later).
* Fixes for numerous editorial issues. Regularize descriptions of
variable-length array queries. Properly tag enumerants so they come
out in the right font (many were mislabeled in usage tags in vk.xml,
or not tagged). Spelling and markup corrections (public issue 4).
* Fix typos and clearly separate description of different types of
memory areas (public issue 5).
* Use standards-compliant preprocessor guard symbols on headers
(public issue 7).
* Note that Github users can't currently set labels on issues, and
recommend a fallback approach (public issue 15).
* Use latexmath prefix on len= attributes (public issue 29).
* Make flink:vkCmdUpdateBuffer pname:dataSize limit consistent (public
issue 65).
* Add VK_KHR_mirror_clamp_to_edge extension to core API branch, as an
optional feature not introducing new commands or enums (internal
issue 104).
* Cleanup invariance language inherited from the GL specification to
not refer to nonexistent (GL-specific) state (internal issue 111).
* Modify the flink:vkCmdDrawIndexed pname:vertexOffset definition to
not be the "base offset within the index buffer" but rather the
"value added to the vertex index before indexing into the vertex
buffer" (internal issue 118).
* Fix drawing chapter in the "Programmable Primitive Shading" section
where it described categories of drawing commands. It referenced
flink:vkCmdDrawIndexed twice. Replace the second reference with
flink:vkCmdDrawIndexedIndirect (internal issue 119).
* Typo fixed in <<sparsememory-examples-advanced,Advanced Sparse
Resources>> sparse memory example (internal issue 122).
* Add flink:VkDisplayPlaneAlphaFlagsKHR to <require> section of
VK_KHR_display extension (internal issue 125)
* Add missing optional="false,true" to
flink:vkGetImageSparseMemoryRequirements
pname:pSparseMemoryRequirementCount parameter (internal issue 132)
* Rename ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT to
ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT
(internal issue 133)
* Fix a handful of broken cross-references in the
<<samplers,Samplers>> chapter (internal issue 134).
* Fix "Input Attachement" GLSL example to use correct syntax (internal
issue 135).
* Update XML schema and documentation to accomodate recently added
attributes for validity. Add some introductory material describing
design choices and pointing to the public repository to file issues.
* Put include of validity in the core spec extensions chapter on its
own line, so that asciidoc is happy.
* Fix vertexOffset language to specify that it's the value added to
the vertex index before indexing into the vertex buffer, not the
base offset within the index buffer.
* Fix error in the description of flink:vkCmdNextSubpass.
185 lines
8.3 KiB
Plaintext
185 lines
8.3 KiB
Plaintext
// Copyright (c) 2015-2016 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[samplers]]
|
|
= Samplers
|
|
|
|
sname:VkSampler objects encapsulate 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.
|
|
|
|
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[]
|
|
|
|
The sname:VkSamplerCreateInfo structure is defined as follows:
|
|
|
|
include::../structs/VkSamplerCreateInfo.txt[]
|
|
|
|
The members of sname:VkSamplerCreateInfo are described as follows:
|
|
|
|
* 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:
|
|
+
|
|
--
|
|
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:
|
|
+
|
|
--
|
|
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:
|
|
+
|
|
--
|
|
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 {apiname} 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 {apiname} 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.
|
|
==================
|
|
|
|
include::../validity/structs/VkSamplerCreateInfo.txt[]
|
|
|
|
pname:addressModeU, pname:addressModeV, and pname:addressModeW must: each
|
|
have one of the following values:
|
|
|
|
include::../enums/VkSamplerAddressMode.txt[]
|
|
|
|
These values control the behavior of sampling with coordinates outside the
|
|
range [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.
|
|
|
|
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[]
|