.. _SD.Graphics.VulkanSCSamples:

.. include:: /content/swdocs.rsts

.. spelling::
    vk
    vksc
    tri
    computeparticles
    vulkanscinfo
    offscreen
    html
    JSON
    gv
    ga
    Vulkan
    pregenerated

Vulkan SC Samples
!!!!!!!!!!!!!!!!!

Vulkan SC samples are included in Jetson Linux. This topic provides detailed steps to build and run these samples on the target.

Building the Samples
@@@@@@@@@@@@@@@@@@@@@

Prerequisites
=============
* The ``cmake`` with version 3.18 or later
* The ``build-essential`` Linux package
* ``NvSci`` headers. The headers are packaged in ``public_sources.tbz2`` that can be downloaded from NVIDIA Developer Center.
    #. To extract them, on host run:

    ::

        tar -I lbzip2 -xvf public_sources.tbz2 -C ./
        cd ./Linux_for_Tegra/source/public
        mkdir nvsci_headers
        tar -xvf nvsci_headers.tbz2 -C ./nvsci_headers

    #. Copy all the headers files under ``nvsci_headers`` to ``/usr/include`` on target.
* ``Vulkan`` headers. Download the ``Vulkan`` headers from `NVIDIA Developer Center <https://developer.nvidia.com/embedded/vulkan>`_,
  and place the headers to ``/usr/include`` on the target.

Build on the Target
===================
The sample source files are available in the ``/usr/src/nvidia/vulkan-sc/vulkan-sc-ecosystem/vulkan-sc-sample/`` directory.
The currently provided samples are:

* vksc_01tri
* vk_01tri
* vksc_computeparticles
* vk_computeparticles
* vulkanscinfo

The samples can only be built on target. To build the samples, run the following commands:

::

    export VKSC_SAMPLES=/usr/src/nvidia/vulkan-sc/vulkan-sc-ecosystem/vulkan-sc-sample
    cd $VKSC_SAMPLES
    mkdir build
    cd build
    cmake ../
    make

After the samples have been built, the sample binaries are generated in the ``build/bin`` directory

Running Vulkan SC Samples
@@@@@@@@@@@@@@@@@@@@@@@@@

Running the vulkanscinfo Command
================================

The ``vulkanscinfo`` command summarizes the core features of the Vulkan SC API and saves the output to the text/JSON/HTML file.

* To display a list of all available options for the ``vulkanscinfo`` command, specify the ``–help`` option:

    ::

        cd $VKSC_SAMPLES/build/bin
        ./vulkanscinfo —help

* To save the output to an HTML file, specify the –html option:

    ::

        cd $VKSC_SAMPLES/build/bin
        ./vulkanscinfo --html

    **Note**: By default you will not have write permission for the ``/usr/src`` folder, the output HTML could not be able to save. To fix the
    issue, run the following command:

    ::

        chmod u+w $VKSC_SAMPLES/build/bin

    or to run it under your your ``HOME`` folder:

    ::

        cd $HOME
        $VKSC_SAMPLES/build/bin/vulkanscinfo --html


Running the vksc_01tri Sample
=============================

To run the ``vksc_01tri`` sample, complete the following steps:

#. Generate the pipeline cache by running the PCC tool.

    ::

        cd $VKSC_SAMPLES/build/bin/data/pipeline/vksc_01tri
        pcc -chip [gv11b|ga10b] -path ./ -out pipeline_cache.bin

    **Note**: The `pipeline_cache.bin` file must be placed in the ``./data/pipeline/vksc_01tri`` directory, because
    the application will look for the ``pipeline_cache.bin`` file in the that directory.

#. Save the offscreen rendering result to an image file.

    ::

        cd $VKSC_SAMPLES/build/bin
        ./vksc_01tri -o

#. Display the rendering result by using OpenWFD.

    ::

        cd $VKSC_SAMPLES/build/bin
        ./vksc_01tri -w

#. (optional) You can generate the JSON file by using the JSON layer library as follows:

    The pregenerated pipeline configuration JSON files are in the ``./data/pipeline/vksc_01tri`` directory, and these files only
    need to be regenerated when there are the pipeline configuration or shader changes.

    ::

        cd $VKSC_SAMPLES/build/bin
        export VK_LAYER_PATH=/etc/vulkansc/icd.d
        export VK_JSON_FILE_PATH=$PWD/data/pipeline/vksc_01tri/
        ./vk_01tri

    The following files will be generated in ``VK_JSON_FILE_PATH``:
        * `vk_01tri_pipeline_0.json`
        * `vk_01tri_pipeline_0.vert.spv`
        * `vk_01tri_pipeline_0.frag.spv`

Running the vksc_computeparticles Sample
========================================

To run the ``vksc_computeparticles`` sample, complete the following steps:

#. Generate the pipeline cache by using the PCC tool.
    ::

        cd $VKSC_SAMPLES/build/bin/data/pipeline/computeparticles
        pcc -chip [gv11b|ga10b] -path ./ -out pipeline_cache.bin

    **Note**: The ``pipeline_cache.bin`` file must be placed in the ``./data/pipeline/computeparticles`` directory, because
    the application will look for the ``pipeline_cache.bin`` file in the that directory.

#. Save the offscreen rendering result to an image file.
    ::

        cd $VKSC_SAMPLES/build/bin
        ./vksc_computeparticles -o

#. Display the rendering result by using OpenWFD.
    ::

        cd $VKSC_SAMPLES/build/bin
        ./vksc_computeparticles -w

#. (optional) You can generate JSON file by using the JSON layer library as follows:

    The pregenerated pipeline configuration JSON files are in the ``./data/pipeline/computeparticles`` directory, and these files only
    need to be regenerated when there are the pipeline configuration or shader changes.
    ::

        cd $VKSC_SAMPLES/build/bin
        export VK_LAYER_PATH=/etc/vulkansc/icd.d
        export VK_JSON_FILE_PATH=$PWD/data/pipeline/computeparticles/
        ./vk_computeparticles

    The following files are generated in ``VK_JSON_FILE_PATH`` :

    * `vk_computeparticles_pipeline_0.json`
    * `vk_computeparticles_pipeline_1.json`
    * `vk_computeparticles_pipeline_0.frag.spv`
    * `vk_computeparticles_pipeline_0.vert.spv`
    * `vk_computeparticles_pipeline_1.compute.spv`

    This sample uses two different pipelines, graphics pipeline and compute
    pipeline; therefore, two JSON files are generated