Crate phobos

Fast, powerful Vulkan abstraction library

Phobos provides powerful Vulkan abstractions to automatically manage common issues like synchronization and resource management. It hides away a lot of boilerplate that comes with Vulkan, while still being highly flexible.

To get started, the easiest way is to simply

// Import all important traits
use phobos::prelude::traits;
// Import types under a namespace.
use phobos::prelude as ph;

// Or, if you dont care about using the types under a namespace
use phobos::prelude::*;

Example

For illustrative purposes, we will use winit here. Any windowing library can be supported by implementing a few trait objects necessary to satisfy the WindowInterface trait.

use winit::window::WindowBuilder;
use winit::event_loop::EventLoopBuilder;
let event_loop = EventLoopBuilder::new().build();
let window = WindowBuilder::new()
    .with_title("Phobos test app")
    .build(&event_loop)
    .unwrap();

First, we will define an AppSettings structure that outlines requirements and information about our application. Phobos will use this to pick a suitable GPU to run your program on and initialize Vulkan for it.

use phobos::prelude::*;

let settings = AppBuilder::new()
        .version((1, 0, 0))
        .name("Phobos demo app")
        .validation(true)
        .window(&window)
        .present_mode(vk::PresentModeKHR::MAILBOX)
        .scratch_size(1 * 1024u64) // 1 KiB scratch memory per buffer type per frame
        .gpu(GPURequirements {
            dedicated: true,
            min_video_memory: 1 * 1024 * 1024 * 1024, // 1 GiB.
            min_dedicated_video_memory: 1 * 1024 * 1024 * 1024,
            queues: vec![
                QueueRequest { dedicated: false, queue_type: QueueType::Graphics },
                QueueRequest { dedicated: true, queue_type: QueueType::Transfer },
                QueueRequest { dedicated: true, queue_type: QueueType::Compute }
            ],
            ..Default::default()
        })
        .build();

Now we are ready to initialize the Phobos library.

use phobos::prelude::*;
let (
    instance,
    physical_device,
    surface,
    device,
    allocator,
    exec,
    frame,
    Some(debug_messenger)
) = WindowedContext::init(&settings)? else {
    panic!("Asked for debug messenger but didn't get one.")
};

For more initialization options, see initialize(), initialize_with_allocator() and WindowedContext::init_with_allocator().

For further example code, check out the following modules

• pipeline for pipeline creation and management.
• wsi for managing your main loop and frame rendering logic.
• graph for creating a pass graph to record commands.
• sync for various synchronization primitives, threading utilities, gpu futures and queue synchronization.
• descriptor for descriptor set management.
• command_buffer for different Vulkan commands available.
• allocator For various allocators and related utilities.
• [image] for managing VkImage and VkImageView objects.
• [buffer] for managing VkBuffer objects.
• util for various utilities and common patterns like buffer uploads.

Re-exports

pub use crate::prelude::*;

Modules

allocator

Contains useful memory allocator wrappers

command_buffer

Exposes command buffer wrappers for recording GPU commands.

core

The core module holds all functionality that is minimally required to initialize a Vulkan context.

descriptor

This module handles everything related to descriptor sets.

graph

The pass graph system is a powerful abstraction that allows you to automatically manage synchronization within a single queue, and automatically transition image layouts based on usage.

pipeline

Deals with wrappers for creating and managing Vulkan pipeline objects and their related objects.

prelude

Re-exports most commonly used types in the library

resource

Exposes common Vulkan resources such as buffers and images.

sync

Provides utilities dealing with Vulkan synchronization outside the scope of the pass graph.

util

Various utilities

wsi

Provides utilities for interacting with the window and rendering frames. If you are using a headless context, you can largely ignore this module.

Macros

buffer

Syntax sugar to easily construct buffer virtual resources

image

Syntax sugar to easily construct image virtual resources