Vulkan-Docs/doc/specs/vulkan/appendices/VK_AMD_shader_fragment_mask.txt

include::meta/VK_AMD_shader_fragment_mask.txt[]

*Last Modified Date*::
    2017-08-16
*IP Status*::
    No known IP claims.
*Dependencies*::
  - Requires the
    https://www.khronos.org/registry/spir-v/extensions/AMD/SPV_AMD_fragment_mask.html[+SPV_AMD_fragment_mask+]
    SPIR-V extension.
*Contributors*::
  - Aaron Hagan, AMD
  - Daniel Rakos, AMD
  - Timothy Lottes, AMD

This extension provides efficient read access to the fragment mask in
compressed multisampled color surfaces.
The fragment mask is a lookup table that associates color samples with color
fragment values.

The fragment mask can be fetched with a call to code:fragmentMaskFetchAMD
from a shader, which returns a single code:uint where each subsequent 4 bit
specifies the color fragment index corresponding to the color sample,
starting from the least significant bit.
For example, when 8 color samples are used, the color fragment index for
color sample 0 will be in bits 0-3 of the fragment mask, for color sample 7
the index will be in bits 28-31.

The color fragment for a particular color sample may then be fetched with
the corresponding fragment mask value using the code:fragmentFetchAMD shader
function.

=== New Object Types

None.

=== New Enum Constants

None.

=== New Enums

None.

=== New SPIR-V Capabilities

  * <<spirvenv-capabilities-table-shaderfragmentmaskamd,
    code:ShaderFragmentMaskAMD>>

=== New Structures

None.

=== New Functions

None.

=== Examples

This example shows a shader that queries the fragment mask from a
multisampled compressed surface and uses it to query fragment values.

[source,c++]
----------------------------------------
#version 450 core

#extension GL_AMD_shader_fragment_mask: enable

layout(binding = 0) uniform sampler2DMS       s2DMS;
layout(binding = 1) uniform isampler2DMSArray is2DMSArray;

layout(binding = 2, input_attachment_index = 0) uniform usubpassInputMS usubpassMS;

layout(location = 0) out vec4 fragColor;

void main()
{
    vec4 fragOne = vec4(0.0);

    uint fragMask = fragmentMaskFetchAMD(s2DMS, ivec2(2, 3));
    uint fragIndex = (fragMask & 0xF0) >> 4;
    fragOne += fragmentFetchAMD(s2DMS, ivec2(2, 3), 1);

    fragMask = fragmentMaskFetchAMD(is2DMSArray, ivec3(2, 3, 1));
    fragIndex = (fragMask & 0xF0) >> 4;
    fragOne += fragmentFetchAMD(is2DMSArray, ivec3(2, 3, 1), fragIndex);

    fragMask = fragmentMaskFetchAMD(usubpassMS);
    fragIndex = (fragMask & 0xF0) >> 4;
    fragOne += fragmentFetchAMD(usubpassMS, fragIndex);

    fragColor = fragOne;
}
----------------------------------------

=== Version History

  * Revision 1, 2017-08-16 (Aaron Hagan)
    - Initial draft