Overview

Himalaya is a real-time renderer built on Vulkan 1.4, designed as a layered system for learning and practicing modern graphics engineering. It currently implements a full rasterization pipeline with PBR shading, cascaded shadow maps, screen-space ambient occlusion, and an experimental path-tracing reference view — all orchestrated through a declarative render graph with automatic barrier insertion.

This page provides a high-level map of the project: what it is, how the code is organized, what rendering features are implemented, and where to go next depending on your interest.

Sources: CLAUDE.md, CMakeLists.txt

What Is Himalaya?

Himalaya is a personal, long-term rendering project targeting mid-range desktop GPUs. It is not a game engine — there is no scripting system, no entity-component architecture, no asset pipeline beyond loading glTF scenes. The entire focus is on the rendering pipeline itself: how geometry flows from disk to GPU, how passes communicate through resources, and how visual quality scales with increasingly sophisticated techniques.

The project follows a progressive enhancement philosophy: every rendering feature starts as the simplest working version and evolves through incremental upgrades. For example, shadows begin as a basic shadow map, then gain cascading (CSM), then PCF filtering, then PCSS contact-hardening soft shadows — each step building on the last without tearing down what came before.

Sources: requirements-and-philosophy.md

Architecture at a Glance

The codebase is organized as four strictly layered static libraries, compiled with a one-way dependency rule. Layer 0 never includes headers from Layer 1, Layer 1 never includes Layer 2, and Layer 2 passes never include each other. The application layer (Layer 3) sits on top, owning all subsystems and filling per-frame data.

The arrows represent compile-time #include dependencies, which flow strictly downward. Each layer only knows about the layer directly beneath it — passes never reference each other's headers, and the RHI contains zero rendering logic.

Sources: architecture.md, CLAUDE.md

Project Structure

The repository root contains four source directories (one per layer), a shaders/ directory of GLSL files, assets/ with sample glTF scenes and HDR environments, and a docs/ tree of design documentation:

The dependency chain is enforced at the CMake level: himalaya_rhi has no target dependencies, himalaya_framework links himalaya_rhi, himalaya_passes links himalaya_framework, and himalaya_app links all three.

Sources: CMakeLists.txt, CLAUDE.md

Implemented Rendering Features

The following table summarizes the rendering techniques currently in the codebase, organized by feature area. Each entry shows which layer owns the implementation and which shader stages are involved.

Sources: scene_data.h, bindings.glsl

Frame Lifecycle

Every frame follows the same lifecycle managed by the Application class. The loop decomposes into four phases: begin (GPU sync + swapchain acquire), update (camera, culling, UI), render (command buffer recording via render graph), and end (submit + present + resize handling).

Within the render() phase, the Renderer fills GPU uniform/storage buffers from the current frame's scene data, then rebuilds the render graph each frame: imported resources are declared, passes are registered with their resource dependencies, compile() computes image layout transitions, and execute() records commands with automatic barrier insertion.

Sources: application.cpp, renderer.h

Current Development Phase

Himalaya is currently in Milestone 1, Phase 6 — adding real-time ray tracing infrastructure and a path-traced reference view. The rasterization pipeline (depth prepass → shadow pass → GTAO → contact shadows → forward PBR → skybox → tonemapping) is feature-complete for M1. The ongoing RT work introduces:

• RHI-level acceleration structure abstraction (BLAS/TLAS creation, building, destruction)
• RT pipeline and shader binding table (raygen, closest-hit, miss, any-hit shaders)
• Scene AS builder (per-mesh-group BLAS, scene TLAS, Geometry Info SSBO)
• Path-tracing reference view with accumulation, OIDN viewport denoising, and importance sampling

The project uses 2 frames in flight with explicit init()/destroy() lifetime management — no RAII destructors for GPU resources. All Vulkan API calls are checked via the VK_CHECK macro, and validation layers are always enabled during development.

Sources: current-phase.md, context.h

Technical Foundation

The renderer is built on a consistent set of Vulkan conventions and design choices that permeate every layer:

Sources: CLAUDE.md, types.h

By the Numbers

Sources: descriptors.h, CLAUDE.md

Reading Guide

The documentation is organized into two sections. Get Started covers practical setup and conventions; Deep Dive explores each layer and subsystem in detail. The recommended reading order follows the catalog sequence:

Get Started

1. Quick Start — Build Environment and Dependencies — How to set up the build environment, install vcpkg dependencies, and compile the project
2. Coding Conventions and Naming Standards — Naming rules, namespace conventions, documentation format, and control flow standards
3. Project Structure and Layered Architecture — Detailed module breakdown, dependency rules, and how the four layers interact

Deep Dive

The deep dive follows the dependency order — start from the lowest abstraction layer and work upward:

• Layer 0 (RHI): GPU Context Lifecycle → Resource Management → Bindless Descriptors → Shader Compilation
• Layer 1 (Framework): Render Graph → Material System → Mesh Management → IBL → Scene Data Contract → Frustum Culling → Shadow Cascades
• Layer 2 (Passes): Depth Prepass → Forward Pass → Shadow Pass → GTAO → Contact Shadows → Skybox & Tonemapping
• Layer 3 (Application): Renderer Core → Scene Loader → Debug UI
• Shader System: GLSL Architecture → Path Tracing Shaders
• Design & Roadmap: Design Principles → Milestone Roadmap

If you are new to the project, start with Project Structure and Layered Architecture to understand how the four layers divide responsibility, then pick any deep-dive page that matches your area of interest.