VkSamplerCreateInfo(3)

# VkSamplerCreateInfo(3) Manual Page

## Name

VkSamplerCreateInfo - Structure specifying parameters of a newly created sampler

Loading… please wait.

## C Specification

The `VkSamplerCreateInfo` structure is defined as:

    // Provided by VK_VERSION_1_0
    typedef struct VkSamplerCreateInfo {
        VkStructureType         sType;
        const void*             pNext;
        VkSamplerCreateFlags    flags;
        VkFilter                magFilter;
        VkFilter                minFilter;
        VkSamplerMipmapMode     mipmapMode;
        VkSamplerAddressMode    addressModeU;
        VkSamplerAddressMode    addressModeV;
        VkSamplerAddressMode    addressModeW;
        float                   mipLodBias;
        VkBool32                anisotropyEnable;
        float                   maxAnisotropy;
        VkBool32                compareEnable;
        VkCompareOp             compareOp;
        float                   minLod;
        float                   maxLod;
        VkBorderColor           borderColor;
        VkBool32                unnormalizedCoordinates;
    } VkSamplerCreateInfo;

## Members

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `flags` is a bitmask of VkSamplerCreateFlagBits describing additional parameters of the sampler.

- `magFilter` is a VkFilter value specifying the magnification filter to apply to lookups.

- `minFilter` is a VkFilter value specifying the minification filter to apply to lookups.

- `mipmapMode` is a VkSamplerMipmapMode value specifying the mipmap filter to apply to lookups.

- `addressModeU` is a VkSamplerAddressMode value specifying the wrapping operation used when the i coordinate used to sample the image would be out of bounds.

- `addressModeV` is a VkSamplerAddressMode value specifying the wrapping operation used when the j coordinate used to sample the image would be out of bounds.

- `addressModeW` is a VkSamplerAddressMode value specifying the wrapping operation used when the k coordinate used to sample the image would be out of bounds. If `unnormalizedCoordinates` is VK_TRUE, `addressModeW` is ignored.

- `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 LOD Operation section.

- `anisotropyEnable` is VK_TRUE to enable anisotropic filtering, as described in the Texel Anisotropic Filtering section, or VK_FALSE otherwise.

- `maxAnisotropy` is the anisotropy value clamp used by the sampler when `anisotropyEnable` is VK_TRUE. If `anisotropyEnable` is VK_FALSE, `maxAnisotropy` is ignored.

- `compareEnable` is VK_TRUE to enable comparison against a reference value during lookups, or VK_FALSE otherwise.

  - Note: Some implementations will default to shader state if this member does not match.

- `compareOp` is a VkCompareOp value specifying the comparison operator to apply to fetched data before filtering as described in the Depth Compare Operation section.

- `minLod` is used to clamp the minimum of the computed LOD value.

- `maxLod` is used to clamp the maximum of the computed LOD value. To avoid clamping the maximum value, set `maxLod` to the constant VK_LOD_CLAMP_NONE.

- `borderColor` is a VkBorderColor value specifying the predefined border color to use.

- `unnormalizedCoordinates` controls whether to use unnormalized or normalized texel coordinates to address texels of the image. When `unnormalizedCoordinates` is 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 `unnormalizedCoordinates` is VK_FALSE, the range of image coordinates is zero to one.

  When `unnormalizedCoordinates` is VK_TRUE, images the sampler is used with in the shader have the following requirements:

  - The `viewType` must be either VK_IMAGE_VIEW_TYPE_1D or VK_IMAGE_VIEW_TYPE_2D.

  - The image view must have a single layer and a single mip level.

    When `unnormalizedCoordinates` is 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.

## Description

Note | Mapping of OpenGL to Vulkan Filter Modes `magFilter` values of VK_FILTER_NEAREST and VK_FILTER_LINEAR directly correspond to `GL_NEAREST` and `GL_LINEAR` magnification filters. `minFilter` and `mipmapMode` combine to correspond to the similarly named OpenGL minification filter of `GL_minFilter_MIPMAP_mipmapMode` (e.g. `minFilter` of VK_FILTER_LINEAR and `mipmapMode` of VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to `GL_LINEAR_MIPMAP_NEAREST`). There are no Vulkan filter modes that directly correspond to OpenGL minification filters of `GL_LINEAR` or `GL_NEAREST`, but they can be emulated using VK_SAMPLER_MIPMAP_MODE_NEAREST, `minLod` = 0, and `maxLod` = 0.25, and using `minFilter` = VK_FILTER_LINEAR or `minFilter` = VK_FILTER_NEAREST, respectively. Note that using a `maxLod` of zero would cause magnification to always be performed, and the `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 λ value to be non-zero and minification to be performed, while still always rounding down to the base level. If the `minFilter` and `magFilter` are equal, then using a `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 `maxSamplerAllocationCount` member of the VkPhysicalDeviceLimits structure.

Note | For historical reasons, if `maxSamplerAllocationCount` is exceeded, some implementations may return 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 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 `maxSamplerAllocationCount` limit.

When this structure is used to write a descriptor via vkWriteSamplerDescriptorsEXT, applications can give the descriptor a debug name in a similar way to naming an object, via the VkDebugUtilsObjectNameInfoEXT structure. However, as there is no actual object, VkDebugUtilsObjectNameInfoEXT must be passed via the `pNext` chain of this structure, with a `objectType` of VK_OBJECT_TYPE_UNKNOWN and a `objectHandle` of VK_NULL_HANDLE. The name is attached to the unique set of descriptor bits written by the implementation, and writing the same bits again with new debug info may rename the original descriptor.

Note | Implementations are not prevented from returning the same bits for different descriptors. This can result in multiple different samplers mapping to the same name.

VkDescriptorSetAndBindingMappingEXT can also be chained in the same way when defining an embedded sampler via VkDescriptorSetAndBindingMappingEXT, naming the embedded sampler.

Valid Usage

- VUID-VkSamplerCreateInfo-mipLodBias-01069
  The absolute value of `mipLodBias` must be less than or equal to `VkPhysicalDeviceLimits`::`maxSamplerLodBias`

- VUID-VkSamplerCreateInfo-samplerMipLodBias-04467
  If the `VK_KHR_portability_subset` extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::`samplerMipLodBias` is VK_FALSE, `mipLodBias` must be zero

- VUID-VkSamplerCreateInfo-maxLod-01973
  `maxLod` must be greater than or equal to `minLod`

- VUID-VkSamplerCreateInfo-anisotropyEnable-01070
  If the `samplerAnisotropy` feature is not enabled, `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-anisotropyEnable-01071
  If `anisotropyEnable` is VK_TRUE, `maxAnisotropy` must be between `1.0` and `VkPhysicalDeviceLimits`::`maxSamplerAnisotropy`, inclusive

- VUID-VkSamplerCreateInfo-minFilter-01645
  If sampler Y′CBCR conversion is enabled and the potential format features of the sampler Y′CBCR conversion do not support VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, `minFilter` and `magFilter` must be equal to the sampler Y′CBCR conversion’s `chromaFilter`

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072
  If `unnormalizedCoordinates` is VK_TRUE, `minFilter` and `magFilter` must be equal

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01073
  If `unnormalizedCoordinates` is VK_TRUE, `mipmapMode` must be VK_SAMPLER_MIPMAP_MODE_NEAREST

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01074
  If `unnormalizedCoordinates` is VK_TRUE, `minLod` and `maxLod` must be zero

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01075
  If `unnormalizedCoordinates` is VK_TRUE, `addressModeU` and `addressModeV` must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01076
  If `unnormalizedCoordinates` is VK_TRUE, `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01077
  If `unnormalizedCoordinates` is VK_TRUE, `compareEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-addressModeU-01078
  If any of `addressModeU`, `addressModeV` or `addressModeW` are VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, `borderColor` must be a valid VkBorderColor value

- VUID-VkSamplerCreateInfo-addressModeU-01646
  If sampler Y′CBCR conversion is enabled, `addressModeU`, `addressModeV`, and `addressModeW` must be VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, `anisotropyEnable` must be VK_FALSE, and `unnormalizedCoordinates` must be VK_FALSE

- VUID-VkSamplerCreateInfo-None-01647
  If sampler Y′CBCR conversion is enabled and the `pNext` chain includes a VkSamplerReductionModeCreateInfo structure, then the sampler reduction mode must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

- VUID-VkSamplerCreateInfo-pNext-06726
  If the `samplerFilterMinmax` feature is not enabled and the `pNext` chain includes a VkSamplerReductionModeCreateInfo structure, then the sampler reduction mode must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

- VUID-VkSamplerCreateInfo-addressModeU-01079
  If the `samplerMirrorClampToEdge` feature is not enabled, and if the `VK_KHR_sampler_mirror_clamp_to_edge` extension is not enabled, `addressModeU`, `addressModeV` and `addressModeW` must not be VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE

- VUID-VkSamplerCreateInfo-compareEnable-01080
  If `compareEnable` is VK_TRUE, `compareOp` must be a valid VkCompareOp value

- VUID-VkSamplerCreateInfo-magFilter-01081
  If either `magFilter` or `minFilter` is VK_FILTER_CUBIC_EXT, `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-magFilter-07911
  If the VK_EXT_filter_cubic extension is not enabled and either `magFilter` or `minFilter` is VK_FILTER_CUBIC_IMG, the `reductionMode` member of VkSamplerReductionModeCreateInfo must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

- VUID-VkSamplerCreateInfo-compareEnable-01423
  If `compareEnable` is VK_TRUE, the `reductionMode` member of VkSamplerReductionModeCreateInfo must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

- VUID-VkSamplerCreateInfo-flags-02574
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `minFilter` and `magFilter` must be equal

- VUID-VkSamplerCreateInfo-flags-02575
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `mipmapMode` must be VK_SAMPLER_MIPMAP_MODE_NEAREST

- VUID-VkSamplerCreateInfo-flags-02576
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `minLod` and `maxLod` must be zero

- VUID-VkSamplerCreateInfo-flags-02577
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `addressModeU` and `addressModeV` must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

- VUID-VkSamplerCreateInfo-flags-02578
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-flags-02579
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `compareEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-flags-02580
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `unnormalizedCoordinates` must be VK_FALSE

- VUID-VkSamplerCreateInfo-nonSeamlessCubeMap-06788
  If the `nonSeamlessCubeMap` feature is not enabled, `flags` must not include VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT

- VUID-VkSamplerCreateInfo-borderColor-04011
  If `borderColor` is one of VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT, then a VkSamplerCustomBorderColorCreateInfoEXT must be included in the `pNext` chain

- VUID-VkSamplerCreateInfo-customBorderColors-04085
  If the `customBorderColors` feature is not enabled, `borderColor` must not be VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT

- VUID-VkSamplerCreateInfo-borderColor-04442
  If `borderColor` is one of VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT, and VkSamplerCustomBorderColorCreateInfoEXT::`format` is not VK_FORMAT_UNDEFINED, VkSamplerCustomBorderColorCreateInfoEXT::`customBorderColor` must be within the range of values representable in `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 `maxCustomBorderColorSamplers` member of the VkPhysicalDeviceCustomBorderColorPropertiesEXT structure

- VUID-VkSamplerCreateInfo-flags-08110
  If `flags` includes VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the `descriptorBufferCaptureReplay` feature must be enabled

- VUID-VkSamplerCreateInfo-pNext-08111
  If the `pNext` chain includes a VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, `flags` must contain VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT

- VUID-VkSamplerCreateInfo-flags-06964
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `minFilter` and `magFilter` must be VK_FILTER_NEAREST

- VUID-VkSamplerCreateInfo-flags-06965
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `mipmapMode` must be VK_SAMPLER_MIPMAP_MODE_NEAREST

- VUID-VkSamplerCreateInfo-flags-06966
  [If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `minLod` and `maxLod` must be zero

- VUID-VkSamplerCreateInfo-flags-06967
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `addressModeU` and `addressModeV` must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

- VUID-VkSamplerCreateInfo-flags-06968
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, and if `addressModeU` or `addressModeV` is VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, then `borderColor` must be VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK

- VUID-VkSamplerCreateInfo-flags-06969
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-flags-06970
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `compareEnable` must be VK_FALSE

Valid Usage (Implicit)

- VUID-VkSamplerCreateInfo-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO

- VUID-VkSamplerCreateInfo-pNext-pNext
  Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkDebugUtilsObjectNameInfoEXT, VkOpaqueCaptureDescriptorDataCreateInfoEXT, VkSamplerBlockMatchWindowCreateInfoQCOM, VkSamplerBorderColorComponentMappingCreateInfoEXT, VkSamplerCubicWeightsCreateInfoQCOM, VkSamplerCustomBorderColorCreateInfoEXT, VkSamplerCustomBorderColorIndexCreateInfoEXT, VkSamplerReductionModeCreateInfo, or VkSamplerYcbcrConversionInfo

- VUID-VkSamplerCreateInfo-sType-unique
  The `sType` value of each structure in the `pNext` chain must be unique

- VUID-VkSamplerCreateInfo-flags-parameter
  `flags` must be a valid combination of VkSamplerCreateFlagBits values

- VUID-VkSamplerCreateInfo-magFilter-parameter
  `magFilter` must be a valid VkFilter value

- VUID-VkSamplerCreateInfo-minFilter-parameter
  `minFilter` must be a valid VkFilter value

- VUID-VkSamplerCreateInfo-mipmapMode-parameter
  `mipmapMode` must be a valid VkSamplerMipmapMode value

- VUID-VkSamplerCreateInfo-addressModeU-parameter
  `addressModeU` must be a valid VkSamplerAddressMode value

- VUID-VkSamplerCreateInfo-addressModeV-parameter
  `addressModeV` must be a valid VkSamplerAddressMode value

- VUID-VkSamplerCreateInfo-addressModeW-parameter
  `addressModeW` must be a valid VkSamplerAddressMode value

## See Also

VK_VERSION_1_0, VkBool32, VkBorderColor, VkCompareOp, VkDescriptorMappingSourceConstantOffsetEXT, VkDescriptorMappingSourceIndirectIndexArrayEXT, VkDescriptorMappingSourceIndirectIndexEXT, VkDescriptorMappingSourcePushIndexEXT, VkDescriptorMappingSourceShaderRecordIndexEXT, VkFilter, VkSamplerAddressMode, VkSamplerCreateFlags, VkSamplerMipmapMode, VkStructureType, vkCreateSampler, vkWriteSamplerDescriptorsEXT

## Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0