// Copyright (c) 2017-2020 Advanced Micro Devices, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_AMD_shader_info.txt[]

=== Other Extension Metadata

*Last Modified Date*::
    2017-10-09
*IP Status*::
    No known IP claims.
*Contributors*::
  - Jaakko Konttinen, AMD

=== Description

This extension adds a way to query certain information about a compiled
shader which is part of a pipeline.
This information may include shader disassembly, shader binary and various
statistics about a shader's resource usage.

While this extension provides a mechanism for extracting this information,
the details regarding the contents or format of this information are not
specified by this extension and may be provided by the vendor externally.

Furthermore, all information types are optionally supported, and users
should not assume every implementation supports querying every type of
information.

include::{generated}/interfaces/VK_AMD_shader_info.txt[]

=== Examples

This example extracts the register usage of a fragment shader within a
particular graphics pipeline:

[source,c++]
----------------------------------------
extern VkDevice device;
extern VkPipeline gfxPipeline;

PFN_vkGetShaderInfoAMD pfnGetShaderInfoAMD = (PFN_vkGetShaderInfoAMD)vkGetDeviceProcAddr(
    device, "vkGetShaderInfoAMD");

VkShaderStatisticsInfoAMD statistics = {};

size_t dataSize = sizeof(statistics);

if (pfnGetShaderInfoAMD(device,
    gfxPipeline,
    VK_SHADER_STAGE_FRAGMENT_BIT,
    VK_SHADER_INFO_TYPE_STATISTICS_AMD,
    &dataSize,
    &statistics) == VK_SUCCESS)
{
    printf("VGPR usage: %d\n", statistics.resourceUsage.numUsedVgprs);
    printf("SGPR usage: %d\n", statistics.resourceUsage.numUsedSgprs);
}
----------------------------------------

The following example continues the previous example by subsequently
attempting to query and print shader disassembly about the fragment shader:

[source,c++]
----------------------------------------
// Query disassembly size (if available)
if (pfnGetShaderInfoAMD(device,
    gfxPipeline,
    VK_SHADER_STAGE_FRAGMENT_BIT,
    VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD,
    &dataSize,
    nullptr) == VK_SUCCESS)
{
    printf("Fragment shader disassembly:\n");

    void* disassembly = malloc(dataSize);

    // Query disassembly and print
    if (pfnGetShaderInfoAMD(device,
        gfxPipeline,
        VK_SHADER_STAGE_FRAGMENT_BIT,
        VK_SHADER_INFO_TYPE_DISASSEMBLY_AMD,
        &dataSize,
        disassembly) == VK_SUCCESS)
    {
        printf((char*)disassembly);
    }

    free(disassembly);
}
----------------------------------------


=== Version History

  * Revision 1, 2017-10-09 (Jaakko Konttinen)
    - Initial revision