Mastering WebGPU with C++

Welcome to the comprehensive guide for utilizing the WebGPU graphics API to develop native 3D applications from the ground up using C++. This documentation is designed for developers targeting Windows, Linux, and macOS.

[!IMPORTANT] Notice: This documentation is currently a work in progress!

---

🚀 Getting Started

Depending on your goals, there are several ways to navigate this material:

1. The Deep Dive: Read every chapter sequentially from the introduction. This is ideal if you want to understand every single line of GPU code you write.
2. The Fast Track: If you prefer readability over raw API calls, you can utilize a shallow wrapper.
3. The Result-Oriented Approach: Jump straight to the "Resulting code" links found at the top and bottom of each page.

🛠️ Technical Setup & Compilation

To compile the base code provided in this guide, please consult the Building section within the Project Setup chapter.

When configuring your build via CMake, you can specify your preferred backend using the following flags:

# To use wgpu-native (the default)
cmake -B build -DWEBGPU_BACKEND=WGPU

# To use Dawn
cmake -B build -DWEBGPU_BACKEND=DAWN

🗺️ Learning Path

The following diagram illustrates the progression of the course:

---

🚦 Documentation Status Legend

Because the WebGPU standard is still evolving, we use the following indicators to signal the current state of each chapter:

The "Next" section provides a preview of future updates, but it is not intended to be stable.

Note: To prevent version discrepancies, always use the specific version of the webgpu/ library provided with the code for that particular chapter.

---

📚 Course Curriculum

1. Fundamentals

• Introduction
• Getting Started $\rightarrow$ Project setup 🟢
• Hello WebGPU 🟢
  • The Adapter 🟢
  • The Device 🟢
  • The Command Queue 🟢
  • Opening a window 🟢
  • First Color 🟢
  • C++ wrapper 🟢

2. Basic 3D Rendering

• Hello Triangle 🟢
• Input Geometry
  • Buffer manipulation 🟢
  • Vertex Attributes (Single $\rightarrow$ Multiple) 🟢
  • Index Buffers 🟢
  • File Loading 🟢
• Shader Uniforms
  • Initial Uniforms 🟢
  • Advanced/Dynamic Uniforms 🟢

3. 3D Meshes & Interaction

• Mesh Basics $\rightarrow$ Simple examples 🟡
• The Pipeline
  • Depth Buffering 🟡
  • Transformation & Projection Matrices 🟡
  • Basic Shading 🟡
  • Loading Meshes from files 🟡
• Texturing
  • First Texture 🟡
  • Mapping & Samplers 🟡
  • Loading textures from files 🟡
• Refactoring & UI
  • Window Resizing 🟡
  • Camera Systems 🟡
  • Simple GUI & Lighting Controls 🟡🟢

4. Lighting & Materials

• Specularity 🟡
• Normal Mapping 🟡
• Upcoming Features:
  • Image-Based Lighting (🟠 WIP)
  • Cube Maps (🟠 WIP)
  • Physically-Based Materials (🟠 WIP)

5. Basic Compute

• Compute Pipeline 🟡
• Image Processing:
  • Mipmap Generation 🟡
  • Convolution Filters 🟡
  • Cubemap Conversion/Prefiltering (🟠 WIP)
• Other:
  • Procedural Geometry Deformation (🟠 WIP)

6. Advanced Techniques & Benchmarking

• RAII Implementation 🟡
• Screen Capture (🟠 WIP)
• Headless Context 🟡
• HDR Textures (🟠 WIP)
• Performance Metrics:
  • Timing 🟡
  • Memory/Processing/Environment (🔴 TODO)

7. Future Roadmap (The "TODO" List)

• Deferred Shading
• Render Bundles
• Multi-Sampling
• Scene Tree Architecture
• Shadow Mapping
• Tesselation
• Raytracing
• Neural Networks

---

📖 Appendices & Extras

• Pedagogy: Teaching native graphics in 2023 🟢
• Hardware: Optimizing for lower-end devices 🟢
• Web Deployment: Adapting examples for the browser 🟡
• Windowing: Using SDL for management 🟡
• Extensions:
  • The extension mechanism (🟠 WIP)
  • Integration with wgpu-native or Dawn (🟠 WIP)
• Debugging: (🟠 WIP)
• Memory Model: (🔴 TODO)

📐 Mathematical Note

When dealing with the projection matrices mentioned in the 3D Meshes section, we typically deal with transformations such as:

$$P = \begin{pmatrix} \frac{1}{tan(\frac{fov}{2}) \cdot aspect} & 0 & 0 & 0 \\ 0 & \frac{1}{tan(\frac{fov}{2})} & 0 & 0 \\ 0 & 0 & \frac{f+n}{n-f} & \frac{2fn}{n-f} \\ 0 & 0 & -1 & 0 \end{pmatrix}$$

Example of a 3D mesh viewer with basic interaction (Recommended starting point: Lighting Control chapter).