Your First Triangle in Vulkan

01Why ~1000 lines

If you've drawn a triangle in OpenGL, it took far less code. OpenGL hid the instance, the device, the framebuffer, and the synchronization behind global state and the driver. Vulkan is explicit by design: you declare all of it. That's why a from-scratch colored triangle runs on the order of a thousand lines: a little over 900 in the original C-API Vulkan Tutorial^[1], about 1,000 (heavily commented) in Sascha Willems' Vulkan 1.3 triangle sample^[14]. The payoff is control over CPU-side submission and multi-threaded command recording, not a higher frame rate for one triangle.

Vulkan object lifetimes are the dependency order: an object has to exist before anything built from it, and has to outlive everything built from it. So the order you build in, reversed, is the teardown order.

The first widget is that dependency graph; come back to it as each object appears.

02Instance & validation

Vulkan does almost no error checking by default: pass a wrong value and you get a crash, a black screen or, worse, something that works on your GPU and breaks on someone else's. The fix is set up in the very first object you create. The VkInstance is your application's connection to Vulkan. You give it an app info (with the API version you target), the instance extensions (the surface extensions came from the Platform & Window tutorial), and the validation layer, a debug layer that checks every call against the spec and reports misuse.

VkApplicationInfo appInfo{ VK_STRUCTURE_TYPE_APPLICATION_INFO };
appInfo.apiVersion = VK_API_VERSION_1_3;                 // highest version targeted, not a feature switch

const char* layers[] = { "VK_LAYER_KHRONOS_validation" };   // debug builds only
// extensionNames = surface extensions from the platform layer + VK_EXT_debug_utils
VkInstanceCreateInfo createInfo{ VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO };
createInfo.pApplicationInfo = &appInfo;
createInfo.enabledLayerCount = 1; createInfo.ppEnabledLayerNames = layers;
createInfo.enabledExtensionCount = (uint32_t)extensionNames.size();
createInfo.ppEnabledExtensionNames = extensionNames.data();
VkResult result = vkCreateInstance(&createInfo, nullptr, &instance);
// VK_ERROR_LAYER_NOT_PRESENT: the validation layer isn't installed on this machine

// ash 0.38: ::default() + consuming setters (no more ::builder()).
let app_info = vk::ApplicationInfo::default()
    .api_version(vk::make_api_version(0, 1, 3, 0));         // targeted version
let layers = [c"VK_LAYER_KHRONOS_validation".as_ptr()];      // debug only
let create_info = vk::InstanceCreateInfo::default()
    .application_info(&app_info)
    .enabled_layer_names(&layers)
    .enabled_extension_names(&extension_names);                // surface exts + debug_utils
// Err(ERROR_LAYER_NOT_PRESENT): the validation layer isn't installed on this machine
let instance = unsafe { entry.create_instance(&create_info, None)? };

03Devices & queues

A laptop can have two GPUs, a weak integrated one and a fast discrete one, and your program has to pick one and say which of its queues it will use. Enumerate the physical devices (the GPUs the instance can see), score them, and pick one that supports the swapchain extension. Then find the queue families you need. A queue family is a group of the GPU's work queues with the same abilities. You need a graphics family (a capability bit) and a present family (a surface-specific query: can this family show images on this window?). Create the logical VkDevice, your handle to the chosen GPU with exactly the features and queues you enable, from one queue-create-info per unique family index.

// present support is a SEPARATE, surface-specific query:
VkBool32 presentSupport = VK_FALSE;
vkGetPhysicalDeviceSurfaceSupportKHR(physicalDevice, familyIndex, surface, &presentSupport);

std::set<uint32_t> uniqueFamilies = { graphicsFamily, presentFamily };  // dedupe: the same index twice is invalid
std::vector<VkDeviceQueueCreateInfo> queueInfos;
float queuePriority = 1.0f;
for (uint32_t family : uniqueFamilies)
    queueInfos.push_back({ VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO, nullptr, 0, family, 1, &queuePriority });

VkPhysicalDeviceVulkan13Features features13{ VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES };
features13.dynamicRendering = VK_TRUE;                   // enable the feature, not just check it
const char* deviceExtensions[] = { VK_KHR_SWAPCHAIN_EXTENSION_NAME };  // DEVICE extension
VkDeviceCreateInfo deviceInfo{ VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO, &features13 };   // feature struct rides on pNext
deviceInfo.queueCreateInfoCount = (uint32_t)queueInfos.size(); deviceInfo.pQueueCreateInfos = queueInfos.data();
deviceInfo.enabledExtensionCount = 1; deviceInfo.ppEnabledExtensionNames = deviceExtensions;
vkCreateDevice(physicalDevice, &deviceInfo, nullptr, &device);
vkGetDeviceQueue(device, graphicsFamily, 0, &graphicsQueue);
vkGetDeviceQueue(device, presentFamily, 0, &presentQueue);

let surface_loader = ash::khr::surface::Instance::new(&entry, &instance);
let present_support = unsafe {
    surface_loader.get_physical_device_surface_support(physical_device, family_index, surface)?
};

use std::collections::HashSet;
let unique_families: HashSet<u32> = [graphics_family, present_family].into_iter().collect();  // dedupe
let queue_priority = [1.0f32];
let queue_infos: Vec<_> = unique_families.iter().map(|&family| vk::DeviceQueueCreateInfo::default()
    .queue_family_index(family).queue_priorities(&queue_priority)).collect();

let mut features13 = vk::PhysicalDeviceVulkan13Features::default().dynamic_rendering(true);
let device_extensions = [ash::khr::swapchain::NAME.as_ptr()];   // DEVICE extension
let device_info = vk::DeviceCreateInfo::default()
    .queue_create_infos(&queue_infos)
    .enabled_extension_names(&device_extensions)
    .push_next(&mut features13);                          // feature struct rides on p_next
let device = unsafe { instance.create_device(physical_device, &device_info, None)? };
let graphics_queue = unsafe { device.get_device_queue(graphics_family, 0) };
let present_queue = unsafe { device.get_device_queue(present_family, 0) };

04The swapchain

The GPU can't draw straight onto the window: while the display shows one image, you need another to draw into. The swapchain (VK_KHR_swapchain) is that rotating set of presentable images, tied to the surface. You choose a surface format (prefer B8G8R8A8_SRGB with the sRGB color space, but enumerate vkGetPhysicalDeviceSurfaceFormatsKHR and fall back: the pair is not guaranteed), a present mode, an image count, and an extent (the images' size in pixels), then create one VkImageView per image to render into. An image view says how to read an image: which format, which mip levels, which layers.

05Shaders → SPIR-V

In OpenGL you hand the driver shader source text at runtime, and every vendor's driver compiles it with its own front end. Vulkan doesn't take GLSL (OpenGL's C-like shading language). It consumes SPIR-V bytecode, a binary intermediate format, which you precompile offline with glslc (from the SDK); HLSL and Slang are also valid SPIR-V sources^[7]. For the hardcoded triangle there's no vertex buffer at all: the vertex shader indexes a constant array with the built-in gl_VertexIndex, and the draw is vkCmdDraw(cmd, 3, 1, 0, 0).

// triangle.vert, compiled with: glslc triangle.vert -o triangle.vert.spv
#version 450
layout(location = 0) out vec3 fragColor;
vec2 positions[3] = vec2[](vec2(0.0, -0.5), vec2(0.5, 0.5), vec2(-0.5, 0.5));
vec3 colors[3]    = vec3[](vec3(1,0,0), vec3(0,1,0), vec3(0,0,1));
void main() {
    gl_Position = vec4(positions[gl_VertexIndex], 0.0, 1.0);  // gl_VertexIndex, not gl_VertexID
    fragColor = colors[gl_VertexIndex];
}

Read the .spv as uint32-aligned bytes (ash has ash::util::read_spv^[3]) and wrap it in a VkShaderModule. Note: Vulkan's clip space, the space gl_Position is written in, is Y-down with a 0..1 depth range, so a triangle that looks right in OpenGL renders upside down here. For the hardcoded triangle the positions are simply picked to look right, and the camera tutorial handles the projection properly.

06The graphics pipeline

Every draw needs the GPU to know which shaders run and how each fixed stage is set up, and Vulkan wants all of that decided and compiled before the frame starts. The VkPipeline is the concrete form of the "baked state object" from The GPU & the Graphics Pipeline: it freezes the shader stages, the fixed-function state (input assembly, rasterizer, multisample, depth/stencil, color blend: the stages you configure but don't program), and the pipeline layout into one object^[8].

07Dynamic rendering

Older Vulkan code makes you declare every image you'll draw into, and how, in two extra objects before you can draw at all. This page uses dynamic rendering (core in Vulkan 1.3), which removes those two objects, VkRenderPass and VkFramebuffer, entirely. At pipeline creation you chain a VkPipelineRenderingCreateInfo (with the color attachment format) into the pipeline's pNext and set renderPass = VK_NULL_HANDLE; at record time you bracket drawing with vkCmdBeginRendering / vkCmdEndRendering^[9].

// No render pass: declare the attachment format the pipeline renders to.
// The array needs a name: the builder borrows it until the pipeline is created.
let color_formats = [swapchain_format];                     // must match the view given to begin_rendering
let mut rendering = vk::PipelineRenderingCreateInfo::default()
    .color_attachment_formats(&color_formats);
let pipeline_info = vk::GraphicsPipelineCreateInfo::default()
    .stages(&stages)
    .vertex_input_state(&vertex_input)                  // empty: corners come from gl_VertexIndex
    .input_assembly_state(&input_assembly)
    .viewport_state(&viewport_state)                    // counts only; the rectangles are dynamic
    .rasterization_state(&rasterizer)
    .multisample_state(&multisample)
    .color_blend_state(&color_blend)
    .dynamic_state(&dynamic_state)                      // VIEWPORT + SCISSOR
    .layout(pipeline_layout)
    .push_next(&mut rendering);                         // render_pass stays VK_NULL_HANDLE
let pipeline = unsafe {
    device.create_graphics_pipelines(vk::PipelineCache::null(), &[pipeline_info], None)
}.map_err(|(_, error)| error)?[0];                   // Err carries any partial results too

08Command buffers

The GPU doesn't run your API calls as you make them. You write the frame's commands into a list on the CPU and hand the whole list over. That list is a command buffer, and a VkCommandPool (created for the graphics queue family) is the allocator it comes from. Each frame you record: transition the image to color-attachment, vkCmdBeginRendering, bind the pipeline, set the dynamic viewport and scissor, vkCmdDraw(3, 1, 0, 0), vkCmdEndRendering, transition to present.

09The render loop & sync

The CPU and GPU run at the same time, and without coordination the CPU will overwrite a command buffer the GPU is still reading, or the GPU will draw into an image the display is still showing. Per frame: wait the in-flight fence, acquire the next swapchain image, reset the fence, record, submit, present. (The loop below is shown in Rust/ash; the C++ is the identical vk* calls in the same order.) The synchronization is where most first renderers go wrong, so be precise about the two primitives^[4]:

• Semaphores order GPU work, queue to queue: one operation signals, a later one waits. A binary semaphore is not waited on by the CPU.
• Fences are the CPU-GPU sync: the CPU calls vkWaitForFences to know the GPU finished.

Frames in flight change how the CPU's and GPU's times combine into the frame time:

In words: with one frame in flight the CPU waits for the GPU to finish before it records the next frame, so the two take turns and their times add. With two, the CPU records the next frame while the GPU draws this one, so the slower of the two sets the pace. Hover any term to see what it stands for.

// in_flight_fence, image_available, render_finished, cmd: this frame-in-flight's copies
unsafe {
    device.wait_for_fences(&[in_flight_fence], true, u64::MAX)?;   // CPU waits the FENCE

    let image_index = match swapchain_loader
        .acquire_next_image(swapchain, u64::MAX, image_available, vk::Fence::null())
    {
        Ok((index, _suboptimal)) => index,                  // suboptimal still presents; handled below
        Err(vk::Result::ERROR_OUT_OF_DATE_KHR) => {
            recreate_swapchain()?;                          // fence untouched, so the next wait returns at once
            return Ok(());
        }
        Err(error) => return Err(error),
    };
    // Reset only once a submit is certain: resetting before that early return
    // would leave the fence unsignaled and deadlock the next frame's wait.
    device.reset_fences(&[in_flight_fence])?;
    // ... record cmd: barrier→begin_rendering→bind→draw(3,1,0,0)→end_rendering→barrier ...

    // Named arrays: the builders borrow them until the call that consumes the struct.
    let wait_semaphores = [image_available];
    let wait_stages = [vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT];   // only the color write waits
    let command_buffers = [cmd];
    let signal_semaphores = [render_finished];
    let submit = vk::SubmitInfo::default()
        .wait_semaphores(&wait_semaphores)                     // GPU waits the SEMAPHORE
        .wait_dst_stage_mask(&wait_stages)
        .command_buffers(&command_buffers)
        .signal_semaphores(&signal_semaphores);
    device.queue_submit(graphics_queue, &[submit], in_flight_fence)?;   // fence signaled when the GPU is done

    let swapchains = [swapchain];
    let image_indices = [image_index];
    let present = vk::PresentInfoKHR::default()
        .wait_semaphores(&signal_semaphores)                   // present waits render-finished
        .swapchains(&swapchains)
        .image_indices(&image_indices);
    let stale = match swapchain_loader.queue_present(present_queue, &present) {
        Ok(suboptimal) => suboptimal,
        Err(vk::Result::ERROR_OUT_OF_DATE_KHR) => true,
        Err(error) => return Err(error),
    };
    if stale || framebuffer_resized { recreate_swapchain()?; }   // §10
}

The widget animates the CPU and GPU lanes across seven frames:

Wrong answers, and why: the CPU can only wait on a fence (not a binary semaphore or a barrier); and a missing present mode is a capability you must query, not a VRAM or validation issue.

10Resize & shutdown

The player drags the window to a new size, and the swapchain's images are now the wrong size for it. The swapchain has gone stale, and the acquire/present calls report it: VK_ERROR_OUT_OF_DATE_KHR means you must recreate; VK_SUBOPTIMAL_KHR still presents but should be recreated soon^[11].

11Pitfalls

12What's next

There's a triangle on screen, and the entire scaffold (instance, device, swapchain, pipeline, sync) is reusable. Next, Textures, Samplers & Materials adds images, samplers, and descriptor sets so the triangle can be textured, then the 2D Renderer turns this into a sprite batcher for the 2D-game capstone. The full path is on the series hub.

1. Khronos. Vulkan Tutorial, adapted from Alexander Overvoorde's original. docs.vulkan.org/tutorial; original at vulkan-tutorial.com. Validation layers, physical-device/queue-family selection, and the explicit-API model; the original C-API version reaches its first triangle after "a little over 900 lines of code".
2. Victor Blanco. Vulkan Guide. vkguide.dev. Vulkan 1.3 with dynamic rendering, structured for an engine; logical-device feature enablement.
3. ash (Rust). docs.rs/ash and the README. Version 0.38: ::default() + consuming setters, push_next, ash::khr/ash::ext loader modules.
4. The Khronos Group. Vulkan Specification, "Synchronization and Cache Control." docs.vulkan.org. Semaphores order GPU queue work (not CPU-waited); fences are the device-to-host sync.
5. The Khronos Group. Vulkan Specification, WSI / VkSurfaceCapabilitiesKHR. docs.vulkan.org. The currentExtent == 0xFFFFFFFF sentinel and the min/max extent clamp.
6. The Khronos Group. Vulkan Specification, VkPresentModeKHR. docs.vulkan.org. FIFO is the only present mode required to be supported; MAILBOX/IMMEDIATE are optional.
7. Khronos. Vulkan Tutorial, "Shader modules." docs.vulkan.org. Vulkan consumes SPIR-V bytecode (via glslc), not GLSL source; the hardcoded-triangle shader and gl_VertexIndex.
8. Khronos. Vulkan Tutorial, "Fixed functions." docs.vulkan.org. The baked pipeline state and dynamic viewport/scissor so resize needn't recreate it.
9. Lesley Lai. "Vulkan dynamic rendering." lesleylai.info. VkPipelineRenderingCreateInfo wiring and the manual image-layout barriers dynamic rendering requires.
10. Khronos. Vulkan Tutorial, "Frames in flight." docs.vulkan.org. Per-frame command buffers and sync objects; frames in flight is not the swapchain image count.
11. Khronos. Vulkan Tutorial, "Swap chain recreation." docs.vulkan.org. OUT_OF_DATE vs SUBOPTIMAL, the resize flag, and the minimize (0,0) case.
12. Charles Giessen / LunarG. vk-bootstrap. github.com/charles-lunarg/vk-bootstrap. Instance, device, queue, and swapchain setup; the README's example shows "500 lines slimmed down to about 50".
13. AMD GPUOpen. Vulkan Memory Allocator. gpuopen.com. A widely used sub-allocator that replaces hand-rolled vkAllocateMemory calls.
14. Sascha Willems. Vulkan C++ examples. github.com/SaschaWillems/Vulkan. A large Vulkan example corpus; its trianglevulkan13 sample is a single-file, heavily commented Vulkan 1.3 dynamic-rendering triangle of about 1,000 lines.
15. gfx-rs. wgpu. wgpu.rs. A safe, portable Rust graphics API implementing WebGPU on top of Vulkan, Metal, D3D12, and OpenGL.