// Copyright (c) 2015-2019 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::{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 an instance of the slink:VkSamplerCreateInfo structure specifying the state of the sampler object. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pSampler points to a slink:VkSampler handle in which the resulting sampler object is returned. 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 an extension-specific 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 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 <> section. * [[samplers-maxAnisotropy]] pname:anisotropyEnable is ename:VK_TRUE to enable anisotropic filtering, as described in the <> 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 <> section. * pname:minLod and pname:maxLod are the values used to clamp the computed LOD value, as described in the <> section. * 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, 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 <> 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 <> 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-maxLod-01973]] pname:maxLod must: be greater than or equal to pname:minLod * [[VUID-VkSamplerCreateInfo-anisotropyEnable-01070]] If the <> 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 <> 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 <> 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 <> is enabled endif::VK_EXT_sampler_filter_minmax[] endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] * [[VUID-VkSamplerCreateInfo-addressModeU-01079]] If the `<>` 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:VkSamplerReductionModeCreateInfoEXT must: be ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT endif::VK_EXT_filter_cubic[] 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[] 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[] **** include::{generated}/validity/structs/VkSamplerCreateInfo.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_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::{generated}/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::{generated}/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::{generated}/api/enums/VkSamplerReductionModeEXT.txt[] * ename:VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT specifies that texel values are combined by computing a weighted average of values in the footprint, using weights as specified in <>. * ename:VK_SAMPLER_REDUCTION_MODE_MIN_EXT 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_EXT specifies 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::{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 <>. -- [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 <>. -- [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 <> 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. * 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 `<>` 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::{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. These colors are described in detail in <>. -- [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 <> 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 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 <> 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 <> ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] , or if the image view has an <> 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 an extension-specific 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 Y\'C~B~C~R~ conversion description',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::{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 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 <> 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 <> in the <> chapter. .Valid Usage **** * [[VUID-vkCreateSamplerYcbcrConversion-None-01648]] The <> 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 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 <> 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 <> 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. ==== ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] If the pname:pNext chain has an instance of slink:VkExternalFormatANDROID with non-zero pname:externalFormat member, the sampler Y'C~B~C~R~ 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 <>. 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 Y'C~B~C~R~ 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-01649]] pname:format must: not be ename:VK_FORMAT_UNDEFINED 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, otherwise it must: not be ename:VK_FORMAT_UNDEFINED. endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-VkSamplerYcbcrConversionCreateInfo-format-01650]] pname:format 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 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-VkSamplerYcbcrConversionCreateInfo-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-VkSamplerYcbcrConversionCreateInfo-format-01653]] pname:format must: represent unsigned normalized values (i.e. the format must be a etext:UNORM format) * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02581]] If the format has a etext:_422 or etext:_420 suffix, then pname:components.g must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY * [[VUID-VkSamplerYcbcrConversionCreateInfo-components-02582]] If the format has a etext:_422 or etext:_420 suffix, then pname:components.a must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY, 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 ename:VK_COMPONENT_SWIZZLE_IDENTITY 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 ename:VK_COMPONENT_SWIZZLE_IDENTITY 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 ename:VK_COMPONENT_SWIZZLE_IDENTITY, both values must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY * [[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 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 <> * [[VUID-VkSamplerYcbcrConversionCreateInfo-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-VkSamplerYcbcrConversionCreateInfo-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::{generated}/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 <> in the <> 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 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 <>. * 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 <>. * 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 <>. In the etext:VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_* 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::{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 <> section of the <> 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::{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 Y\'CbCr conversion',type='protos'] -- To destroy a sampler Y'C~B~C~R~ 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 Y'C~B~C~R~ conversion. * pname:ycbcrConversion is the conversion to destroy. * pname:pAllocator controls host memory allocation as described in the <> chapter. include::{generated}/validity/protos/vkDestroySamplerYcbcrConversion.txt[] -- endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]