vkforge 0.6.0
VkForge: A Vulkan User-End API Implementation Generator for Renderer Development
Requires Python: >=3.8

# VkForge - Vulkan End-User API Implementation Generator

[![PyPI version](https://img.shields.io/pypi/v/vkforge)](https://pypi.org/project/vkforge/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**VkForge** is a **lean Vulkan code generator** that helps you write Vulkan applications faster by generating boilerplate implementations. It gives you direct control over Vulkan while automating repetitive setup code.

## Why Use VkForge?

- **Write real Vulkan code** - No hidden abstractions or magic  
- **Save development time** - Generate Vulkan boilerplate instantly  
- **Small and focused** - C99 code, C++ compatible  
- **Flexible usage** - Pick only what you need  
- **SDL3 integration** - With plans for more platform support  

```c
// Example: Get started quickly
#include "vkforge_typedecls.h"  // Generated type declarations
#include "vkforge_funcdecls.h"  // Generated function declarations

int main() {
    SDL_Window* window = SDL_CreateWindow("App", 800, 600, SDL_WINDOW_VULKAN);
    VkForgeCore* core = VkForge_CreateCore(window, 0, 0); // Convenience creator for core Vulkan objects
    VkForgeRender* render = VkForge_CreateRender(/*...*/); // Object designed for rending with Vulkan
    
    while(running) {
        VkForge_UpdateRender(render); // Handles Vulkan complexity
    }
}
```

## Key Features

### Automatic Vulkan Implementation
- Generates Vulkan initialization code (instance, device, swapchain)
- Creates pipelines from your shaders
- Builds descriptor layouts automatically
- Uses glslangValidator (from Vulkan SDK) for GLSL compilation

### Helpful Utilities
- Basic texture loading via SDL3_image
- Memory management helpers
- Synchronization utilities
- Dynamic rendering (Vulkan 1.3)

### Flexible Generation
- Generate complete implementations or just specific components
- Mix generated and handwritten code
- Update pipelines as shaders change

## How It Works

VkForge generates clean C code by analyzing:

1. **Your Shaders** (SPIR-V / GLSL source (compiled automatically))
2. **Your Configuration** (YAML format)

```yaml
# Example vkforge.yml
ID: VkForge 0.5

Pipeline: # Atleast one pipeline to generate pipeline code and layout code
  - name: MainPipeline
    ShaderModule: # layouts are automatically designed from shader combinations
      - path: shaders/main.vert 
      - path: shaders/main.frag
    VertexInputBindingDescription: # describe how vertex locations are binded to buffers
      - stride: sizeof(Vertex) # Can be Type, Sizeof or Integer
        first_location: 0
```

## Getting Started

1. Install VkForge:
```bash
pip install vkforge
```

2. Ensure glslangValidator is in your PATH (comes with Vulkan SDK)

3. Create your config file and run:
```bash
vkforge config.yml --source-dir src --build-dir build
```

4. Use the generated code:
```c
#include "vkforge_typedecls.h"
#include "vkforge_funcdecls.h"

void DrawCallback(VkForgeRender render) {
    VkForge_BindPipeline(render.userData, "MainPipeline", render.cmdbuf_draw);
    vkCmdDraw(render.cmdbuf_draw, 3, 1, 0, 0);
}
```

## Usage Patterns

VkForge is designed to be flexible:

- **Starter Template** - Generate all code once and modify manually
- **Pipeline Updates** - Regenerate only pipelines when shaders change
- **Partial Adoption** - Use only specific generated components
- **Convenience Components** - Provide automatic layout design and render management

```yaml
# Generate certain files just once
GenerateOnce:
- CMakeLists.txt
- vkforge_core.c
```

## Current Limitations

- Vulkan 1.3 with dynamic rendering only (renderpass support planned)
- SDL3 platform support (others planned)
- Basic feature set (see roadmap below)

## Roadmap

Help wanted on these features! Contribute via pull requests or ideas.

- Optimize Design layout to only store unique data globally
- Add support for push constants
- Add support for subpass inputs
- Add support for Renderpass (pre-1.3 Vulkan)
- Platform abstraction (Raylib, GLFW support)
- Alternative texture loading backends (stb_image)
- 3D utility functions
- Extended utility functions with pNext and pAllocator support ??
- Ensure VkForge support both Graphs and Compute GPU activities

## Community & Contribution

VkForge is **open source** and **MIT licensed**. We welcome all contributions!

- Try it out and report issues
- Help implement roadmap features
- Improve documentation
- Share with others who might find it useful

🔗 [GitHub Repository](https://github.com/Rickodesea/VkForge)  
📦 [PyPI Package](https://pypi.org/project/vkforge/)  
💬 [Discussions](https://github.com/Rickodesea/VkForge/discussions)  

## Why VkForge?

Vulkan is powerful but requires lots of boilerplate. VkForge helps by:
- Generating the repetitive code
- Providing useful components
- Providing convenient utility functions
- Keeping you in control of the Vulkan API
- Staying out of your way when you don't need it

**Small. Focused. Flexible.**  

(c) 2025 Alrick Grandison, Algodal