DOCSEARCHbyAlgolia
Submit Docs

Vulkano Documentation

repository·master·Indexed 26 days ago

https://github.com/vulkano-rs/vulkano

A type-safe Rust wrapper for the Vulkan graphics API designed to prevent invalid API usage through compile-time and runtime checks. Vulkano provides automatic GPU synchronization, transparent interoperability with GLSL and SPIR-V shaders, and a specialized ecosystem of crates including vulkano-shaders, vulkano-taskgraph, and vulkano-util.

Tokens
3.5K
Snippets
3
Records
14
Agent score
40%

What's inside Vulkano

  1. Overview of Vulkano

    master

    Vulkano is a Rust wrapper around the Vulkan graphics API. It is designed to provide a high-level, type-safe Rust API that prevents invalid Vulkan API usage through both compile-time and runtime checks.

    Key features include:

    • Safety: Aims to prevent undefined behavior in non-unsafe code by ensuring valid API usage.
    • Automatic Synchronization: Can automatically manage GPU-side synchronization, including dependency detection and semaphore management.
    • Shader Integration: Provides transparent interoperability with GLSL and SPIR-V shader code, including automatically generated types for shader layouts.
    • Low-level Control: Provides a 'low-levelish' API that offers comfort types without hiding the underlying Vulkan operations.

  2. Vulkano Ecosystem and Library Structure

    master

    The Vulkano project is composed of several specialized crates that work together:

    • vulkano: The core main library.
    • vulkano-shaders: Provides the shader! macro for compiling GLSL shaders.
    • vulkano-taskgraph: Enables building a dependency graph of tasks that are automatically synchronized and executed on the Vulkan device.
    • vulkano-util: Provides utility functions for common operations like device creation, swapchain creation, and managing render windows.

  3. Check Vulkano's Vulkan feature coverage

    master

    Vulkano provides varying levels of support for Vulkan core features and extensions. Use this coverage information to determine if your application's requirements (e.g., specific Vulkan versions or extensions) are met by the library.

    Support levels are categorized as:

    • Fully supported: The feature or extension is completely implemented.
    • Partially supported: Some aspects are implemented, but certain features or parameters may be missing.
    • Unsupported: The feature or extension is not implemented in Vulkano.

    As of the Vulkan 1.4.303 spec, coverage includes features from Vulkan 1.0, 1.1, 1.2, and 1.3.

  4. Setup Vulkano on Windows (Cross-compiling to GNU)

    master

    While the windows-gnu toolchain is not directly supported, you can cross-compile to it from windows-msvc.

    1. Download and extract: https://s3-us-west-1.amazonaws.com/rust-lang-ci2/rust-ci-mirror/x86_64-6.3.0-release-posix-seh-rt_v5-rev2.7z
    2. Add the absolute path to mingw64\bin to your PATH (ensure this is placed before the msys2 path).
    3. Set the default toolchain: rustup default stable-x86_64-pc-windows-msvc
    4. Install the target: rustup target install x86_64-pc-windows-gnu
    5. Install Build Tools for Visual Studio 2017.
    6. Install msys2.
    7. In the msys2 terminal, run: pacman --noconfirm -Syu mingw64/mingw-w64-x86_64-pkg-config mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-make mingw-w64-x86_64-python2 mingw-w64-x86_64-ninja
    8. Add the msys2 mingw64 binary path to your PATH.
    9. When building or running, include the target flag: cargo run --target x86_64-pc-windows-gnu.
    rustup default stable-x86_64-pc-windows-msvc
rustup target install x86_64-pc-windows-gnu
# In msys2 terminal:
pacman --noconfirm -Syu mingw64/mingw-w64-x86_64-pkg-config mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-make mingw-w64-x86_64-python2 mingw-w64-x86_64-ninja
# To run:
cargo run --target x86_64-pc-windows-gnu

  5. Setup Vulkano on macOS, iOS, and tvOS

    master

    Because Vulkan is not natively supported on Apple platforms, Vulkano uses MoltenVK (a Vulkan implementation on top of Metal).

    • macOS: The easiest method is to install the Vulkan SDK for macOS.
    • iOS and tvOS: Vulkano links directly to the MoltenVK framework. You only need to install the Vulkan SDK for macOS, which includes the necessary frameworks for iOS and tvOS.

  6. Get started with Vulkano

    master

    To begin using Vulkano, use the following resources:

    • Examples: Explore the examples folder in the repository for practical implementations.
    • API Documentation: Use docs.rs/vulkano for the full API reference.
    • Learning Guide: The guide at vulkano.rs provides a progression from simple compute examples to rendering triangles and Mandelbrots.
    • Community Support: Raise questions or report bugs via GitHub Issues.

  8. Setup Vulkano on Linux

    master

    Install required development tools and Vulkan drivers using your package manager.

    Ubuntu/Debian: sudo apt-get install build-essential git python cmake libvulkan-dev vulkan-tools

    Arch Linux: sudo pacman -Sy base-devel git python cmake vulkan-devel --noconfirm

    # Ubuntu
sudo apt-get install build-essential git python cmake libvulkan-dev vulkan-tools

# Arch
sudo pacman -Sy base-devel git python cmake vulkan-devel --noconfirm

  9. Setup Vulkano on Windows (MSVC toolchain)

    master

    To use the x86_64-pc-windows-msvc toolchain, follow these steps:

    1. Set the default toolchain: rustup default stable-x86_64-pc-windows-msvc
    2. Install Build Tools for Visual Studio 2017.
    3. Install msys2 following their official instructions.
    4. In the msys2 terminal, run the following command to install dependencies: pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-python2 mingw-w64-x86_64-ninja
    5. Add the msys2 mingw64 binary path to your PATH environment variable.
    rustup default stable-x86_64-pc-windows-msvc
# In msys2 terminal:
pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-python2 mingw-w64-x86_64-ninja

  10. Vulkano support for non-core extensions

    master
    Vulkano provides full support for several Vulkan extensions that have not yet been promoted to the core specification. This includes surface extensions for various platforms (Android, Wayland, Win32, XCB, Xlib, Metal, etc.), memory management extensions, and shader-related extensions. Some extensions are marked as 'promoted', meaning they are part of a newer core specification but may still be accessed via their extension names in some contexts.

  11. Vulkan 1.3 Extension Support Reference

    master

    This record lists the Vulkan 1.3 extensions supported by Vulkano. Extensions are categorized into those that are fully supported, partially supported, or unsupported. Use this to determine if specific hardware-accelerated features or vendor-specific extensions (NV, QCOM, VALVE, etc.) are available for your application.

    Fully Supported Extensions

    • VK_NV_memory_decompression
    • VK_NV_mesh_shader
    • VK_NV_optical_flow
    • VK_NV_per_stage_descriptor_set
    • VK_NV_present_barrier
    • VK_NV_ray_tracing (deprecated)
    • VK_NV_ray_tracing_invocation_reorder
    • VK_NV_ray_tracing_motion_blur
    • VK_NV_ray_tracing_validation
    • VK_NV_representative_fragment_test
    • VK_NV_sample_mask_override_coverage
    • VK_NV_scissor_exclusive
    • VK_NV_shader_atomic_float16_vector
    • VK_NV_shader_image_footprint
    • VK_NV_shader_sm_builtins
    • VK_NV_shader_subgroup_partitioned
    • VK_NV_shading_rate_image
    • VK_NV_viewport_array2
    • VK_NV_viewport_swizzle
    • VK_NV_win32_keyed_mutex (promoted)
    • VK_NVX_binary_import
    • VK_NVX_image_view_handle
    • VK_NVX_multiview_per_view_attributes
    • VK_QCOM_filter_cubic_clamp
    • VK_QCOM_filter_cubic_weights
    • VK_QCOM_fragment_density_map_offset
    • VK_QCOM_image_processing
    • VK_QCOM_image_processing2
    • VK_QCOM_multiview_per_view_render_areas
    • VK_QCOM_multiview_per_view_viewports
    • VK_QCOM_render_pass_shader_resolve
    • VK_QCOM_render_pass_store_ops
    • VK_QCOM_render_pass_transform
    • VK_QCOM_rotated_copy_commands
    • VK_QCOM_tile_properties
    • VK_QCOM_ycbcr_degamma
    • VK_QNX_external_memory_screen_buffer
    • VK_SEC_amigo_profiling
    • VK_VALVE_descriptor_set_host_mapping
    • VK_VALVE_mutable_descriptor_type (promoted)

  12. Vulkan 1.3 Extension Support Coverage

    master

    Vulkano provides varying levels of support for Vulkan 1.3 extensions. Use this reference to determine if specific features are available for your application.

    Fully Supported

    • VK_KHR_acceleration_structure: Host acceleration structure operations.
    • VK_KHR_external_memory_win32: Includes vkGetMemoryWin32HandleKHR, vkGetMemoryWin32HandlePropertiesKHR, and VkExportMemoryWin32HandleInfoKHR.
    • VK_KHR_external_semaphore_win32: Includes VkD3D12FenceSubmitInfoKHR.
    • VK_KHR_fragment_shading_rate.
    • VK_KHR_portability_subset (provisional): Check for tessellationIsolines and tessellationPointMode.
    • VK_KHR_ray_tracing_pipeline: Includes vkCmdSetRayTracingPipelineStackSizeKHR, vkGetRayTracingCaptureReplayShaderGroupHandlesKHR, and deferred host operations.
    • VK_KHR_ray_tracing_maintenance1: Includes vkCmdTraceRaysIndirect2KHR and VK_ACCESS_2_SHADER_BINDING_TABLE_READ_BIT_KHR.
    • VK_EXT_buffer_device_address (deprecated): Includes VkBufferDeviceAddressCreateInfoEXT.
    • VK_EXT_debug_utils: Includes vkSetDebugUtilsObjectTagEXT, vkSubmitDebugUtilsMessageEXT, VkDebugUtilsObjectNameInfoEXT (extending VkPipelineShaderStageCreateInfo), and VkDebugUtilsMessengerCallbackDataEXT (note: not all data is exposed to the callback).
    • VK_EXT_swapchain_maintenance1: Includes vkReleaseSwapchainImagesEXT / VkReleaseSwapchainImagesInfoEXT and VkSwapchainPresentFenceInfoEXT.