// 03 — pipeline deep dive

Engine Architecture

The HTML class is the single public interface the user sees. Internally it owns and orchestrates all subsystems through unique_ptr. No subsystem knows about the others — HTML coordinates them.

// engine Architecture

Frame Time Line

Every frame follows a fixed sequence. Input and logic run first, then rendering, then ImGui overlay, then physics step. The separation is explicit — no rendering during physics, no physics during rendering.

// frame execution order

Shadow Atlas

Instead of one shadow map per light (which requires N render passes and N textures), all shadow maps are packed into a single atlas texture. The stepLight loop distributes slots: directional light gets 1 slot, each point light needs 6 faces (cubemap), each spot light needs 1.

// shadow atlas - slot distribution

int numberOfLights = 1;                                       // Directional
numberOfLights += (int)pointLights.size() * 6;                // 6 faces per point light
numberOfLights += (int)spotLights.size();                     // 1 per spot light

int maxPerBatch = GetMaxNumberLightsShadowAtlas();

for (int i = 0; i < numberOfLights; i += maxPerBatch) {
  InitRenderProcess(frameInfo, i, dirPosReference);           // -> ShadowMap + GBuffer for this batch
  RenderObjects(frameInfo, i, dirPosReference);               // -> Lighting pass
  if (i + maxPerBatch < numberOfLights)
    vkWrapper_.EndOffScreenRenderPass(frameInfo);             // Close pass, start next batch
}

G-Buffer Layout

The Deferred pipeline writes geometry data to a set of render targets in a first pass, then the lighting pass reads from them. Separating geometry from lighting allows N lights at roughly the cost of 1 forward pass.

// G-Buffer Attachments - Deferred PBR

Culling System

Before any draw call, objects outside the camera frustum are skipped entirely. A bounding sphere is generated at model load time. Each frame, the sphere is tested against the 6 frustum planes. On Android, distance-based culling is used instead — simpler and cheaper on mobile GPUs.

// For each entity with a MeshComponent:
BoundingSphere sphere = mesh.boundingSphere;         // center + radius, generated at load

for (Plane plane : frustum.planes) {                 // 6 planes: near, far, left, right, top, bottom
  float dist = dot(plane.normal, sphere.center) + plane.d;
  if (dist < -sphere.radius) -> CULL (behind this plane)
}
-> VISIBLE: submit to draw call list

// Android fallback:
if (distance(camera.pos, sphere.center) > maxDistance) -> CULL

Image Barriers & Synchronization

Vulkan has no implicit synchronization — every image layout transition and pipeline stage dependency must be declared explicitly. The post-process chain requires a sequence of barriers to correctly hand off ownership between passes.

// After geometry pass: transition scene target to be readable by post-process shader
VkImageMemoryBarrier barrier{};
barrier.oldLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
barrier.newLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
barrier.srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT;   // waited until color writes finish
barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT;              // safe to read in fragment shader
vkCmdPipelineBarrier(cmd,
  VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT,                // source stage
  VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT,                        // destination stage
  ...);

// BlitTexture: transition post-process output -> scene target
// src: SHADER_READ_ONLY -> TRANSFER_SRC
// dst: SHADER_READ_ONLY -> TRANSFER_DST
// -> vkCmdBlitImage
// -> final barrier: TRANSFER_DST -> SHADER_READ_ONLY

Post-Process Chain

Each effect writes to its own output texture. viewbase and sampler are redirected after each effect, so the chain requires no intermediate copies — the output of one pass is the input of the next.

// MotionBlur reads velocity pass output
motionBlurSystem_->Apply(frameInfo.commandBuffer, viewbase, sampler,
  velTex->getImageView(), velTex->getSampler(), ...);
viewbase = mbOutput->getImageView();  // redirect for next pass

// DoF reads MB output + depth buffer
dofSystem_->Apply(frameInfo.commandBuffer, viewbase, sampler,
  vkWrapper_.GetOffScreenDepthView(), ...);
viewbase = dofOut->getImageView();

// Bloom reads DoF output
bloomSystem_->Apply(frameInfo.commandBuffer, viewbase, sampler, ...);

ECS Architecture

The engine is built around an ECS with a contiguous component storage + O(1) lookup map. A Job System handles async model and texture loading. The render layer is fully abstracted behind API-specific backends (Vulkan / Android / OpenGL / Web).

// Contiguous storage for cache-friendly iteration
std::vector<std::pair<size_t, T>> entityList_;

// O(1) lookup by entity ID
std::unordered_map<size_t, size_t> entityIdToIndexMap_;

// Usage: direct access without full scan
size_t index = entityIdToIndexMap_[entityID];
T* comp = &entityList_[index].second;

Plant Generator

case PlantGeneratorSystem::kStochasticTree:
  result = { 'X' };
  for (size_t i = 0; i < iterations; i++) {
    for (char node : result) {
      if (node == 'X') {
        int r = rand() % 100;
        if      (r < 40) AppendString(newVector, "FF[+X][-X]X");
        else if (r < 70) AppendString(newVector, "F[+X]F[-X]+X");
        else if (r < 90) AppendString(newVector, "F[\\X][/X]FX");
        else              AppendString(newVector, "FX");
      }
    }
  }
  break;

// 04 — challenges & solutions

Problems I Solved

// 05 — results

By The Numbers

Platforms

Vulkan · Desktop

Android · Mobile

// 06 — retrospective

What I Learned

• 01 Vulkan forces you to understand the GPU pipeline completely. Every memory barrier, image layout transition and synchronization point is explicit. When something breaks, you know exactly why — and RenderDoc makes the invisible visible.
• 02 Implementing Forward+, Deferred and PBR gave me a real understanding of modern rendering: how a G-Buffer is built, why decoupling geometry from lighting matters, and when each technique makes sense for a given scene. This is knowledge that's hard to get from using an engine that hides it.
• 03 The chained post-process pipeline taught me how render passes, image barriers and texture ownership work at the API level — directly applicable to writing custom post-process passes in UE5 or Unity.
• 04 L-Systems and WFC are real tools used in production PCG pipelines. Building them from scratch made their strengths and limitations concrete — when to use each, what parameters control the output, and how to expose them as artist-friendly controls.
• 05 Designing API-agnostic interfaces before implementing (Vulkan vs OpenGL in the same engine) is the same discipline as writing TA tools that work across different DCCs — abstract first, implement second.
• 06 Shadow Atlas distribution, frustum culling and ECS data layout are the three optimizations with the highest practical impact. All three are about memory access patterns — either on the GPU (atlas) or the CPU (cache locality).
• 07 RenderDoc as a debugging and inspection tool. Visualizing the G-Buffer passes in isolation was invaluable for diagnosing rendering issues.