vulkan/README.md

# frameworks/native/vulkan

This subdirectory contains Android's Vulkan loader, as well as some Vulkan-related tools useful to platform developers.

## Documentation

The former contents of doc/implementors_guide/ are now at https://source.android.com/devices/graphics/implement-vulkan.

## Coding Style

We follow the [Chromium coding style](https://www.chromium.org/developers/coding-style) for naming and formatting, except with four-space indentation instead of two spaces. In general, any C++ features supported by the prebuilt platform toolchain are allowed.

Use "clang-format -style=file" to format all C/C++ code, except code imported verbatim from elsewhere. Setting up git-clang-format in your environment is recommended.

## Code Generation

We generate several parts of the loader and tools directly from the Vulkan Registry (external/vulkan-headers/registry/vk.xml). Code generation must be done manually because the generator is not part of the platform toolchain (yet?). Files named `foo_gen.*` are generated by the code generator.

### Run The Code Generator

Install Python3 (if not already installed) and execute below:
`$ ./scripts/code_generator.py`

### `VKJson*` Files Code Generator Guide

## `vk_parser.py`

This script parses the Vulkan XML registry (`vk.xml`) and generates `vk.py`, which contains Python representations of Vulkan structures and mappings. Key functions include:
- Parsing `vk.xml` to extract Vulkan API constants, enums, handles, structs, and extensions.
- Generating Python `dataclasses` for Vulkan structs and handles.
- Creating mappings for features, extensions, and core versions to their corresponding structs.
- Handling C to Python type conversions and aliases.
- The main function is `gen_vk()`.

## `vkjson_generator.py`

This script generates the C++ code for serializing Vulkan device capabilities into a JSON format. It uses `vk.py` as its source of truth for Vulkan API information.
-   **`gen_h()`**: Generates `vkjson.h`, which defines the C++ structs (`VkJsonInstance`, `VkJsonDevice`, etc.) for storing Vulkan properties.
-   **`gen_cc()`**: Generates `vkjson.cc`, providing the JSON serialization and deserialization logic for the C++ structs.
-   **`gen_instance_cc()`**: Generates `vkjson_instance.cc`, which implements functions to query a physical device and populate the C++ structs with its capabilities.

## `vkjson_codegen.py`

This script serves as the primary entry point for regenerating all Vulkan JSON-related files. It performs the code generation process by calling the necessary functions from `vk_parser.py` and `vkjson_generator.py` in the correct order. Running this single script ensures that `vk.py`, `vkjson.h`, `vkjson.cc`, and `vkjson_instance.cc` are all updated based on the Vulkan XML registry.

### Vulkan EDI Pipeline Update Guide

This guide outlines the three main parts for updating the Vulkan EDI pipeline.

## Part 1: Update `vk.py` and `vkjson_*.cc` files

  - **Location**: Android repository : `$ANDROID_BUILD_TOP/frameworks/native/vulkan`
  - **Command**:
    `python3 scripts/vkjson_codegen.py`

## Part 2: Update Vulkan Device Info Collector (cts Repository)

  - **Location**: Android repository: `$ANDROID_BUILD_TOP/cts`
  - **Command**:
    `python3 common/device-side/device-info/src/com/android/compatibility/common/deviceinfo/scripts/code_generator.py`

## Part 3: Update the Protobuf Schemas (in google3)

# A. Generate `VulkanDeviceInfo.deviceinfo.json

  - **Location**: Android repository root: `$ANDROID_BUILD_TOP`
  - **Commands**:
    ```
        # Build the necessary CTS modules
        mmma cts/tools/cts-device-info/ cts/common/device-side/device-info

        # Install the collector APK. Note: The path depends on your lunch target.
        adb install -r -g out/target/product/<target_name>/testcases/CtsDeviceInfo/arm64/CtsDeviceInfo.apk

        # Run the instrumented test to generate the file on the device
        adb shell am instrument --no-isolated-storage -w \
        -e class com.android.compatibility.common.deviceinfo.VulkanDeviceInfo \
        com.android.compatibility.common.deviceinfo/androidx.test.runner.AndroidJUnitRunner

        # Pull the generated JSON from the device
        adb pull /sdcard/device-info-files/VulkanDeviceInfo.deviceinfo.json
    ```

# B. Generate Final Protobuf Files

Next, move to your `google3` workspace to update the source files and run the final proto generator script.

1. **Update `vk.py`**: Copy the `vk.py` from `$ANDROID_BUILD_TOP`/frameworks/native/vulkan/scripts file to `wireless/android/partner/adl/proto/scripts/`.
    - In the copied `vk.py` file, add a comment in the file to disable lint errors - `# pylint: disable=all`

2. **Update `VulkanDeviceInfo.deviceinfo.json`**: Copy the JSON file generated in the previous step (**A**) to `javatests/com/google/wireless/android/partner/adl/pipeline/extendeddeviceinfo/`.

3. **Run Generator**: Execute the following command to update the `.proto` files, `apfe.sdl`, and the `ExtendedDeviceInfoTest.java` test file.
      - **Location**: `google3`
      - **Command**:
        `python3 wireless/android/partner/adl/proto/scripts/vulkan_proto_gen.py`