mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-17 08:46:32 +00:00
1d67e47f14
* Bump API patch number and header version number to 51 for this update.
Github Issues:
* Add Valid Usage statement to flink:vkCmdResolveImage to require that
source and destination image formats match (public issue 492).
* Specify that a code:char* parameter must: be a valid null-terminated
string in the <<fundamentals-implicit-validity, implicit valid usage>>
section (public issue 494).
* Removed unnecessary VU for slink:VkPhysicalDeviceFeatures which is
covered by ename:VK_ERROR_FEATURE_NOT_PRESENT already (public issue
496).
* Clarify valid usage of pname:pQueueFamilyIndices in
slink:VkBufferCreateInfo, slink:VkImageCreateInfo, and
slink:VkSwapchainCreateInfoKHR (public issue 501).
* Document that dependencies of enabled extensions must also be enabled in
the <<extended-functionality-extensions-dependencies, Extension
Dependencies>> section (public issue 507).
Internal Issues:
* Change slink:VkMappedMemoryRange valid usage to allow pname:offset +
pname:size == size of the allocation. Also, if ename:VK_WHOLE_SIZE is
used, require the end of the mapping to be aligned to a multiple of
pname:nonCoherentAtomSize (internal issue 611).
* Add issue to `VK_KHR_win32_surface` about reusing window objects from a
different graphics API or Vulkan ICD (internal issue 639).
* Require locations on user in/out in `GL_KHR_vulkan_glsl` (internal issue
783).
* Added version info to the json validation output, and updated the schema
to match (internal issue 838).
* Restructure enumerated type descriptions separately from the command or
structure they are used in, allowing better reference page generation
(internal issue 841).
* Re-sort extension appendices to be in alphabetical order within each
author ID section.
* Fix enum naming and clarify behavior for
`VK_NVX_device_generated_commands` extension.
New Extensions:
309 lines
14 KiB
Plaintext
309 lines
14 KiB
Plaintext
// Copyright (c) 2015-2017 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::../api/handles/VkSampler.txt[]
|
|
|
|
// refEnd VkSampler
|
|
|
|
// refBegin vkCreateSampler Create a new sampler object
|
|
|
|
To create a sampler object, call:
|
|
|
|
include::../api/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 slink: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::../api/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 a elink:VkFilter value specifying the magnification
|
|
filter to apply to lookups.
|
|
* pname:minFilter is a elink:VkFilter value specifying the minification
|
|
filter to apply to lookups.
|
|
* pname:mipmapMode is a elink:VkSamplerMipmapMode value specifying the
|
|
mipmap filter to apply to lookups.
|
|
* pname:addressModeU is a elink:VkSamplerAddressMode value specifying the
|
|
addressing mode for outside [0..1] range for U coordinate.
|
|
* pname:addressModeV is a elink:VkSamplerAddressMode value specifying the
|
|
addressing mode for outside [0..1] range for V coordinate.
|
|
* pname:addressModeW is a elink:VkSamplerAddressMode value specifying the
|
|
addressing mode for outside [0..1] range for W coordinate.
|
|
* [[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 a elink:VkCompareOp value specifying the comparison
|
|
function to apply to fetched data before filtering as described in the
|
|
<<textures-depth-compare-operation, Depth Compare Operation>> section.
|
|
* 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 a elink:VkBorderColor value specifying the
|
|
predefined border color to use.
|
|
* [[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 must: not use projection.
|
|
** The functions must: not 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 [eq]#{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.
|
|
==================
|
|
|
|
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 slink:VkPhysicalDeviceLimits structure.
|
|
If pname:maxSamplerAllocationCount is exceeded, fname:vkCreateSampler will
|
|
return ename:VK_ERROR_TOO_MANY_OBJECTS.
|
|
|
|
Since slink: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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkSamplerCreateInfo-mipLodBias-01069]]
|
|
The absolute value of pname:mipLodBias must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxSamplerLodBias
|
|
* [[VUID-VkSamplerCreateInfo-anisotropyEnable-01070]]
|
|
If the <<features-features-samplerAnisotropy,anisotropic sampling>>
|
|
feature is not enabled, pname:anisotropyEnable must: be ename:VK_FALSE
|
|
* [[VUID-VkSamplerCreateInfo-anisotropyEnable-01071]]
|
|
If pname:anisotropyEnable is ename:VK_TRUE, pname:maxAnisotropy must: be
|
|
between `1.0` and
|
|
sname:VkPhysicalDeviceLimits::pname:maxSamplerAnisotropy, inclusive
|
|
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072]]
|
|
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minFilter and
|
|
pname:magFilter must: be equal
|
|
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01073]]
|
|
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:mipmapMode
|
|
must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST
|
|
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01074]]
|
|
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:minLod and
|
|
pname:maxLod must: be zero
|
|
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01075]]
|
|
If pname:unnormalizedCoordinates is ename:VK_TRUE, 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
|
|
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01076]]
|
|
If pname:unnormalizedCoordinates is ename:VK_TRUE,
|
|
pname:anisotropyEnable must: be ename:VK_FALSE
|
|
* [[VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01077]]
|
|
If pname:unnormalizedCoordinates is ename:VK_TRUE, pname:compareEnable
|
|
must: be ename:VK_FALSE
|
|
* [[VUID-VkSamplerCreateInfo-addressModeU-01078]]
|
|
If any of pname:addressModeU, pname:addressModeV or pname:addressModeW
|
|
are ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, pname:borderColor
|
|
must: be a valid elink:VkBorderColor value
|
|
* [[VUID-VkSamplerCreateInfo-addressModeU-01079]]
|
|
If the +VK_KHR_sampler_mirror_clamp_to_edge+ extension is not enabled,
|
|
pname:addressModeU, pname:addressModeV and pname:addressModeW must: not
|
|
be ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
|
|
* [[VUID-VkSamplerCreateInfo-compareEnable-01080]]
|
|
If pname:compareEnable is ename:VK_TRUE, pname:compareOp must: be a
|
|
valid elink:VkCompareOp value
|
|
ifdef::VK_IMG_filter_cubic[]
|
|
* [[VUID-VkSamplerCreateInfo-magFilter-01081]]
|
|
If either pname:magFilter or pname:minFilter is
|
|
ename:VK_FILTER_CUBIC_IMG, pname:anisotropyEnable must: be
|
|
ename:VK_FALSE
|
|
endif::VK_IMG_filter_cubic[]
|
|
****
|
|
|
|
include::../validity/structs/VkSamplerCreateInfo.txt[]
|
|
|
|
// refBegin VkFilter Specify filters used for texture lookups
|
|
|
|
Possible values of the slink:VkSamplerCreateInfo::pname:magFilter and
|
|
pname:minFilter parameters, specifying filters used for texture lookups,
|
|
are:
|
|
|
|
include::../api/enums/VkFilter.txt[]
|
|
|
|
* ename:VK_FILTER_NEAREST specifies nearest filtering.
|
|
* ename:VK_FILTER_LINEAR specifies linear filtering.
|
|
|
|
These filters are described in detail in <<textures-texel-filtering, Texel
|
|
Filtering>>.
|
|
|
|
// refEnd VkFilter
|
|
|
|
// refBegin VkSamplerMipmapMode Specify mipmap mode used for texture lookups
|
|
|
|
Possible values of the slink:VkSamplerCreateInfo::pname:mipmapMode,
|
|
specifying the mipmap mode used for texture lookups, are:
|
|
|
|
include::../api/enums/VkSamplerMipmapMode.txt[]
|
|
|
|
* ename:VK_SAMPLER_MIPMAP_MODE_NEAREST specifies nearest filtering.
|
|
* ename:VK_SAMPLER_MIPMAP_MODE_LINEAR specifies linear filtering.
|
|
|
|
These modes are described in detail in <<textures-texel-filtering, Texel
|
|
Filtering>>.
|
|
|
|
// refEnd VkSamplerMipmapMode
|
|
|
|
// refBegin VkSamplerAddressMode Specify behavior of sampling with texture coordinates outside an image
|
|
|
|
Possible values of the slink:VkSamplerCreateInfo::ptext:addressMode*
|
|
parameters, specifying the behavior of sampling with coordinates outside the
|
|
range [eq]#[0,1]# for the respective [eq]#u#, [eq]#v#, or [eq]#w# coordinate
|
|
as defined in the <<textures-wrapping-operation, Wrapping Operation>>
|
|
section, are:
|
|
|
|
include::../api/enums/VkSamplerAddressMode.txt[]
|
|
|
|
* ename:VK_SAMPLER_ADDRESS_MODE_REPEAT specifies that the repeat wrap mode
|
|
will be used.
|
|
* ename:VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT specifies that the
|
|
mirrored repeat wrap mode will be used.
|
|
* ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE specifies that the clamp to
|
|
edge wrap mode will be used.
|
|
* ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER specifies that the clamp
|
|
to border wrap mode will be used.
|
|
* ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE specifies 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.
|
|
|
|
// refEnd VkSamplerAddressMode
|
|
|
|
// refBegin VkBorderColor Specify border color used for texture lookups
|
|
|
|
Possible values of slink:VkSamplerCreateInfo::pname:borderColor, specifying
|
|
the border color used for texture lookups, are:
|
|
|
|
include::../api/enums/VkBorderColor.txt[]
|
|
|
|
* ename:VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK specifies a transparent,
|
|
floating-point format, black color.
|
|
* ename:VK_BORDER_COLOR_INT_TRANSPARENT_BLACK specifies a transparent,
|
|
integer format, black color.
|
|
* ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK specifies an opaque,
|
|
floating-point format, black color.
|
|
* ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK specifies an opaque, integer
|
|
format, black color.
|
|
* ename:VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE specifies an opaque,
|
|
floating-point format, white color.
|
|
* ename:VK_BORDER_COLOR_INT_OPAQUE_WHITE specifies an opaque, integer
|
|
format, white color.
|
|
|
|
These colors are described in detail in <<textures-texel-replacement, Texel
|
|
Replacement>>.
|
|
|
|
// refEnd VkBorderColor
|
|
|
|
// refBegin vkDestroySampler Destroy a sampler object
|
|
|
|
To destroy a sampler, call:
|
|
|
|
include::../api/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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkDestroySampler-sampler-01082]]
|
|
All submitted commands that refer to pname:sampler must: have completed
|
|
execution
|
|
* [[VUID-vkDestroySampler-sampler-01083]]
|
|
If sname:VkAllocationCallbacks were provided when pname:sampler was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroySampler-sampler-01084]]
|
|
If no sname:VkAllocationCallbacks were provided when pname:sampler was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroySampler.txt[]
|