mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-22 12:19:27 +00:00
75bbb5f4d5
* Bump API patch number and header version number to 12 for this
update.
Github Issues:
* Change valid usage statements intended to be "sub-points" to
be actual sub-points (public issue 66).
* Replace double negation in description of
slink:VkRenderPassBeginInfo::pname:pClearValues (based on public
merge 142).
* Cleanup minor typos in spec, ref pages and XML, including those
proposed in public pull requests 144, 150, 151, 167, 168, 181, and
186.
* Use *strict subset* in describing the partial order of memory
property types for slink:VkMemoryType, and update the style guide
accordingly (public issue 190).
* Fix various "a image" -> "an image" typos (public issue 191).
* Note in the <<fundamentals-validusage,Valid Usage>> and
<<extensions-interactions,Extension Interactions>> sections that
structures defined by extensions which may be passed in structure
chains using the ptext:pNext member must: include initial
ptext:sType and ptext:pNext members (public issue 192).
Internal Issues:
* Remove duplicate language from the description of the pname:fence
parameter to flink:vkQueueSubmit and improve validity language
(internal issue 91).
* Added documentation for "optional" attribute to XML readme.tex/pdf
(internal issue 149).
* Clarify the host-side data validity rules and behavior of
flink:vkFlushMappedMemoryRanges and
flink:vkInvalidateMappedMemoryRanges (internal issue 266).
Other Commits:
* Added clarification to flink:vkCmdFillBuffer regarding the use of
ename:VK_WHOLE_SIZE.
* Fixed and documented implementation of "validextensionstructs"
attribute. in XML processing scripts and readme.tex/pdf.
* Add missing validity statements to flink:vkResetEvent and
flink:vkCmdResetEvent.
* Fix validity for the
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag.
Correct all the draw/dispatch commands to mention optimally tiled
images as well as linear tiled images, and say image VIEWS instead
of images. Add validity statement to flink:vkCmdBlitImage
* Replace the {apiname} macro with hardcoded "Vulkan", now that we've
committed to that name.
* Add the VK_AMD_rasterization_order extension to vk.xml.
183 lines
8.3 KiB
Plaintext
183 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:
|
|
|
|
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:
|
|
+
|
|
--
|
|
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 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.
|
|
==================
|
|
|
|
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[]
|