Vulkan Graph Driver

vk-graph is a high-performance Vulkan driver for the Rust programming language featuring automated resource management and execution. It is blazingly-fast, built for real-world use, and supports modern Vulkan commands¹.

[dependencies]
vk-graph = "0.14"

Changelog

Overview

vk-graph supports desktop, mobile, and AR/VR platforms in headless, windowed, or full-screen modes. An accessory crate is provided for winit support:

use vk_graph_window::{Window, WindowError};

fn main() -> Result<(), WindowError> {
    Window::new()?.run(|frame| {
        // It's time to do some graphics! 😲
    })
}

Usage

vk-graph provides a fully-generic graph structure for statically typed access to resources used while rendering. The Graph structure allows Vulkan smart pointer resources to be bound as "nodes" which may be used by shader pipelines. The graph supports swapchain integration and may be used to execute custom command streams.

Features of the graph:

• Compute, graphic, and ray-trace pipelines
• Automatic Vulkan management (render passes, subpasses, descriptors, pools, etc.)
• Automatic render pass scheduling, re-ordering, merging, with resource aliasing
• Interoperable with existing Vulkan code
• Optional shader hot-reload from disk

Example code:

graph
    .begin_cmd()
    .debug_name("Fancy new algorithm for shading a moving character who is actively on fire")
    .bind_pipeline(&gfx_pipeline)
    .shader_resource_access(0, prev_image, AccessType::FragmentShaderReadColorInputAttachment)
    .shader_resource_access(1, some_image, AccessType::FragmentShaderReadOther)
    .shader_resource_access(3, fire_buffer, AccessType::FragmentShaderReadUniformBuffer)
    .color_attachment_image(0, swapchain_image, LoadOp::CLEAR_BLACK_ALPHA_ZERO, StoreOp::Store)
    .depth_stencil_attachment_image(depth_image, LoadOp::Load, StoreOp::DontCare)
    .record_cmd(move |cmd| {
        cmd
            .push_constants(some_u8_slice)
            .draw(6, 1, 0, 0);
    });

Optional features

vk-graph puts a lot of functionality behind optional features in order to optimize compile time for the most common use cases. The following features are available.

• loaded (enabled by default) — Support searching for the Vulkan loader manually at runtime.
• linked — Link the Vulkan loader at compile time.
• profile-with-* — Use the specified profiling backend: profile-with-puffin, profile-with-optick, profile-with-superluminal, or profile-with-tracy

Debug Logging

This crate uses log for low-overhead logging.

To enable logging, set the RUST_LOG environment variable to trace, debug, info, warn or error and initialize the logging provider of your choice. Examples use pretty_env_logger.

You may also filter messages, for example:

RUST_LOG=vk_graph::driver=trace,vk_graph=warn cargo run --example ray_trace

TRACE vk_graph::driver::instance > created a Vulkan instance
DEBUG vk_graph::driver::physical_device > physical device: NVIDIA GeForce RTX 3090
DEBUG vk_graph::driver::physical_device > extension "VK_KHR_16bit_storage" v1
DEBUG vk_graph::driver::physical_device > extension "VK_KHR_8bit_storage" v1
DEBUG vk_graph::driver::physical_device > extension "VK_KHR_acceleration_structure" v13
...

Performance Profiling

This crate uses profiling and supports multiple profiling providers. When not in use profiling has zero cost.

To enable profiling, compile with one of the profile-with-* features enabled and initialize the profiling provider of your choice.

Example code uses puffin:

cargo run --features profile-with-puffin --release --example vsm_omni

Quick Start

Included are some examples you might find helpful:

• hello_world.rs — Displays a window on the screen. Please start here.
• triangle.rs — Shaders and full setup of index/vertex buffers; < 100 LOC.
• shader-toy/ — Recreation of a two-pass shader toy using the original shader code.

See the example code, documentation, or helpful guide book for more information.

NOTE: Required development packages and libraries are listed in the guide. All new users should read and understand the guide.

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}

Footnotes

1. Modern Vulkan usage means no pixel queries. Anything else unsupported is due to there being better options, no current need, or no interest. Please open an issue. ↩