KhronosGroup / KhronosGroup/Vulkan-Tools

Command line arguments behavior is inconsistent and USAGE is misleading

Open
#1,100 0 comments 0 reactions 1 assignee View on GitHub

@charles-lunarg is already working on this.

Since Mar 26, 2025.

bug enhancement vulkaninfo
Dominant language
C++
Stars
493
Forks
202
Avg merge
1h 37m
Merged PRs (30d)
4

Description

vulkaninfoSDK --help ouput the following but the USAGe section doesn't express how each argument can be combined.

Note that in the usage section, --show-video-props is missing.

$ vulkaninfoSDK --help

vulkaninfo - Summarize Vulkan information in relation to the current environment.

USAGE:
    vulkaninfoSDK.exe --summary
    vulkaninfoSDK.exe -o <filename> | --output <filename>
    vulkaninfoSDK.exe -j | -j=<gpu-number> | --json | --json=<gpu-number>
    vulkaninfoSDK.exe --text
    vulkaninfoSDK.exe --html
    vulkaninfoSDK.exe --show-formats
    vulkaninfoSDK.exe --show-tool-props
    vulkaninfoSDK.exe --show-promoted-structs

OPTIONS:
[-h, --help]         Print this help.
[--summary]          Show a summary of the instance and GPU's on a system.
[-o <filename>, --output <filename>]
                     Print output to a new file whose name is specified by filename.
                     File will be written to the current working directory.
[--text]             Produce a text version of vulkaninfo output to stdout. This is
                     the default output.
[--html]             Produce an html version of vulkaninfo output, saved as
                     "vulkaninfo.html" in the directory in which the command
                     is run.
[-j, --json]         Produce a json version of vulkaninfo output conforming to the Vulkan
                     Profiles schema, saved as
                     "VP_VULKANINFO_[DEVICE_NAME]_[DRIVER_VERSION].json"
                     of the first gpu in the system.
[-j=<gpu-number>, --json=<gpu-number>]
                     For a multi-gpu system, a single gpu can be targeted by
                     specifying the gpu-number associated with the gpu of
                     interest. This number can be determined by running
                     vulkaninfo without any options specified.
[--show-tool-props]  Show the active VkPhysicalDeviceToolPropertiesEXT that vulkaninfo finds.
[--show-formats]     Display the format properties of each physical device.
                     Note: This only affects text output.
[--show-promoted-structs] Include structs promoted to core in pNext Chains.
[--show-video-props]
                     Display the video profile info, video capabilities and
                     video format properties of each video profile supported
                     by each physical device.
                     Note: This only affects text output which by default
                     only contains the list of supported video profile names.

Here is an example to express how the arguments can be combined:

$ vkconfig loader --help
vkconfig: Invalid 'loader' command argument: '--help'...

Name
        'loader' - Command to manage system Vulkan Loader configuration

Synopsis
        vkconfig loader (--override | -o) (<configuration_index> | <configuration_name> | <configuration_file>)
        vkconfig loader (--surrender | -s)
        vkconfig loader (--list | -l)
        vkconfig loader (--import | -i) <configuration_file>
        vkconfig loader (--export | -e) (<configuration_index> | <configuration_name>) <configuration_file>
        vkconfig loader (--delete | -d) (<configuration_index> | <configuration_name>)

Description
        vkconfig loader (--override | -o) (<configuration_index> | <configuration_name> | <configuration_file>)
                Override the system Vulkan Loader configuration generated by Vulkan Configurator.
                 - <configuration_index> is an index enumerated with `vkconfig loader --list`.
                 - <configuration_name> is the name of the stored configuration listed with `vkconfig loader --list`.

        vkconfig loader (--surrender | -s)
                Surrender the Vulkan Loader configuration to Vulkan applications.

        vkconfig loader (--list | -l)
                List the Vulkan Loader configurations found by Vulkan Configurator on the system.

        vkconfig loader (--import | -i) <configuration_file>
                Import a Vulkan Loader configuration stored by Vulkan Configurator on the system.

        vkconfig loader (--export | -e) (<configuration_index> | <configuration_name>) <configuration_file>
                Export a Vulkan Loader configuration stored by Vulkan Configurator on the system.
                 - <configuration_index> is an index enumerated with `vkconfig loader --list`.
                 - <configuration_name> is the name of the stored configuration listed with `vkconfig loader --list`.

        vkconfig loader (--delete | -d) (<configuration_index> | <configuration_name>)
                Remove a Vulkan Loader configuration stored by Vulkan Configurator on the system.
                 - <configuration_index> is an index enumerated with `vkconfig loader --list`.
                 - <configuration_name> is the name of the stored configuration listed with `vkconfig loader --list`.

My suggestion for vulkaninfo USAGE would be:

$ vulkaninfoSDK --help

vulkaninfo - Summarize Vulkan information in relation to the current environment.

USAGE:
    vulkaninfoSDK.exe --summary
    vulkaninfoSDK.exe --text (-o (<filename>) (--show-formats) (--show-tool-props) (--show-promoted-structs) (--show-video-props)
    vulkaninfoSDK.exe --html (-o (<filename>) (--show-formats) (--show-tool-props) (--show-promoted-structs) (--show-video-props)
    vulkaninfoSDK.exe --json(=<gpu-number>) (-o (<filename>) (--show-tool-props) (--show-promoted-structs) (--show-video-props)

OPTIONS:
[-h, --help]         Print this help.
[--summary]          Show a summary of the instance and GPU's on a system.
[-o <filename>, --output <filename>]
                     Print output to a new file whose name is specified by filename.
                     File will be written to the current working directory.
[--text]             Produce a text version of vulkaninfo output to stdout. This is
                     the default output.
[--html]             Produce an html version of vulkaninfo output, saved as
                     "vulkaninfo.html" in the directory in which the command
                     is run.
[-j, --json]         Produce a json version of vulkaninfo output conforming to the Vulkan
                     Profiles schema, saved as
                     "VP_VULKANINFO_[DEVICE_NAME]_[DRIVER_VERSION].json"
                     of the first gpu in the system.
[-j=<gpu-number>, --json=<gpu-number>]
                     For a multi-gpu system, a single gpu can be targeted by
                     specifying the gpu-number associated with the gpu of
                     interest. This number can be determined by running
                     vulkaninfo without any options specified.
[--show-tool-props]  Show the active VkPhysicalDeviceToolPropertiesEXT that vulkaninfo finds.
[--show-formats]     Display the format properties of each physical device.
                     Note: This only affects text output.
[--show-promoted-structs] Include structs promoted to core in pNext Chains.
[--show-video-props]
                     Display the video profile info, video capabilities and
                     video format properties of each video profile supported
                     by each physical device.
                     Note: This only affects text output which by default
                     only contains the list of supported video profile names.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.