Cauldron

A simple framework for rapid prototyping on Vulkan or DirectX12.

Cauldron was developed by AMD and is used internally to develop prototypes, demos and SDK samples.

Cauldron is compiled as a static library. To see it in action check projects below.

Projects that feature Cauldron

• FidelityFX-SPD Single Pass Downsampler (SPD)
• FidelityFX-SSSR Stochastic Screen Space Reflections (SSSR)
• FidelityFX-LPM Luma Preserving Mapper (LPM)
• FidelityFX-CACAO Combined Adaptive Compute Ambient Occlusion (CACAO)
• FidelityFX-VariableShading Variable Rate Shading (VRS)
• FidelityFX-ParallelSort GPU-based optimised sorting
• TressFX, a library that simulates and renders realistic hair and fur
• GLTFSample, a simple demo app to show off Cauldron's features

Cauldron Features

• glTF 2.0 File loader
  • Animation for cameras, objects, skeletons and lights
  • Skinning
    • Baking skinning into buffers (DX12 only)
  • PBR Materials
    • Metallic-Roughness
    • Specular-Glossiness (KHR_materials_pbrSpecularGlossiness)
  • Lighting
    • KHR_lights_punctual extension
      • Point
      • Directional
      • Spot Lights w/ Shadows (up to 4)
    • Image-based Lighting (IBL) CubeMaps
  • Shadow techniques
    • shadow maps (PCF)
    • shadow masks (DX12 only)
• Configurable GBuffer, supported techniques:
  • Full forward
  • Motion vectors
  • Normals
  • Depth
  • Specular-roughness
  • Diffuse-alpha
• Postprocessing
  • TAA
  • Bloom
  • HDR/Tonemapping
• Texture Loaders for DDS (including the BCn formats), JPEG and PNG formats
  • MIP Map generation for powers-of-two textures
• In-app user interface using Dear ImGui
• Rendering Resource Management
  • Command Buffer Ring
  • Timestamp Queries
  • Memory Heap Manager (Linear Allocator)
  • Static buffers for VB/IB/CB with suballocation support
  • Dynamic buffers for VB/IB/CB using a ring buffer
• Debug Rendering
  • Wireframe Bounding Boxes
  • Light Frustums
• Window management & swapchain creation
  • Fullscreen/Windowed Modes
• Support for DXC/SM6.x
• Shader Binary & PSO caching
• FreeSync ™️ 2 HDR support
• Multithreading loading & creation of resources
  • Textures & MIP map generation
  • Shader compilation
  • Pipeline creation
• VK extensions can be enabled from the app side
• Benchmarking

Directory Structure

• build : Build scripts & generated solution files/folders
• libs : Libraries
  • AGS : AMD helper library for querying GPU info
  • VulkanMemoryAllocator : Helper library for memory management with Vulkan applications
  • d3d12x : The D3D12 helper library
  • dxc : DirectX Shader Compiler
  • imgui : Graphical User Interface library
  • json : Library for adding JSON support w/ C++ syntax
• media : Builtin textures and other data
• src : Source code files
  • common : Common code used by both DX12/VK
  • DX12 : DirectX12 backend
  • VK : Vulkan backend

Note: more info on the rendering backends can be found in the Readme of their respective folders.

Build

Windows Prerequisites

• CMake 3.16
• Visual Studio 2017
• Windows 10 SDK 10.0.18362.0
• Vulkan SDK 1.2.131.2

Linux Prerequisites

• CMake 3.4
• GLM
• GCC 8.0 or higher
• Vulkan SDK 1.1.106

How-to-Build

• Linux (Vulkan Only) run cmake .. -DGFX_API=VK in the build directory
• Run the GenerateSolutions.bat file in the build directory.
• build/VK and build/DX12 folders will contain the Framework_*.sln files
• Simply build the solution file for the desired API
• build/DX12/src/DX12/ directory will contain the compiled static library Framework_DX12.lib for DX12 (similar for VK) under the selected configuration (Debug/Release) folder.

Framework Architecture

Every feature in Cauldron has been implemented in a single file using C++11.

The main features could be grouped in 4 categories:

• Resource managers & loaders
  • Texture loaders - can load DDS, PNG, JPG and any other file supported by the WIC subsystem. It can also create image views.
  • StaticBufferPool - holds vertices and indices for static geometry. It creates a huge buffer and then suballocates chunks from it in a linear fashion. Chunks cannot be freed.
  • DynamicBufferRing - holds constant buffers and also vertices and indices. Same as before but allocation happens in a ring fashion.
  • ResourceViewHeaps - holds the Descriptor Sets.
  • UploadHeap - system memory buffer that holds the texture data to be uploaded to video memory via DMA
  • CommandListRing - allocates a number of command buffers from a ring buffer and returns a ready-to-use command buffer.
  • Device - all the device related code.
• Renderers
  • GLTF* - loads and renders the model using a certain technique
  • PostProcPS/PS - draws a 2D quad using a custom shader, used by the post processing passes.
  • ImGUI - code for driving the ImGUI
  • Widgets
    • Wireframe - draws a wireframe cube (used for rendering bounding boxes and light/camera frustums)
    • Axis - draws the coordinate axis of a matrix
• Vulkan specific helpers & setup code
  • InstanceVK - creates an instance and enables the validation layer
  • Extension helpers
    • ExtDebugMarkers - sets up the debug markers
    • ExtFp16 - enables FP16 extension
    • ExtFreeSync2 - enables FreeSync extension
    • ExtValidation - enables the validation layer
• Commons & OS-specific code
  • Swapchain - handles resizing, fullscreen/windowed modes, etc.
  • FrameworkWindows - creates a window, processes windows message pump

Cauldron was originally written using DX12 and later on ported to Vulkan using the same structure. This would make Cauldron ideal for learning Vulkan if you're coming from DirectX12, or vice versa.

Known Issues

Please bear in mind that in order to keep Cauldron simple we are only covering the most frequently used features (for now).

Please feel free to open an issue for bug reports.

Contribution

Cauldron should be very easy to extend, should you want to contribute to Cauldron, you can open a merge request.

3rd-Party Open Source Projects Used

• ImGUI
• JSON for Modern C++
• AMD GPU Services (AGS) SDK
• Vulkan Memory Allocator
• DirectX Shader Compiler
• D3DX12
• stb_image