status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/chapters/samplers.txt

377 lines
16 KiB
Plaintext
Raw Blame History

// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
[[samplers]]
= Samplers
[open,refpage='VkSampler',desc='Opaque handle to a sampler object',type='handles']
--
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[]
--
[open,refpage='vkCreateSampler',desc='Create a new sampler object',type='protos']
--
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[]
--
[open,refpage='VkSamplerCreateInfo',desc='Structure specifying parameters of a newly created sampler',type='structs']
--
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[]
ifdef::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[]
* [[VUID-VkSamplerCreateInfo-magFilter-01422]]
If either pname:magFilter or pname:minFilter is
ename:VK_FILTER_CUBIC_IMG, the pname:reductionMode member of
slink:VkSamplerReductionModeCreateInfoEXT must: be
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT
endif::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[]
ifdef::VK_EXT_sampler_filter_minmax[]
* [[VUID-VkSamplerCreateInfo-compareEnable-01423]]
If pname:compareEnable is ename:VK_TRUE, the pname:reductionMode member
of slink:VkSamplerReductionModeCreateInfoEXT must: be
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT
endif::VK_EXT_sampler_filter_minmax[]
****
include::../validity/structs/VkSamplerCreateInfo.txt[]
--
ifdef::VK_EXT_sampler_filter_minmax[]
[open,refpage='VkSamplerReductionModeCreateInfoEXT',desc='Structure specifying sampler reduction mode',type='structs']
--
If the pname:pNext list of slink:VkSamplerCreateInfo includes a
sname:VkSamplerReductionModeCreateInfoEXT structure, then that structure
includes a mode that controls how texture filtering combines texel values.
The sname:VkSamplerReductionModeCreateInfoEXT structure is defined as:
include::../api/structs/VkSamplerReductionModeCreateInfoEXT.txt[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:reductionMode is an enum of type elink:VkSamplerReductionModeEXT
that controls how texture filtering combines texel values.
If this structure is not present, pname:reductionMode is considered to be
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT.
include::../validity/structs/VkSamplerReductionModeCreateInfoEXT.txt[]
--
[open,refpage='VkSamplerReductionModeEXT',desc='Specify reduction mode for texture filtering',type='enums']
--
Reduction modes are specified by elink:VkSamplerReductionModeEXT, which
takes values:
include::../api/enums/VkSamplerReductionModeEXT.txt[]
* ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT indicates that
texel values are combined by computing a weighted average of values in
the footprint, using weights as specified in
<<textures-unnormalized-to-integer,the image operations chapter>>.
* ename:VK_SAMPLER_REDUCTION_MODE_MIN_EXT indicates that texel values are
combined by taking the component-wise minimum of values in the footprint
with non-zero weights.
* ename:VK_SAMPLER_REDUCTION_MODE_MAX_EXT indicates that texel values are
combined by taking the component-wise maximum of values in the footprint
with non-zero weights.
--
endif::VK_EXT_sampler_filter_minmax[]
[open,refpage='VkFilter',desc='Specify filters used for texture lookups',type='enums']
--
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>>.
--
[open,refpage='VkSamplerMipmapMode',desc='Specify mipmap mode used for texture lookups',type='enums']
--
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>>.
--
[open,refpage='VkSamplerAddressMode',desc='Specify behavior of sampling with texture coordinates outside an image',type='enums']
--
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.
--
[open,refpage='VkBorderColor',desc='Specify border color used for texture lookups',type='enums']
--
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>>.
--
[open,refpage='vkDestroySampler',desc='Destroy a sampler object',type='protos']
--
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[]
--
Reference in New Issue View Git Blame Copy Permalink