// Copyright (c) 2014-2019 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

include::{generated}/meta/VK_KHR_sampler_mirror_clamp_to_edge.txt[]

*Last Modified Date*::
    2019-08-17
*Contributors*::
  - Tobias Hector, Imagination Technologies
  - Jon Leech, Khronos

`VK_KHR_sampler_mirror_clamp_to_edge` extends the set of sampler address
modes to include an additional mode
(ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE) that effectively uses a
texture map twice as large as the original image in which the additional
half of the new image is a mirror image of the original image.

This new mode relaxes the need to generate images whose opposite edges match
by using the original image to generate a matching "`mirror image`".
This mode allows the texture to be mirrored only once in the negative s, t,
and r directions.

=== New Enum Constants

  * Extending elink:VkSamplerAddressMode:
  ** ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE

=== Example

Creating a sampler with the new address mode in each dimension


[source,c++]
----------------------------------------
    VkSamplerCreateInfo createInfo =
    {
        VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO // sType
        // Other members set to application-desired values
    };

    createInfo.addressModeU = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
    createInfo.addressModeV = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
    createInfo.addressModeW = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;

    VkSampler sampler;
    VkResult result = vkCreateSampler(
        device,
        &createInfo,
        &sampler);
----------------------------------------

=== Issues

1) Why are both KHR and core versions of the
ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE token present?

*RESOLVED*: This functionality was intended to be required in Vulkan 1.0.
We realized shortly before public release that not all implementations could
support it, and moved the functionality into an optional extension, but did
not apply the KHR extension suffix.
Adding a KHR-suffixed alias of the non-suffixed enum has been done to comply
with our own naming rules.

In a related change, before spec revision 1.1.121 this extension was
hardwiring into the spec Makefile so it was always included with the
Specification, even in the core-only versions.
This has now been reverted, and it is treated as any other extension.

=== Version History

 * Revision 1, 2016-02-16 (Tobias Hector)
   - Initial draft
 * Revision 2, 2019-08-14 (Jon Leech)
   - Add KHR-suffixed alias of non-suffixed enum.
 * Revision 3, 2019-08-17 (Jon Leech)
   - Add an issue explaining the reason for the extension API not being
     suffixed with KHR.