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 addressing mode for U coordinates outside [0,1).

- `addressModeV` is a VkSamplerAddressMode value specifying the addressing mode for V coordinates outside [0,1).

- `addressModeW` is a VkSamplerAddressMode value specifying the addressing mode for W coordinates outside [0,1).

- `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.

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 VkOpaqueCaptureDescriptorDataCreateInfoEXT, VkSamplerBlockMatchWindowCreateInfoQCOM, VkSamplerBorderColorComponentMappingCreateInfoEXT, VkSamplerCubicWeightsCreateInfoQCOM, VkSamplerCustomBorderColorCreateInfoEXT, VkSamplerReductionModeCreateInfo, or VkSamplerYcbcrConversionInfo

- VUID-VkSamplerCreateInfo-sType-unique
  The `sType` value of each struct 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, VkFilter, VkSamplerAddressMode, VkSamplerCreateFlags, VkSamplerMipmapMode, VkStructureType, vkCreateSampler

## 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-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0