VulkanApp Graphics API

- In development [2024.2]!
+ Authors: Gustavo Silva, Danilo Dutra, Cludio Evangelista, Matheus Araujo.
# Work for the Computer Graphics course at the Federal University of Catalo (UFCAT), Gois

This project demonstrates how to draw a triangle on the screen using vertex and fragment shaders in 2D, leveraging the Vulkan API (using the Vulkan SDK provided by LunarG) and the Python language. The code includes all the necessary steps to render the triangle, making it a comprehensive and easy-to-understand example of 2D rendering based on Vulkan.

Features

• GLFW Window Creation: Easily set up a window for rendering with Vulkan.
• Vulkan Integration: Uses the Vulkan API for efficient 3D rendering.
• 3D Rotating Cube: A simple, yet complete example of rendering a rotating 3D cube.
• Easy to Understand: The code is structured and commented for readability and ease of understanding.
• Python Implementation: Developed entirely in Python with Vulkan bindings.

Requirements

• Python 3.x: Ensure you have Python 3 installed.
• Vulkan SDK 1.3.x: Download and install the Vulkan SDK from LunarG.
• GLFW: Installed via Python's package manager pip:

  pip install glfw
  

• Vulkan Python Bindings: Install the Vulkan API bindings for Python via pip with the command:

  pip install vulkan
  

• Docker (optional): You can run this project using Docker for isolated development environments. For more details, see the Docker Setup from Docker Hub or Docker Setup from Local Build.

Installation

Manual setup

1. Clone the repository:

   git clone https://github.com/GustavoBorges13/vulkanapp-graphics-api.git
   cd vulkanapp-graphics-api
   

2. Install the required Python packages:

   pip install -r requirements.txt
   

3. Ensure the Vulkan SDK is properly installed on your system. You can check by running:

   vulkaninfo
   

4. Run the Python script to launch the 3D rotating cube:

   python main.py
   

Portable installation

coming soon

Installer setup

comming soon

Docker Setup from Docker Hub

To run graphical applications in Docker, you'll need to configure X11 display support based on your operating system.

General Notes

Ensure Docker is installed and configured on your machine.

For Windows Users

You can also follow the windows procedure in a solved problem here. If you need to display graphical applications from Docker on Windows, follow these steps:

1. Download and Install X Server:

   • Install VcXsrv, a Windows X Server tool. This will set up Xming and Xlaunch.

2. Configure Xlaunch:

   1. Launch Xlaunch after installation.
   2. In the "Select Display Settings" screen, keep "Multiple windows" checked.
   3. In the "Select how to start clients" screen, choose "Start no client".
   4. In the "Extra settings" screen, check "Disable access control".
   5. Click "Finish" to complete the setup.

3. Run the Docker Container:

   docker run -it --rm --name my_vulkan_app -e DISPLAY=host.docker.internal:0 gustavoborges13/vulkan_app
   
   # If you have an NVIDIA GPU (optional), use:
   docker run --gpus all -it --rm --name my_vulkan_app -e DISPLAY=host.docker.internal:0 gustavoborges13/vulkan_app
   

   Xlaunch will run in the background, waiting for X11 applications to connect and use display :0.

For Linux Users

To display graphical applications from Docker on Linux, follow these steps:

1. Install X Server:

   • Most Linux distributions come with an X server installed. If not, install it using your package manager:

     sudo apt-get install xorg
     

2. Configure X Server for Docker:

   • Allow Docker containers to access the X server:

     xhost +local:docker
     
     # To revoke access later (optional):
     xhost -local:docker
     

3. Run the Docker Container:

   docker run -it --rm --name my_vulkan_app -e DISPLAY=host.docker.internal:0 -v /tmp/.X11-unix:/tmp/.X11-unix gustavoborges13/vulkan_app
   
   # If you have an NVIDIA GPU (optional), use:
   docker run --gpus all -it --rm --name my_vulkan_app -e DISPLAY=host.docker.internal:0 -v /tmp/.X11-unix:/tmp/.X11-unix gustavoborges13/vulkan_app
   

   This setup will allow Docker containers to use the X11 display server on your Linux system.

For macOS Users

To display graphical applications from Docker on macOS, follow these steps:

1. Install X Server:

   • Download and install XQuartz from the official website.

2. Configure XQuartz:

   1. Open XQuartz after installation.
   2. Go to XQuartz > Preferences.
   3. In the "Security" tab, check "Allow connections from network clients".
   4. Restart XQuartz to apply the changes.

3. Run the Docker Container:

   • Run the Docker container:

     docker run -it --rm --name my_vulkan_app -e DISPLAY=host.docker.internal:0 gustavoborges13/vulkan_app
     
     # If you have an NVIDIA GPU (optional), use:
     docker run --gpus all -it --rm --name my_vulkan_app -e DISPLAY=host.docker.internal:0 gustavoborges13/vulkan_app
     

   XQuartz will provide the display server necessary for running X11 applications.

Docker Setup from Local Build

Using Dockerfile

The build will be performed by ./Dockerfile.

1. Clone the repository:

     git clone https://github.com/GustavoBorges13/vulkanapp-graphics-api.git
     cd vulkanapp-graphics-api
   

2. To build the Docker image, use the following command:

     docker build -t vulkanapp-graphics-api .
   

3. Run the Docker container:

     docker run -it --rm -e DISPLAY=host.docker.internal:0 vulkanapp-graphics-api
   
     # If you have an NVIDIA GPU (optional), use:
     docker run --gpus all -it --rm -e DISPLAY=host.docker.internal:0 vulkanapp-graphics-api
   

This command ensures that the container has access to the GPU and connects to the X Server on your host machine for graphical output.

It's worth remembering that the observations made earlier in the from docker hub procedure apply here too. Have the X server configured and docker installed.

Using Docker Compose

The build will be performed by ./docker-compose.yml.

It's worth remembering that the observations made earlier in the from docker hub procedure apply here too. Have the X server configured and docker installed for the application window to appear.

1. Clone the repository:

     git clone https://github.com/GustavoBorges13/vulkanapp-graphics-api.git
     cd vulkanapp-graphics-api
   

2. To build the Docker image and run, use the following command:

     docker-compose up
   

For detailed Docker commands, see the docker-commands.md file.

Usage

Once the application is running, a window will open displaying a 2D triangle. The triangle will be rendered using vertex and fragment shaders, demonstrating basic 2D rendering with the Vulkan API.

Project Structure

.
 .gitignore                  # Git ignore file
 app.py                      # Window glfw prepare
 colors.py                   # Color handling for print debugMode
 commands.py                 # Command handling and execution
 config.py                   # Python imports general
 device.py                   # Device selection and management
 docker-commands.md          # Docker commands and setup instructions
 docker-compose.yml          # Docker Compose configuration
 Dockerfile                  # Docker configuration for building the image
 engine.py                   # Core engine logic for the application
 frame.py                    # Frame handling for rendering
 framebuffer.py              # Framebuffer management
 instance.py                 # Vulkan instance creation
 LICENSE                     # License file for the project
 logging.py                  # Logging utilities - Validation Layers
 main.py                     # Main application to launch program
 memory.py                   # Memory management for Vulkan
 pipeline.py                 # Pipeline configuration and management
 queue_families.py           # Queue families management for Vulkan
 README.md                   # Project documentation and overview
 requirements.txt            # Python dependencies
 shaders.py                  # Shader management for rendering
 swapchain.py                # Swapchain handling for Vulkan
 sync.py                     # Synchronization primitives

 .github
    workflows
        Docker.yml          # GitHub Actions automatic workflow for Docker

 shaders                     # Shader files for the application
    compile_shaders.bat     # Batch script to compile shaders
    frag.spv                # Compiled fragment shader
    shader.frag             # Fragment shader source code
    shader.vert             # Vertex shader source code
    vert.spv                # Compiled vertex shader

 __pycache__                 # Compiled Python files

Getting Started with Vulkan API: Introduction and Basics

Dive into the world of Vulkan API! Whether you're new to graphics programming or looking to expand your skills, our guide provides a clear and engaging introduction to Vulkan's core concepts. Start building high-performance graphics applications today! Explore the Wiki