VulkanApp Graphics API

- In development [2024.2]!
+ Authors: Gustavo Silva, Danilo Dutra, Cláudio Evangelista, Matheus Araujo.
# Work for the Computer Graphics course at the Federal University of Catalão (UFCAT), Goiás

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.

All credits to Professor Andrew for his teachings on YouTube https://www.youtube.com/@GetIntoGameDev

🌟 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