status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-22 02:58:16 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/chapters/samplers.txt
Jon Leech ce60b9c887 Change log for March 7, 2018 Vulkan 1.1.70 spec update: 
* Vulkan 1.1 initial release. Bump API patch number and header version
    number to 70 for this update. The patch number will be used for both
    Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment
    continuously from the previous Vulkan 1.0.69 update.

    NOTE: We are not publishing an updated 1.0.70 specification, or 1.1
    reference pages, along with 1.1.70. There are still minor issues to work
    out with those build targets. However, we will soon generate all three
    types of documents as part of the regular spec update cycle.

    NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the
    current specification in the `master` branch. The `1.0` branch is out of
    date and will not be maintained, since we will be generating both 1.1
    and 1.0 specifications from the `master` branch in the future.

Github Issues:

  * Clarify how mapped memory ranges are flushed in
    flink:vkFlushMappedMemoryRanges (public issue 127).
  * Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a
    list of tasks that each command performs, rather than necessarily being
    discrete pieces of hardware that one task flows through. Add a
    "`synchronization command`" pipeline type which all synchronization
    command execute (it's just TOP + BOTTOM), with an explanatory note
    (public issue 554).

Internal Issues:

  * Regenerate all images used in the spec in Inkscape with a consistent
    look-and-feel, and adjust image size attributes so they're all legible,
    and not too large with respect to the spec body text (internal issue
    701).
  * Document in the <<extensions,extensions>> appendix and in the style
    guide that `KHX` extensions are no longer supported or used in the
    Vulkan 1.1 timeframe (internal issue 714).
  * Remove the leftover equations_temp directory after PDF build completes
    (internal issue 925).
  * Update the <<credits, Credits (Informative)>> appendix to include
    contributors to Vulkan 1.1, and to list them according to the API
    version(s) they contributed to (internal issue 987).
  * Add a NOTE to the introduction explaining that interfaces defined by
    extensions which were promoted to Vulkan 1.1 are now expressed as
    aliases of the Vulkan 1.1 type (internal issue 991).
  * Instrument spec source conditionals so spec can be built with 1.1
    features, extensions promoted to 1.1, or both (internal issues 992,
    998).
  * Modify the XML schema and tools to support explicit aliasing of types,
    structures, and commands, and use this to express the promotion of 1.0
    extensions to 1.1 core features, by making the extension interfaces
    aliases of the core features they were promoted to. Mark up promoted
    interfaces to allow still generating 1.0 + extension specifications
    (internal issue 991).
  * Platform names, along with corresponding preprocessor symbols to enable
    extensions specific to those platforms, are now reserved in vk.xml using
    the <platform> tag. Update the registry schema and schema specification
    to match (internal issue 1011).
  * Updated the <<textures-texel-replacement, Texel Replacement>> section to
    clarify that reads from invalid texels for image resources result in
    undefined values (internal issue 1014).
  * Modify description of patch version so it continues to increment across
    minor version changes (internal issue 1033).
  * Clarify and unify language describing physical device-level core and
    extension functionality in the <<fundamentals-validusage-extensions,
    Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid
    Usage for Newer Core Versions>>, <<initialization-functionpointers
    Command Function Pointers>>, <<initialization-phys-dev-extensions,
    Extending Physical Device From Device Extensions>>
    <<extended-functionality-instance-extensions-and-devices, Instance
    Extensions and Device Extensions>> sections and for
    flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that
    instance-level functionality is tied to the loader, and independent of
    the ICD; physical device-level functionality is tied to the ICD, and
    associated with device extensions; physical devices are treated more
    uniformly between core and extensions; and instance and physical
    versions can be different (internal issue 1048).
  * Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>>
    section to clarify the ability for pending command buffers to transition
    to the invalid state after submission, and add a command buffer
    lifecycle diagram (internal issue 1050).
  * Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters
    are ignored when push descriptors are not supported (internal issue
    1054).
  * Specify that flink:vkCreateImage will return an error if the image is
    too large, in a NOTE in the slink:VkImageFormatProperties description
    (internal issue 1078).
  * Remove near-duplicate NOTEs about when to query function pointers
    dynamically in the <<initialization, Initialization>> chapter and
    replace by extending the NOTE in the <<fundamentals-abi, Application
    Binary Interface>> section (internal issue 1085).
  * Restore missing references to "`Sparse Resource Features`" in the
    flink:VkBufferCreateFlagBits description (internal issue 1086).
  * Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl`
    specification, the <<descriptorsets, Resource Descriptors>> section and
    its subsections, and the <<interfaces-resources-descset, Descriptor Set
    Interface>> for consistency, reduction of duplicate information, and
    removal of GLSL correspondance/examples (internal issue 1090).
  * Correctly describe code:PrimitiveId as an Input for tessellation control
    and evaluation shaders, not an Output (internal issue 1109).
  * Relax the requirements on chroma offsets for nearest filtering in
    <<textures-implict-reconstruction, Implicit Reconstruction>> (internal
    issue 1116).

Other Issues:

  * Clarify the intended relationship between specification language and
    certain terms defined in the Khronos Intellectual Property Rights
    policy. Specific changes include:
  ** Rewrote IP/Copyright preamble and introduction to better agree with
     normative language both as laid out in the introduction, and the
     Khronos IPR policy.
  ** Added notion of fully informative sections, which are now tagged with
     "`(Informative)`" in their titles.
  ** Removed non-normative uses of the phrase "`not required`"
  ** Clarified the distinction between terms "`optional`" and "`not
     required:`" as they relate to the IPR Policy, and updated specification
     text to use terms consistent with the intent.
  ** Reduced additions to RFC 2119, and ensured the specification agreed
     with the leaner language.
  ** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from
     normative text.
  ** Moved several paragraphs that should not have been normative to
     informative notes.
  ** Clarified a number of definitions in the Glossary.
  ** Updated the document writing guide to match new terminology changes.
  * Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire,
    application memory lifetime>> language that that for objects other than
    descriptor sets, a slink:VkDescriptorSetLayout object used in the
    creation of another object (such as slink:VkPipelineLayout or
    slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation
    of that object and can be safely destroyed afterwards.
  * Updated the <<textures-scale-factor, Scale Factor Operation>> section to
    use the ratio of anisotropy, rather than the integer sample rate, to
    perform the LOD calculation. The spec still allows use of the sample
    rate as the value used to calculate the LOD, but no longer requires it.
  * Update `vulkan_ext.c` to include all platform-related definitions from
    the Vulkan platform headers, following the split of the headers into
    platform-specific and non-platform-specific files.
  * Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter
    which accidentally duplicated an anchor in the pipelines chapter. There
    were no reference to this anchor, fortunately.
  * Add valid usage statement for slink:VkWriteDescriptorSet and
    slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout
    used to allocate the source and destination sets must not have been
    destroyed at the time flink:vkUpdateDescriptorSets is called.
  * Document mapping of subgroup barrier functions to SPIR-V, and clarify a
    place where subgroupBarrier sounds like it's execution-only in the
    standalone `GL_KHR_shader_subgroup` specification.
  * Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with
    the default Arial font family replaced by the sans-serif Noto font
    family.
  * Numerous minor updates to README.adoc, build scripts, Makefiles, and
    registry and style guide specifications to support Vulkan 1.1 outputs,
    use them as defaults, and remove mention of `KHX` extensions, which are
    no longer supported.

New Extensions:

  * `VK_EXT_vertex_attrib_divisor`
2018-03-07 04:18:52 -08:00

767 lines
32 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// Copyright (c) 2015-2018 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 (level-of-detail) 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 used by the sampler
when pname:anisotropyEnable is ename:VK_TRUE.
If pname:anisotropyEnable is ename:VK_FALSE, pname:maxAnisotropy is
ignored.
* 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
LOD 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.
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
** The sampler must: not enable sampler Y'C~B~C~R~ conversion.
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* 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,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
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkSamplerCreateInfo-minFilter-01645]]
If <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is
enabled and
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT
is not set for the format, pname:minFilter and pname:magFilter must: be
equal to the sampler Y'C~B~C~R~ conversion's pname:chromaFilter
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[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
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[VUID-VkSamplerCreateInfo-addressModeU-01646]]
If <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is
enabled, pname:addressModeU, pname:addressModeV, and pname:addressModeW
must: be ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE,
pname:anisotropyEnable must: be ename:VK_FALSE, and
pname:unnormalizedCoordinates must: be ename:VK_FALSE
ifdef::VK_EXT_sampler_filter_minmax[]
* [[VUID-VkSamplerCreateInfo-None-01647]]
The sampler reduction mode must: be set to
ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT if
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> is enabled
endif::VK_EXT_sampler_filter_minmax[]
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
* [[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[]
--
[open,refpage='VkSamplerCreateFlags',desc='Reserved for future use',type='enums']
--
include::../api/flags/VkSamplerCreateFlags.txt[]
sname:VkSamplerCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
--
ifdef::VK_EXT_sampler_filter_minmax[]
[open,refpage='VkSamplerReductionModeCreateInfoEXT',desc='Structure specifying sampler reduction mode',type='structs']
--
If the pname:pNext chain 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.
ifdef::VK_IMG_filter_cubic[]
* ename:VK_FILTER_CUBIC_IMG specifies cubic filtering.
endif::VK_IMG_filter_cubic[]
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_sampler_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[]
--
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
[[samplers-YCbCr-conversion]]
== Sampler Y'C~B~C~R~ conversion
[open,refpage='VkSamplerYcbcrConversionInfo',desc='Structure specifying Y\'CbCr conversion to a sampler or image view',type='structs']
--
To create a sampler with Y'C~B~C~R~ conversion enabled, add a
slink:VkSamplerYcbcrConversionInfo to the pname:pNext chain of the
slink:VkSamplerCreateInfo structure.
To create a sampler Y'C~B~C~R~ conversion, the
<<features-features-sampler-YCbCr-conversion,pname:samplerYcbcrConversion
feature>> must: be enabled.
Conversion must: be fixed at pipeline creation time, through use of a
combined image sampler with an immutable sampler in
sname:VkDescriptorSetLayoutBinding.
A slink:VkSamplerYcbcrConversionInfo must: be provided for samplers to be
used with image views that access ename:VK_IMAGE_ASPECT_COLOR_BIT if the
format appears in <<features-formats-requiring-sampler-ycbcr-conversion>>.
The sname:VkSamplerYcbcrConversionInfo structure is defined as:
include::../api/structs/VkSamplerYcbcrConversionInfo.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/structs/VkSamplerYcbcrConversionInfoKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:conversion is a slink:VkSamplerYcbcrConversion handle created with
flink:vkCreateSamplerYcbcrConversion.
include::../validity/structs/VkSamplerYcbcrConversionInfo.txt[]
--
[open,refpage='VkSamplerYcbcrConversion',desc='',type='handles']
--
A sampler Y'C~B~C~R~ conversion is an opaque representation of a
device-specific sampler Y'C~B~C~R~ conversion description, represented as a
sname:VkSamplerYcbcrConversion handle:
include::../api/handles/VkSamplerYcbcrConversion.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/handles/VkSamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
--
[open,refpage='vkCreateSamplerYcbcrConversion',desc='Create a new Ycbcr conversion',type='protos']
--
To create a slink:VkSamplerYcbcrConversion, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkCreateSamplerYcbcrConversion.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
include::../api/protos/vkCreateSamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* pname:device is the logical device that creates the sampler Y'C~B~C~R~
conversion.
* pname:pCreateInfo is a pointer to an instance of the
slink:VkSamplerYcbcrConversionCreateInfo specifying the requested
sampler Y'C~B~C~R~ conversion.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
* pname:pYcbcrConversion points to a slink:VkSamplerYcbcrConversion handle
in which the resulting sampler Y'C~B~C~R~ conversion is returned.
The interpretation of the configured sampler Y'C~B~C~R~ conversion is
described in more detail in <<textures-sampler-YCbCr-conversion,the
description of sampler Y'C~B~C~R~ conversion>> in the <<textures,Image
Operations>> chapter.
.Valid Usage
****
* [[VUID-vkCreateSamplerYcbcrConversionKHR-None-01648]]
The <<features-features-sampler-YCbCr-conversion, sampler Y'C~B~C~R~
conversion feature>> must: be enabled
****
include::../validity/protos/vkCreateSamplerYcbcrConversion.txt[]
--
[open,refpage='VkSamplerYcbcrConversionCreateInfo',desc='Structure specifying the parameters of the newly created conversion',type='structs']
--
The sname:VkSamplerYcbcrConversionCreateInfo structure is defined as:
include::../api/structs/VkSamplerYcbcrConversionCreateInfo.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/structs/VkSamplerYcbcrConversionCreateInfoKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* pname:sType is the type of this structure.
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
* pname:format is the format of the image from which color information
will be retrieved.
* pname:ycbcrModel describes the color matrix for conversion between color
models.
* pname:ycbcrRange describes whether the encoded values have headroom and
foot room, or whether the encoding uses the full numerical range.
* pname:components applies a _swizzle_ based on elink:VkComponentSwizzle
enums prior to range expansion and color model conversion.
* pname:xChromaOffset describes the
<<textures-chroma-reconstruction,sample location>> associated with
downsampled chroma channels in the x dimension.
pname:xChromaOffset has no effect for formats in which chroma channels
are the same resolution as the luma channel.
* pname:yChromaOffset describes the
<<textures-chroma-reconstruction,sample location>> associated with
downsampled chroma channels in the y dimension.
pname:yChromaOffset has no effect for formats in which the chroma
channels are not downsampled vertically.
* pname:chromaFilter is the filter for chroma reconstruction.
* pname:forceExplicitReconstruction can: be used to ensure that
reconstruction is done explicitly, if supported.
[NOTE]
.Note
====
Setting pname:forceExplicitReconstruction to ename:VK_TRUE may: have a
performance penalty on implementations where explicit reconstruction is not
the default mode of operation.
====
.Valid Usage
****
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-format-01649]]
pname:format must: not be ename:VK_FORMAT_UNDEFINED
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-format-01650]]
pname:format must: support
ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or
ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-xChromaOffset-01651]]
If the format does not support
ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, pname:xChromaOffset
and pname:yChromaOffset must: not be
ename:VK_CHROMA_LOCATION_COSITED_EVEN
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-xChromaOffset-01652]]
If the format does not support
ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, pname:xChromaOffset
and pname:yChromaOffset must: not be ename:VK_CHROMA_LOCATION_MIDPOINT
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-format-01653]]
pname:format must: represent unsigned normalized values (i.e. the format
must be a etext:UNORM format)
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-None-01654]]
If the format has a etext:_422 or etext:_420 suffix:
** pname:components.g must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY
** pname:components.a must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY,
ename:VK_COMPONENT_SWIZZLE_ONE, or ename:VK_COMPONENT_SWIZZLE_ZERO
** pname:components.r must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY or
ename:VK_COMPONENT_SWIZZLE_B
** pname:components.b must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY or
ename:VK_COMPONENT_SWIZZLE_R
** If either pname:components.r or pname:components.b is
ename:VK_COMPONENT_SWIZZLE_IDENTITY, both values must: be
ename:VK_COMPONENT_SWIZZLE_IDENTITY
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-ycbcrModel-01655]]
If pname:ycbcrModel is not
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, then
pname:components.r, pname:components.g, and pname:components.b must:
correspond to channels of the pname:format; that is, pname:components.r,
pname:components.g, and pname:components.b must: not be
ename:VK_COMPONENT_SWIZZLE_ZERO or ename:VK_COMPONENT_SWIZZLE_ONE, and
must: not correspond to a channel which contains zero or one as a
consequence of <<textures-conversion-to-rgba,conversion to RGBA>>
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-forceExplicitReconstruction-01656]]
If the format does not support
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT,
pname:forceExplicitReconstruction must: be FALSE
* [[VUID-VkSamplerYcbcrConversionCreateInfoKHR-chromaFilter-01657]]
If the format does not support
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT,
pname:chromaFilter must: be ename:VK_FILTER_NEAREST
****
include::../validity/structs/VkSamplerYcbcrConversionCreateInfo.txt[]
If pname:chromaFilter is ename:VK_FILTER_NEAREST, chroma samples are
reconstructed to luma channel resolution using nearest-neighbour sampling.
Otherwise, chroma samples are reconstructed using interpolation.
More details can be found in <<textures-sampler-YCbCr-conversion,the
description of sampler Y'C~B~C~R~ conversion>> in the <<textures,Image
Operations>> chapter.
--
[open,refpage='VkSamplerYcbcrModelConversion',desc='Color model component of a color space',type='enums']
--
elink:VkSamplerYcbcrModelConversion defines the conversion from the source
color model to the shader color model.
Possible values are:
include::../api/enums/VkSamplerYcbcrModelConversion.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/enums/VkSamplerYcbcrModelConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY specifies that the
input values to the conversion are unmodified.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY specifies no
model conversion but the inputs are range expanded as for Y'C~B~C~R~.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 specifies the color
model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.709 and
described in the "`BT.709 Y’C~B~C~R~ conversion`" section of the
<<data-format,Khronos Data Format Specification>>.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 specifies the color
model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.601 and
described in the "`BT.601 Y’C~B~C~R~ conversion`" section of the
<<data-format,Khronos Data Format Specification>>.
* ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 specifies the color
model conversion from Y'C~B~C~R~ to R'G'B' defined in BT.2020 and
described in the "`BT.2020 Y’C~B~C~R~ conversion`" section of the
<<data-format,Khronos Data Format Specification>>.
In the etext:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_*_KHR color models, for
the input to the sampler Y'C~B~C~R~ range expansion and model conversion:
* the Y (Y' luma) channel corresponds to the G channel of an RGB image.
* the CB (C~B~ or "`U`" blue color difference) channel corresponds to the
B channel of an RGB image.
* the CR (C~R~ or "`V`" red color difference) channel corresponds to the R
channel of an RGB image.
* the alpha channel, if present, is not modified by color model
conversion.
These rules reflect the mapping of channels after the channel swizzle
operation (controlled by
slink:VkSamplerYcbcrConversionCreateInfo::pname:components).
[NOTE]
.Note
====
For example, an "`YUVA`" 32-bit format comprising four 8-bit channels can be
implemented as ename:VK_FORMAT_R8G8B8A8_UNORM with a component mapping:
* pname:components.a = ename:VK_COMPONENT_SWIZZLE_IDENTITY
* pname:components.r = ename:VK_COMPONENT_SWIZZLE_B
* pname:components.g = ename:VK_COMPONENT_SWIZZLE_R
* pname:components.b = ename:VK_COMPONENT_SWIZZLE_G
====
--
[open,refpage='VkSamplerYcbcrRange',desc='Range of encoded values in a color space',type='enums']
--
The elink:VkSamplerYcbcrRange enum describes whether color channels are
encoded using the full range of numerical values or whether values are
reserved for headroom and foot room.
elink:VkSamplerYcbcrRange is defined as:
include::../api/enums/VkSamplerYcbcrRange.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/enums/VkSamplerYcbcrRangeKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL indicates that the full range of
the encoded values are valid and interpreted according to the ITU "`full
range`" quantization rules.
* ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW indicates that headroom and foot
room are reserved in the numerical range of encoded values, and the
remaining values are expanded according to the ITU "`narrow range`"
quantization rules.
The formulae for these conversions is described in the
<<textures-sampler-YCbCr-conversion-rangeexpand,Sampler Y'C~B~C~R~ Range
Expansion>> section of the <<textures,Image Operations>> chapter.
No range modification takes place if pname:ycbcrModel is
ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY; the pname:ycbcrRange
field of sname:VkSamplerYcbcrConversionCreateInfo is ignored in this case.
--
[open,refpage='VkChromaLocation',desc='Position of downsampled chroma samples',type='enums']
--
The elink:VkChromaLocation enum, which defines the location of downsampled
chroma channel samples relative to the luma samples, is defined as:
include::../api/enums/VkChromaLocation.txt[]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
or the equivalent
include::../api/enums/VkChromaLocationKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* ename:VK_CHROMA_LOCATION_COSITED_EVEN indicates that downsampled chroma
samples are aligned with luma samples with even coordinates.
* ename:VK_CHROMA_LOCATION_MIDPOINT indicates that downsampled chroma
samples are located half way between each even luma sample and the
nearest higher odd luma sample.
--
[open,refpage='vkDestroySamplerYcbcrConversion',desc='Destroy a created Y\'CbCr conversion',type='protos']
--
To destroy a sampler Y'C~B~C~R~ conversion, call:
ifdef::VK_VERSION_1_1[]
include::../api/protos/vkDestroySamplerYcbcrConversion.txt[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1+VK_KHR_sampler_ycbcr_conversion[or the equivalent command]
ifdef::VK_KHR_sampler_ycbcr_conversion[]
include::../api/protos/vkDestroySamplerYcbcrConversionKHR.txt[]
endif::VK_KHR_sampler_ycbcr_conversion[]
* pname:device is the logical device that destroys the Y'C~B~C~R~
conversion.
* pname:ycbcrConversion is the conversion to destroy.
* pname:pAllocator controls host memory allocation as described in the
<<memory-allocation, Memory Allocation>> chapter.
include::../validity/protos/vkDestroySamplerYcbcrConversion.txt[]
--
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
Reference in New Issue View Git Blame Copy Permalink