Vulkan Debugging Guide

Overview

rendara provides first-class support for Vulkan debugging through its Vulkan layer. This guide covers everything from basic frame capture to advanced pipeline analysis.

Vulkan Layer Setup

rendara installs a Vulkan layer that intercepts API calls for capture and analysis. The layer is automatically registered during installation.

Verify Layer Installation

vulkaninfo | grep rendara
# VK_LAYER_RENDARA_capture

Manual Layer Configuration

If you need to manually enable the layer:

# Linux
export VK_INSTANCE_LAYERS=VK_LAYER_RENDARA_capture
export VK_LAYER_PATH=~/.rendara/layers

# Windows (PowerShell)
$env:VK_INSTANCE_LAYERS="VK_LAYER_RENDARA_capture"
$env:VK_LAYER_PATH="$HOME\.rendara\layers"

Capturing Frames

There are several ways to capture frames from Vulkan applications:

Method 1: Launch with rendara

rendara launch ./my-vulkan-app

Press F12 to capture a frame while the application runs.

Method 2: Capture Running App

rendara capture --pid $(pgrep my-vulkan-app)

Method 3: Programmatic Capture

Use the rendara API to trigger captures from code:

// Link against rendara-capture library
#include <rendara/capture.h>

// Trigger capture
rendara_capture_frame();

Pipeline State Inspection

rendara captures the complete Vulkan pipeline state at each draw call:

• Graphics Pipeline — Shader stages, vertex input, rasterization, blending
• Compute Pipeline — Compute shader, specialization constants
• Descriptor Sets — All bound resources, samplers, buffers
• Push Constants — Current push constant values
• Dynamic State — Viewports, scissors, blend constants

Resource Inspection

Buffers

View buffer contents as raw bytes, structured data, or interpreted vertex/index data:

rendara inspect buffer 0x1234 --format vertex --layout "vec3 pos, vec3 normal, vec2 uv"

Images

Inspect textures with full mip chain and array layer support:

• View individual mip levels
• Inspect array layers and cubemap faces
• Visualize depth/stencil as color
• Channel isolation (R, G, B, A)

Synchronization Analysis

Vulkan synchronization bugs are notoriously hard to debug. rendara helps by:

• Static Analysis — Detects missing or incorrect barriers
• Hazard Detection — Identifies read-after-write, write-after-write hazards
• Barrier Visualization — Shows pipeline stage dependencies

rendara analyze frame.rdc --sync-check

⚠ HAZARD: Write-after-read on VkImage 0x5678
  Write: vkCmdCopyBufferToImage (draw #45)
  Read: Fragment shader sample (draw #42)
  Missing: VK_PIPELINE_STAGE_TRANSFER_BIT → VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT

AI-Powered Analysis

Ask rendara questions about your Vulkan frame in natural language:

rendara ask "why is the shadow map empty?"
rendara ask "which draw call writes to the G-buffer normal attachment?"
rendara ask "what's causing the pipeline stall at draw 234?"

Common Vulkan Issues

Black Screen

• Check render pass attachments and clear values
• Verify viewport and scissor are set correctly
• Inspect vertex buffer binding and index buffer

Flickering

• Usually a synchronization issue — run --sync-check
• Check for missing barriers between frames
• Verify swapchain image transitions

Performance Issues

• Use AI analysis to find bottlenecks
• Check for redundant state changes
• Look for excessive barrier usage