| // Copyright 2015-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-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::{generated}/api/handles/VkSampler.txt[] |
| -- |
| |
| [open,refpage='vkCreateSampler',desc='Create a new sampler object',type='protos'] |
| -- |
| To create a sampler object, call: |
| |
| include::{generated}/api/protos/vkCreateSampler.txt[] |
| |
| * pname:device is the logical device that creates the sampler. |
| * pname:pCreateInfo is a pointer to a 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 is a pointer to a slink:VkSampler handle in which the |
| resulting sampler object is returned. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCreateSampler-maxSamplerAllocationCount-04110]] |
| There must: be less than |
| slink:VkPhysicalDeviceLimits::pname:maxSamplerAllocationCount |
| slink:VkSampler objects currently created on the device |
| **** |
| |
| include::{generated}/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::{generated}/api/structs/VkSamplerCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkSamplerCreateFlagBits describing |
| additional parameters of the sampler. |
| * 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 U coordinates outside [eq]#[0,1)#. |
| * pname:addressModeV is a elink:VkSamplerAddressMode value specifying the |
| addressing mode for V coordinates outside [eq]#[0,1)#. |
| * pname:addressModeW is a elink:VkSamplerAddressMode value specifying the |
| addressing mode for W coordinates outside [eq]#[0,1)#. |
| * [[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 is used to clamp the <<textures-level-of-detail-operation, |
| minimum of the computed LOD value>>. |
| * pname:maxLod is used to clamp the <<textures-level-of-detail-operation, |
| maximum of the computed LOD value>>. |
| To avoid clamping the maximum value, set pname:maxLod to the constant |
| ename:VK_LOD_CLAMP_NONE. |
| * 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 size in each |
| dimension. |
| When set to ename:VK_FALSE the range of image coordinates is zero to |
| one. |
| + |
| 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 |
| <<limits-maxSamplerAllocationCount,maxSamplerAllocationCount>> member of the |
| slink:VkPhysicalDeviceLimits structure. |
| |
| [NOTE] |
| .Note |
| ==== |
| For historical reasons, if pname:maxSamplerAllocationCount is exceeded, some |
| implementations may return ename:VK_ERROR_TOO_MANY_OBJECTS. |
| Exceeding this limit will result in undefined: behavior, and an application |
| should not rely on the use of the returned error code in order to identify |
| when the limit is reached. |
| ==== |
| |
| 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 |
| ifdef::VK_KHR_portability_subset[] |
| * [[VUID-VkSamplerCreateInfo-samplerMipLodBias-04467]] |
| If the `apiext:VK_KHR_portability_subset` extension is enabled, and |
| slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:samplerMipLodBias |
| is ename:VK_FALSE, pname:mipLodBias must: be zero |
| endif::VK_KHR_portability_subset[] |
| * [[VUID-VkSamplerCreateInfo-maxLod-01973]] |
| pname:maxLod must: be greater than or equal to pname:minLod |
| * [[VUID-VkSamplerCreateInfo-anisotropyEnable-01070]] |
| If the <<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 {YCbCr} conversion>> is enabled |
| and the <<potential-format-features, potential format features>> of the |
| sampler {YCbCr} conversion do not support |
| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, |
| pname:minFilter and pname:magFilter must: be equal to the sampler |
| {YCbCr} 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 {YCbCr} 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_VERSION_1_2,VK_EXT_sampler_filter_minmax[] |
| * [[VUID-VkSamplerCreateInfo-None-01647]] |
| The sampler reduction mode must: be set to |
| ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE if |
| <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> is enabled |
| endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkSamplerCreateInfo-addressModeU-01079]] |
| If <<features-samplerMirrorClampToEdge,samplerMirrorClampToEdge>> is not |
| enabled, and if the `apiext: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,VK_EXT_filter_cubic[] |
| * [[VUID-VkSamplerCreateInfo-magFilter-01081]] |
| If either pname:magFilter or pname:minFilter is |
| ename:VK_FILTER_CUBIC_EXT, pname:anisotropyEnable must: be |
| ename:VK_FALSE |
| endif::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] |
| ifdef::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] |
| ifndef::VK_EXT_filter_cubic[] |
| * [[VUID-VkSamplerCreateInfo-magFilter-01422]] |
| If either pname:magFilter or pname:minFilter is |
| ename:VK_FILTER_CUBIC_EXT, the pname:reductionMode member of |
| slink:VkSamplerReductionModeCreateInfo must: be |
| ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE |
| endif::VK_EXT_filter_cubic[] |
| endif::VK_IMG_filter_cubic+VK_EXT_sampler_filter_minmax[] |
| ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] |
| * [[VUID-VkSamplerCreateInfo-compareEnable-01423]] |
| If pname:compareEnable is ename:VK_TRUE, the pname:reductionMode member |
| of slink:VkSamplerReductionModeCreateInfo must: be |
| ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE |
| endif::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] |
| ifdef::VK_EXT_fragment_density_map[] |
| * [[VUID-VkSamplerCreateInfo-flags-02574]] |
| If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then |
| pname:minFilter and pname:magFilter must: be equal |
| * [[VUID-VkSamplerCreateInfo-flags-02575]] |
| If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then |
| pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST |
| * [[VUID-VkSamplerCreateInfo-flags-02576]] |
| If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then |
| pname:minLod and pname:maxLod must: be zero |
| * [[VUID-VkSamplerCreateInfo-flags-02577]] |
| If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then |
| 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-flags-02578]] |
| If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then |
| pname:anisotropyEnable must: be ename:VK_FALSE |
| * [[VUID-VkSamplerCreateInfo-flags-02579]] |
| If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then |
| pname:compareEnable must: be ename:VK_FALSE |
| * [[VUID-VkSamplerCreateInfo-flags-02580]] |
| If pname:flags includes ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then |
| pname:unnormalizedCoordinates must: be ename:VK_FALSE |
| endif::VK_EXT_fragment_density_map[] |
| ifdef::VK_EXT_custom_border_color[] |
| * [[VUID-VkSamplerCreateInfo-borderColor-04011]] |
| If pname:borderColor is one of ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or |
| ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, then a |
| slink:VkSamplerCustomBorderColorCreateInfoEXT must: be included in the |
| pname:pNext chain |
| * [[VUID-VkSamplerCreateInfo-customBorderColors-04085]] |
| If the <<features-customBorderColors, pname:customBorderColors>> feature |
| is not enabled, pname:borderColor must: not be |
| ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or |
| ename:VK_BORDER_COLOR_INT_CUSTOM_EXT |
| * [[VUID-VkSamplerCreateInfo-borderColor-04442]] |
| If pname:borderColor is one of ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or |
| ename:VK_BORDER_COLOR_INT_CUSTOM_EXT, and |
| slink:VkSamplerCustomBorderColorCreateInfoEXT::pname:format is not |
| ename:VK_FORMAT_UNDEFINED, |
| slink:VkSamplerCustomBorderColorCreateInfoEXT::pname:customBorderColor |
| must: be within the range of values representable in pname:format |
| * [[VUID-VkSamplerCreateInfo-None-04012]] |
| The maximum number of samplers with custom border colors which can: be |
| simultaneously created on a device is implementation-dependent and |
| specified by the |
| <<limits-maxCustomBorderColorSamplers,maxCustomBorderColorSamplers>> |
| member of the slink:VkPhysicalDeviceCustomBorderColorPropertiesEXT |
| structure |
| endif::VK_EXT_custom_border_color[] |
| **** |
| |
| include::{generated}/validity/structs/VkSamplerCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VK_LOD_CLAMP_NONE',desc='Maximum level of detail unclamped access sentinel',type='consts'] |
| -- |
| ename:VK_LOD_CLAMP_NONE is a special constant value used for |
| slink:VkSamplerCreateInfo::pname:maxLod to indicate that maximum LOD |
| clamping should not be performed. |
| |
| include::{generated}/api/enums/VK_LOD_CLAMP_NONE.txt[] |
| -- |
| |
| [open,refpage='VkSamplerCreateFlagBits',desc='Bitmask specifying additional parameters of sampler',type='enums'] |
| -- |
| Bits which can: be set in slink:VkSamplerCreateInfo::pname:flags, specifying |
| additional parameters of a sampler, are: |
| |
| include::{generated}/api/enums/VkSamplerCreateFlagBits.txt[] |
| |
| ifdef::VK_EXT_fragment_density_map[] |
| * [[samplers-subsamplesampler]] ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT |
| specifies that the sampler will read from an image created with |
| pname:flags containing ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT. |
| * ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT |
| specifies that the implementation may: use approximations when |
| reconstructing a full color value for texture access from a subsampled |
| image. |
| |
| [NOTE] |
| .Note |
| ==== |
| The approximations used when |
| ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT is |
| specified are implementation defined. |
| Some implementations may: interpolate between fragment density levels in a |
| subsampled image. |
| In that case, this bit may: be used to decide whether the interpolation |
| factors are calculated per fragment or at a coarser granularity. |
| ==== |
| endif::VK_EXT_fragment_density_map[] |
| -- |
| |
| [open,refpage='VkSamplerCreateFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkSamplerCreateFlags.txt[] |
| |
| tname:VkSamplerCreateFlags is a bitmask type for setting a mask of zero or |
| more elink:VkSamplerCreateFlagBits. |
| -- |
| |
| ifdef::VK_VERSION_1_2,VK_EXT_sampler_filter_minmax[] |
| [open,refpage='VkSamplerReductionModeCreateInfo',desc='Structure specifying sampler reduction mode',type='structs',alias='VkSamplerReductionModeCreateInfoEXT'] |
| -- |
| The sname:VkSamplerReductionModeCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkSamplerReductionModeCreateInfo.txt[] |
| |
| ifdef::VK_EXT_sampler_filter_minmax[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkSamplerReductionModeCreateInfoEXT.txt[] |
| endif::VK_EXT_sampler_filter_minmax[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:reductionMode is a elink:VkSamplerReductionMode value controlling |
| how texture filtering combines texel values. |
| |
| If the pname:pNext chain of slink:VkSamplerCreateInfo includes a |
| sname:VkSamplerReductionModeCreateInfo structure, then that structure |
| includes a mode 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. |
| |
| include::{generated}/validity/structs/VkSamplerReductionModeCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkSamplerReductionMode',desc='Specify reduction mode for texture filtering',type='enums',alias='VkSamplerReductionModeEXT'] |
| -- |
| Reduction modes are specified by elink:VkSamplerReductionMode, which takes |
| values: |
| |
| include::{generated}/api/enums/VkSamplerReductionMode.txt[] |
| |
| ifdef::VK_EXT_sampler_filter_minmax[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkSamplerReductionModeEXT.txt[] |
| endif::VK_EXT_sampler_filter_minmax[] |
| |
| * ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE specifies 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 specifies 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 specifies that texel values are |
| combined by taking the component-wise maximum of values in the footprint |
| with non-zero weights. |
| -- |
| endif::VK_VERSION_1_2,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::{generated}/api/enums/VkFilter.txt[] |
| |
| * ename:VK_FILTER_NEAREST specifies nearest filtering. |
| * ename:VK_FILTER_LINEAR specifies linear filtering. |
| ifdef::VK_IMG_filter_cubic,VK_EXT_filter_cubic[] |
| * ename:VK_FILTER_CUBIC_EXT specifies cubic filtering. |
| endif::VK_IMG_filter_cubic,VK_EXT_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::{generated}/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::{generated}/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. |
| ifdef::VK_VERSION_1_2,VK_KHR_sampler_mirror_clamp_to_edge[] |
| * 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 |
| ifdef::VK_VERSION_1_2[<<features-samplerMirrorClampToEdge,samplerMirrorClampToEdge>> is enabled, or if] |
| the `apiext:VK_KHR_sampler_mirror_clamp_to_edge` extension is enabled. |
| endif::VK_VERSION_1_2,VK_KHR_sampler_mirror_clamp_to_edge[] |
| -- |
| |
| [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::{generated}/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. |
| ifdef::VK_EXT_custom_border_color[] |
| * ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT indicates that a |
| slink:VkSamplerCustomBorderColorCreateInfoEXT structure is included in |
| the slink:VkSamplerCreateInfo::pname:pNext chain which contains the |
| color data in floating-point format. |
| * ename:VK_BORDER_COLOR_INT_CUSTOM_EXT indicates that a |
| slink:VkSamplerCustomBorderColorCreateInfoEXT structure is included in |
| the slink:VkSamplerCreateInfo::pname:pNext chain which contains the |
| color data in integer format. |
| endif::VK_EXT_custom_border_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::{generated}/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::{generated}/validity/protos/vkDestroySampler.txt[] |
| -- |
| |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| [[samplers-YCbCr-conversion]] |
| == Sampler {YCbCr} conversion |
| |
| [open,refpage='VkSamplerYcbcrConversionInfo',desc='Structure specifying {YCbCr} conversion to a sampler or image view',type='structs'] |
| -- |
| To create a sampler with {YCbCr} conversion enabled, add a |
| slink:VkSamplerYcbcrConversionInfo structure to the pname:pNext chain of the |
| slink:VkSamplerCreateInfo structure. |
| To create a sampler {YCbCr} conversion, the |
| <<features-samplerYcbcrConversion,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 is one of the <<formats-requiring-sampler-ycbcr-conversion, formats |
| that require a sampler Y'C~B~C~R~ conversion>> |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| , or if the image view has an |
| <<memory-external-android-hardware-buffer-external-formats,external format>> |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| . |
| |
| The sname:VkSamplerYcbcrConversionInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkSamplerYcbcrConversionInfo.txt[] |
| |
| ifdef::VK_KHR_sampler_ycbcr_conversion[] |
| or the equivalent |
| |
| include::{generated}/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 a structure extending this |
| structure. |
| * pname:conversion is a slink:VkSamplerYcbcrConversion handle created with |
| flink:vkCreateSamplerYcbcrConversion. |
| |
| include::{generated}/validity/structs/VkSamplerYcbcrConversionInfo.txt[] |
| -- |
| |
| [open,refpage='VkSamplerYcbcrConversion',desc='Opaque handle to a device-specific sampler {YCbCr} conversion description',type='handles'] |
| -- |
| A sampler {YCbCr} conversion is an opaque representation of a |
| device-specific sampler {YCbCr} conversion description, represented as a |
| sname:VkSamplerYcbcrConversion handle: |
| |
| include::{generated}/api/handles/VkSamplerYcbcrConversion.txt[] |
| |
| ifdef::VK_KHR_sampler_ycbcr_conversion[] |
| or the equivalent |
| |
| include::{generated}/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::{generated}/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::{generated}/api/protos/vkCreateSamplerYcbcrConversionKHR.txt[] |
| endif::VK_KHR_sampler_ycbcr_conversion[] |
| |
| * pname:device is the logical device that creates the sampler {YCbCr} |
| conversion. |
| * pname:pCreateInfo is a pointer to a |
| slink:VkSamplerYcbcrConversionCreateInfo structure specifying the |
| requested sampler {YCbCr} conversion. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pYcbcrConversion is a pointer to a slink:VkSamplerYcbcrConversion |
| handle in which the resulting sampler {YCbCr} conversion is returned. |
| |
| The interpretation of the configured sampler {YCbCr} conversion is described |
| in more detail in <<textures-sampler-YCbCr-conversion,the description of |
| sampler {YCbCr} conversion>> in the <<textures,Image Operations>> chapter. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCreateSamplerYcbcrConversion-None-01648]] |
| The <<features-samplerYcbcrConversion, sampler {YCbCr} conversion |
| feature>> must: be enabled |
| **** |
| |
| include::{generated}/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::{generated}/api/structs/VkSamplerYcbcrConversionCreateInfo.txt[] |
| |
| ifdef::VK_KHR_sampler_ycbcr_conversion[] |
| or the equivalent |
| |
| include::{generated}/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 a structure extending this |
| 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 components in the x dimension. |
| pname:xChromaOffset has no effect for formats in which chroma components |
| are not downsampled horizontally. |
| * pname:yChromaOffset describes the |
| <<textures-chroma-reconstruction,sample location>> associated with |
| downsampled chroma components in the y dimension. |
| pname:yChromaOffset has no effect for formats in which the chroma |
| components 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. |
| |
| If pname:format supports |
| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT |
| the pname:forceExplicitReconstruction value behaves as if it was set to |
| ename:VK_TRUE. |
| ==== |
| |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| If the pname:pNext chain includes a slink:VkExternalFormatANDROID structure |
| with non-zero pname:externalFormat member, the sampler {YCbCr} conversion |
| object represents an _external format conversion_, and pname:format must: be |
| ename:VK_FORMAT_UNDEFINED. |
| Such conversions must: only be used to sample image views with a matching |
| <<memory-external-android-hardware-buffer-external-formats,external |
| format>>. |
| When creating an external format conversion, the value of pname:components |
| is ignored. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| Sampler {YCbCr} conversion objects do not support _external format |
| conversion_ without additional extensions defining _external formats_. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| |
| .Valid Usage |
| **** |
| ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-04060]] |
| pname:format must: represent unsigned normalized values (i.e. the format |
| must be a etext:UNORM format) |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01904]] |
| If an external format conversion is being created, pname:format must: be |
| ename:VK_FORMAT_UNDEFINED |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-04061]] |
| If an external format conversion is not being created, pname:format |
| must: represent unsigned normalized values (i.e. the format must be a |
| etext:UNORM format) |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01650]] |
| The <<potential-format-features, potential format features>> of the |
| sampler {YCbCr} conversion must: support |
| ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or |
| ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01651]] |
| If the <<potential-format-features, potential format features>> of the |
| sampler {YCbCr} conversion do not support |
| ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, pname:xChromaOffset |
| and pname:yChromaOffset must: not be |
| ename:VK_CHROMA_LOCATION_COSITED_EVEN if the corresponding components |
| are <<textures-chroma-reconstruction, downsampled>> |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01652]] |
| If the <<potential-format-features, potential format features>> of the |
| sampler {YCbCr} conversion do not support |
| ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, pname:xChromaOffset |
| and pname:yChromaOffset must: not be ename:VK_CHROMA_LOCATION_MIDPOINT |
| if the corresponding components are <<textures-chroma-reconstruction, |
| downsampled>> |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02581]] |
| If the format has a etext:_422 or etext:_420 suffix, then |
| pname:components.g must: be the |
| <<resources-image-views-identity-mappings,identity swizzle>> |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02582]] |
| If the format has a etext:_422 or etext:_420 suffix, then |
| pname:components.a must: be the |
| <<resources-image-views-identity-mappings,identity swizzle>>, |
| ename:VK_COMPONENT_SWIZZLE_ONE, or ename:VK_COMPONENT_SWIZZLE_ZERO |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02583]] |
| If the format has a etext:_422 or etext:_420 suffix, then |
| pname:components.r must: be the |
| <<resources-image-views-identity-mappings,identity swizzle>> or |
| ename:VK_COMPONENT_SWIZZLE_B |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02584]] |
| If the format has a etext:_422 or etext:_420 suffix, then |
| pname:components.b must: be the |
| <<resources-image-views-identity-mappings,identity swizzle>> or |
| ename:VK_COMPONENT_SWIZZLE_R |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02585]] |
| If the format has a etext:_422 or etext:_420 suffix, and if either |
| pname:components.r or pname:components.b is the |
| <<resources-image-views-identity-mappings,identity swizzle>>, both |
| values must: be the identity swizzle |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-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 components 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 component which contains zero or one as a |
| consequence of <<textures-conversion-to-rgba,conversion to RGBA>> |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrRange-02748]] |
| If pname:ycbcrRange is ename:VK_SAMPLER_YCBCR_RANGE_ITU_NARROW then the |
| R, G and B components obtained by applying the pname:component swizzle |
| to pname:format must: each have a bit-depth greater than or equal to 8 |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-forceExplicitReconstruction-01656]] |
| If the <<potential-format-features, potential format features>> of the |
| sampler {YCbCr} conversion do not support |
| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT |
| pname:forceExplicitReconstruction must: be ename:VK_FALSE |
| * [[VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-01657]] |
| If the <<potential-format-features, potential format features>> of the |
| sampler {YCbCr} conversion do not support |
| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, |
| pname:chromaFilter must: not be ename:VK_FILTER_LINEAR |
| **** |
| |
| include::{generated}/validity/structs/VkSamplerYcbcrConversionCreateInfo.txt[] |
| |
| If pname:chromaFilter is ename:VK_FILTER_NEAREST, chroma samples are |
| reconstructed to luma component 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 {YCbCr} 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::{generated}/api/enums/VkSamplerYcbcrModelConversion.txt[] |
| |
| ifdef::VK_KHR_sampler_ycbcr_conversion[] |
| or the equivalent |
| |
| include::{generated}/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 {YCbCr}. |
| * ename:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 specifies the color |
| model conversion from {YCbCr} to {RGBprime} 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 {YCbCr} to {RGBprime} 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 {YCbCr} to {RGBprime} 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_* color models, for the |
| input to the sampler {YCbCr} range expansion and model conversion: |
| |
| * the Y (Y{prime} luma) component corresponds to the G component of an RGB |
| image. |
| * the CB (C~B~ or "`U`" blue color difference) component corresponds to |
| the B component of an RGB image. |
| * the CR (C~R~ or "`V`" red color difference) component corresponds to the |
| R component of an RGB image. |
| * the alpha component, if present, is not modified by color model |
| conversion. |
| |
| These rules reflect the mapping of components after the component swizzle |
| operation (controlled by |
| slink:VkSamplerYcbcrConversionCreateInfo::pname:components). |
| |
| [NOTE] |
| .Note |
| ==== |
| For example, an "`YUVA`" 32-bit format comprising four 8-bit components 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 components 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::{generated}/api/enums/VkSamplerYcbcrRange.txt[] |
| |
| ifdef::VK_KHR_sampler_ycbcr_conversion[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkSamplerYcbcrRangeKHR.txt[] |
| endif::VK_KHR_sampler_ycbcr_conversion[] |
| |
| * ename:VK_SAMPLER_YCBCR_RANGE_ITU_FULL specifies 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 specifies 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 {YCbCr} 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 slink:VkSamplerYcbcrConversionCreateInfo is ignored in this case. |
| -- |
| |
| [open,refpage='VkChromaLocation',desc='Position of downsampled chroma samples',type='enums'] |
| -- |
| The elink:VkChromaLocation enum defines the location of downsampled chroma |
| component samples relative to the luma samples, and is defined as: |
| |
| include::{generated}/api/enums/VkChromaLocation.txt[] |
| |
| ifdef::VK_KHR_sampler_ycbcr_conversion[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkChromaLocationKHR.txt[] |
| endif::VK_KHR_sampler_ycbcr_conversion[] |
| |
| * ename:VK_CHROMA_LOCATION_COSITED_EVEN specifies that downsampled chroma |
| samples are aligned with luma samples with even coordinates. |
| * ename:VK_CHROMA_LOCATION_MIDPOINT specifies 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 {YCbCr} conversion',type='protos'] |
| -- |
| To destroy a sampler {YCbCr} conversion, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/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::{generated}/api/protos/vkDestroySamplerYcbcrConversionKHR.txt[] |
| endif::VK_KHR_sampler_ycbcr_conversion[] |
| |
| * pname:device is the logical device that destroys the {YCbCr} conversion. |
| * pname:ycbcrConversion is the conversion to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| include::{generated}/validity/protos/vkDestroySamplerYcbcrConversion.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| ifdef::VK_EXT_custom_border_color[] |
| [open,refpage='VkSamplerCustomBorderColorCreateInfoEXT',desc='Structure specifying custom border color',type='structs'] |
| -- |
| In addition to the predefined border color values, applications can: provide |
| a custom border color value by including the |
| sname:VkSamplerCustomBorderColorCreateInfoEXT structure in the |
| slink:VkSamplerCreateInfo::pname:pNext chain. |
| |
| The sname:VkSamplerCustomBorderColorCreateInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkSamplerCustomBorderColorCreateInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:customBorderColor is a slink:VkClearColorValue representing the |
| desired custom sampler border color. |
| * pname:format is a elink:VkFormat representing the format of the sampled |
| image view(s). |
| This field may be ename:VK_FORMAT_UNDEFINED if the |
| <<features-customBorderColorWithoutFormat,customBorderColorWithoutFormat>> |
| feature is enabled. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04013]] |
| If provided pname:format is not ename:VK_FORMAT_UNDEFINED then the |
| slink:VkSamplerCreateInfo::pname:borderColor type must: match the |
| sampled type of the provided pname:format, as shown in the _SPIR-V |
| Sampled Type_ column of the <<formats-numericformat>> table |
| * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04014]] |
| If the |
| <<features-customBorderColorWithoutFormat,customBorderColorWithoutFormat>> |
| feature is not enabled then pname:format must: not be |
| ename:VK_FORMAT_UNDEFINED |
| * [[VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04015]] |
| If the sampler is used to sample an image view of |
| ename:VK_FORMAT_B4G4R4A4_UNORM_PACK16, |
| ename:VK_FORMAT_B5G6R5_UNORM_PACK16, or |
| ename:VK_FORMAT_B5G5R5A1_UNORM_PACK16 format then pname:format must: not |
| be ename:VK_FORMAT_UNDEFINED |
| **** |
| |
| include::{generated}/validity/structs/VkSamplerCustomBorderColorCreateInfoEXT.txt[] |
| -- |
| endif::VK_EXT_custom_border_color[] |
| |
| ifdef::VK_EXT_border_color_swizzle[] |
| [open,refpage='VkSamplerBorderColorComponentMappingCreateInfoEXT',desc='Structure specifying the component mapping of the border color',type='structs'] |
| -- |
| |
| If the sampler is created with ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK, |
| ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK, |
| ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, or |
| ename:VK_BORDER_COLOR_INT_CUSTOM_EXT pname:borderColor, and that sampler |
| will be combined with an image view that does not have an |
| <<resources-image-views-identity-mappings,identity swizzle>>, and |
| slink:VkPhysicalDeviceBorderColorSwizzleFeaturesEXT::pname:borderColorSwizzleFromImage |
| is not enabled, then it is necessary to specify the component mapping of the |
| border color, by including the |
| sname:VkSamplerBorderColorComponentMappingCreateInfoEXT structure in the |
| slink:VkSamplerCreateInfo::pname:pNext chain, to get defined results. |
| |
| The sname:VkSamplerBorderColorComponentMappingCreateInfoEXT structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkSamplerBorderColorComponentMappingCreateInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:components is a slink:VkComponentMapping structure specifying a |
| remapping of the border color components. |
| * pname:srgb indicates that the sampler will be combined with an image |
| view that has an image format which is sRGB encoded. |
| |
| The slink:VkComponentMapping pname:components member describes a remapping |
| from components of the border color to components of the vector returned by |
| shader image instructions when the border color is used. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkSamplerBorderColorComponentMappingCreateInfoEXT-borderColorSwizzle-06437]] |
| The <<features-borderColorSwizzle, pname:borderColorSwizzle>> feature |
| must: be enabled. |
| **** |
| |
| include::{generated}/validity/structs/VkSamplerBorderColorComponentMappingCreateInfoEXT.txt[] |
| -- |
| endif::VK_EXT_border_color_swizzle[] |
