Graphics.Vulkan.Core10.Sampler

Documentation

createSampler :: forall a io. (PokeChain a, MonadIO io) => Device -> SamplerCreateInfo a -> ("allocator" ::: Maybe AllocationCallbacks) -> io Sampler

vkCreateSampler - Create a new sampler object

Parameters

• device is the logical device that creates the sampler.

• pCreateInfo is a pointer to a SamplerCreateInfo structure specifying the state of the sampler object.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pSampler is a pointer to a Sampler handle in which the resulting sampler object is returned.

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid SamplerCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pSampler must be a valid pointer to a Sampler handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_TOO_MANY_OBJECTS

See Also

AllocationCallbacks, Device, Sampler, SamplerCreateInfo

withSampler :: forall a io r. (PokeChain a, MonadIO io) => (io Sampler -> (Sampler -> io ()) -> r) -> Device -> SamplerCreateInfo a -> Maybe AllocationCallbacks -> r

A convenience wrapper to make a compatible pair of calls to createSampler and destroySampler

To ensure that destroySampler is always called: pass bracket (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass '(,)' as the first argument.

destroySampler :: forall io. MonadIO io => Device -> Sampler -> ("allocator" ::: Maybe AllocationCallbacks) -> io ()

vkDestroySampler - Destroy a sampler object

Parameters

• device is the logical device that destroys the sampler.

• sampler is the sampler to destroy.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

• All submitted commands that refer to sampler must have completed execution

• If AllocationCallbacks were provided when sampler was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when sampler was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If sampler is not NULL_HANDLE, sampler must be a valid Sampler handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If sampler is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to sampler must be externally synchronized

See Also

AllocationCallbacks, Device, Sampler

data SamplerCreateInfo (es :: [Type])

VkSamplerCreateInfo - Structure specifying parameters of a newly created sampler

Description

Mapping of OpenGL to Vulkan filter modes

magFilter values of FILTER_NEAREST and 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 FILTER_LINEAR and mipmapMode of 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 SAMPLER_MIPMAP_MODE_NEAREST, minLod = 0, and maxLod = 0.25, and using minFilter = FILTER_LINEAR or minFilter = 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 PhysicalDeviceLimits structure. If maxSamplerAllocationCount is exceeded, createSampler will return ERROR_TOO_MANY_OBJECTS.

Since Sampler 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

• The absolute value of mipLodBias must be less than or equal to PhysicalDeviceLimits::maxSamplerLodBias

• maxLod must be greater than or equal to minLod
• If the anisotropic sampling feature is not enabled, anisotropyEnable must be FALSE
• If anisotropyEnable is TRUE, maxAnisotropy must be between 1.0 and PhysicalDeviceLimits::maxSamplerAnisotropy, inclusive
• If sampler Y′CBCR conversion is enabled and the sampler Y′CBCR conversion’s features do not support FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, minFilter and magFilter must be equal to the sampler Y′CBCR conversion’s chromaFilter
• If unnormalizedCoordinates is TRUE, minFilter and magFilter must be equal
• If unnormalizedCoordinates is TRUE, mipmapMode must be SAMPLER_MIPMAP_MODE_NEAREST
• If unnormalizedCoordinates is TRUE, minLod and maxLod must be zero
• If unnormalizedCoordinates is TRUE, addressModeU and addressModeV must each be either SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER
• If unnormalizedCoordinates is TRUE, anisotropyEnable must be FALSE
• If unnormalizedCoordinates is TRUE, compareEnable must be FALSE
• If any of addressModeU, addressModeV or addressModeW are SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, borderColor must be a valid BorderColor value
• If sampler Y′CBCR conversion is enabled, addressModeU, addressModeV, and addressModeW must be SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, anisotropyEnable must be FALSE, and unnormalizedCoordinates must be FALSE
• The sampler reduction mode must be set to SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE if sampler Y′CBCR conversion is enabled
• If samplerMirrorClampToEdge is not enabled, and if the VK_KHR_sampler_mirror_clamp_to_edge extension is not enabled, addressModeU, addressModeV and addressModeW must not be SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
• If compareEnable is TRUE, compareOp must be a valid CompareOp value
• If either magFilter or minFilter is FILTER_CUBIC_EXT, anisotropyEnable must be FALSE
• If compareEnable is TRUE, the reductionMode member of SamplerReductionModeCreateInfo must be SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then minFilter and magFilter must be equal
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then mipmapMode must be SAMPLER_MIPMAP_MODE_NEAREST
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then minLod and maxLod must be zero
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then addressModeU and addressModeV must each be either SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then anisotropyEnable must be FALSE
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then compareEnable must be FALSE
• If flags includes SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then unnormalizedCoordinates must be FALSE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SAMPLER_CREATE_INFO

• 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 SamplerReductionModeCreateInfo or SamplerYcbcrConversionInfo
• The sType value of each struct in the pNext chain must be unique
• flags must be a valid combination of SamplerCreateFlagBits values
• magFilter must be a valid Filter value
• minFilter must be a valid Filter value
• mipmapMode must be a valid SamplerMipmapMode value
• addressModeU must be a valid SamplerAddressMode value
• addressModeV must be a valid SamplerAddressMode value
• addressModeW must be a valid SamplerAddressMode value

See Also

Bool32, BorderColor, CompareOp, Filter, SamplerAddressMode, SamplerCreateFlags, SamplerMipmapMode, StructureType, createSampler

Constructors

SamplerCreateInfo

Fields

• next :: Chain es

  pNext is NULL or a pointer to an extension-specific structure.

• flags :: SamplerCreateFlags

  flags is a bitmask of SamplerCreateFlagBits describing additional parameters of the sampler.

• magFilter :: Filter

  magFilter is a Filter value specifying the magnification filter to apply to lookups.

• minFilter :: Filter

  minFilter is a Filter value specifying the minification filter to apply to lookups.

• mipmapMode :: SamplerMipmapMode

  mipmapMode is a SamplerMipmapMode value specifying the mipmap filter to apply to lookups.

• addressModeU :: SamplerAddressMode

  addressModeU is a SamplerAddressMode value specifying the addressing mode for outside [0..1] range for U coordinate.

• addressModeV :: SamplerAddressMode

  addressModeV is a SamplerAddressMode value specifying the addressing mode for outside [0..1] range for V coordinate.

• addressModeW :: SamplerAddressMode

  addressModeW is a SamplerAddressMode value specifying the addressing mode for outside [0..1] range for W coordinate.

• mipLodBias :: Float

  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 Level-of-Detail Operation section.

• anisotropyEnable :: Bool

  anisotropyEnable is TRUE to enable anisotropic filtering, as described in the Texel Anisotropic Filtering section, or FALSE otherwise.

• maxAnisotropy :: Float

  maxAnisotropy is the anisotropy value clamp used by the sampler when anisotropyEnable is TRUE. If anisotropyEnable is FALSE, maxAnisotropy is ignored.

• compareEnable :: Bool

  compareEnable is TRUE to enable comparison against a reference value during lookups, or FALSE otherwise.

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

  compareOp is a CompareOp value specifying the comparison function to apply to fetched data before filtering as described in the Depth Compare Operation section.

• minLod :: Float

  minLod and maxLod are the values used to clamp the computed LOD value, as described in the Level-of-Detail Operation section.

• maxLod :: Float
• borderColor :: BorderColor

  borderColor is a BorderColor value specifying the predefined border color to use.

• unnormalizedCoordinates :: Bool

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

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

  • The viewType must be either IMAGE_VIEW_TYPE_1D or IMAGE_VIEW_TYPE_2D.
  • The image view must have a single layer and a single mip level.

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

Instances

Extensible SamplerCreateInfo

Defined in Graphics.Vulkan.Core10.Sampler

Methods

extensibleType :: StructureType

getNext :: SamplerCreateInfo es -> Chain es

setNext :: SamplerCreateInfo ds -> Chain es -> SamplerCreateInfo es

extends :: Typeable e => proxy e -> (Extends SamplerCreateInfo e -> b) -> Maybe b

Show (Chain es) => Show (SamplerCreateInfo es)

Defined in Graphics.Vulkan.Core10.Sampler

Methods

showsPrec :: Int -> SamplerCreateInfo es -> ShowS

show :: SamplerCreateInfo es -> String

showList :: [SamplerCreateInfo es] -> ShowS

PeekChain es => FromCStruct (SamplerCreateInfo es)

Defined in Graphics.Vulkan.Core10.Sampler

Methods

peekCStruct :: Ptr (SamplerCreateInfo es) -> IO (SamplerCreateInfo es)

PokeChain es => ToCStruct (SamplerCreateInfo es)

Defined in Graphics.Vulkan.Core10.Sampler

Methods

withCStruct :: SamplerCreateInfo es -> (Ptr (SamplerCreateInfo es) -> IO b) -> IO b

pokeCStruct :: Ptr (SamplerCreateInfo es) -> SamplerCreateInfo es -> IO b -> IO b

withZeroCStruct :: (Ptr (SamplerCreateInfo es) -> IO b) -> IO b

pokeZeroCStruct :: Ptr (SamplerCreateInfo es) -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

es ~ ([] :: [Type]) => Zero (SamplerCreateInfo es)

Defined in Graphics.Vulkan.Core10.Sampler

Methods

zero :: SamplerCreateInfo es