// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ VkSamplerCreateInfo(3) ====================== Name ---- VkSamplerCreateInfo - Structure specifying parameters of a newly created sampler C Specification --------------- // refBegin VkSamplerCreateInfo - Structure specifying parameters of a newly created sampler The sname:VkSamplerCreateInfo structure is defined as: include::../api/structs/VkSamplerCreateInfo.txt[] Members ------- * 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 the magnification filter to apply to lookups, and is of type: + -- // refBegin VkFilter - specify filters used for texture lookups include::../api/enums/VkFilter.txt[] -- + * pname:minFilter is the minification filter to apply to lookups, and is of type elink:VkFilter. * pname:mipmapMode is the mipmap filter to apply to lookups as described in the <> section, and is of type: + -- // refBegin VkSamplerMipmapMode - specify mipmap mode used for texture lookups include::../api/enums/VkSamplerMipmapMode.txt[] -- + * pname:addressModeU is the addressing mode for outside [0..1] range for U coordinate. See elink:VkSamplerAddressMode. * pname:addressModeV is the addressing mode for outside [0..1] range for V coordinate. See elink:VkSamplerAddressMode. * pname:addressModeW is the addressing mode for outside [0..1] range for W coordinate. See elink:VkSamplerAddressMode. * [[samplers-mipLodBias]] pname:mipLodBias is the bias to be added to mipmap LOD calculation and bias provided by image sampling functions in SPIR-V, as described in the <> 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. * 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 the comparison function to apply to fetched data before filtering as described in the <> section. See elink:VkCompareOp. * pname:minLod and pname:maxLod are the values used to clamp the computed level-of-detail value, as described in the <> section. pname:maxLod must: be greater than or equal to pname:minLod. * pname:borderColor is the predefined border color to use, as described in the <> section, and is of type: + -- // refBegin VkBorderColor - specify border color used for texture lookups include::../api/enums/VkBorderColor.txt[] -- + * [[samplers-unnormalizedCoordinates]] pname:unnormalizedCoordinates controls whether to use unnormalized or normalized texel coordinates to address texels of the image. When set to ename:VK_TRUE, the range of the image coordinates used to lookup the texel is in the range of zero to the image dimensions for x, y and z. When set to ename:VK_FALSE the range of image coordinates is zero to one. When pname:unnormalizedCoordinates is ename:VK_TRUE, samplers have the following requirements: ** pname:minFilter and pname:magFilter must: be equal. ** pname:mipmapMode must: be ename:VK_SAMPLER_MIPMAP_MODE_NEAREST. ** pname:minLod and pname:maxLod must: be zero. ** pname:addressModeU and pname:addressModeV must: each be either ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER. ** pname:anisotropyEnable must: be ename:VK_FALSE. ** pname:compareEnable must: be ename:VK_FALSE. * When pname:unnormalizedCoordinates is ename:VK_TRUE, images the sampler is used with in the shader have the following requirements: ** The pname:viewType must: be either ename:VK_IMAGE_VIEW_TYPE_1D or ename:VK_IMAGE_VIEW_TYPE_2D. ** The image view must: have a single layer and a single mip level. * When pname:unnormalizedCoordinates is ename:VK_TRUE, image built-in functions in the shader that use the sampler have the following requirements: ** The functions mustnot: use projection. ** The functions mustnot: use offsets. Description ----------- [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 latexmath:[$\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. ================== pname:addressModeU, pname:addressModeV, and pname:addressModeW must: each have one of the following values: // refBegin VkSamplerAddressMode - specify behavior of sampling with texture coordinates outside an image include::../api/enums/VkSamplerAddressMode.txt[] These values control the behavior of sampling with coordinates outside the range latexmath:[$[0,1\]$] for the respective u, v, or w coordinate as defined in the <> section. * ename:VK_SAMPLER_ADDRESS_MODE_REPEAT indicates that the repeat wrap mode will be used. * ename:VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT indicates that the mirrored repeat wrap mode will be used. * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE indicates that the clamp to edge wrap mode will be used. * ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER indicates that the clamp to border wrap mode will be used. * ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE indicates that the mirror clamp to edge wrap mode will be used. This is only valid if the VK_KHR_mirror_clamp_to_edge extension is enabled. The maximum number of sampler objects which can: be simultaneously created on a device is implementation-dependent and specified by the <> member of the sname:VkPhysicalDeviceLimits structure. If pname:maxSamplerAllocationCount is exceeded, fname:vkCreateSampler will return ename:VK_ERROR_TOO_MANY_OBJECTS. Since sname: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. include::../validity/structs/VkSamplerCreateInfo.txt[] See Also -------- basetype:VkBool32, elink:VkBorderColor, elink:VkCompareOp, elink:VkFilter, elink:VkSamplerAddressMode, elink:VkSamplerCreateFlags, elink:VkSamplerMipmapMode, elink:VkStructureType, flink:vkCreateSampler Document Notes -------------- For more information, see the Vulkan Specification at URL https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkSamplerCreateInfo This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly. include::footer.txt[]