# nvlabs/nvdiffrast architecture

> Architecture diagram of the GitHub repository nvlabs/nvdiffrast, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvlabs/nvdiffrast
- Repository: https://github.com/nvlabs/nvdiffrast

## Overview

1. **What this repo is**
   - `nvdiffrast` is a **PyTorch extension library** for **high-performance differentiable rendering**.
   - Its core purpose is to expose a small set of GPU-accelerated primitives for rasterization-based rendering workflows.

2. **Top-level architecture**
   - The repo is split into:
     - **Python package layer**: `nvdiffrast/`
     - **Torch binding layer**: `csrc/torch/`
     - **Shared native rendering core**: `csrc/common/`
     - **Examples and documentation**: `samples/`, `docs/`
   - The Python side is thin; most heavy lifting happens in compiled C++/CUDA code.

3. **Public Python API boundary**
   - The package entry point is `nvdiffrast/torch/ops.py` and `nvdiffrast/torch/__init__.py`.
   - This layer presents the operations used by training code, while hiding the native extension details.
   - The library is specifically positioned as a **PyTorch-first API**, so the main consumer is model code that wants differentiable rendering in a deep learning loop.

4. **Torch binding layer**
   - `csrc/torch/torch_bindings.cpp` and related files connect Python/Torch calls to native implementations.
   - Separate binding translation units exist for the main ops:
     - `torch_rasterize.cpp`
     - `torch_interpolate.cpp`
     - `torch_texture.cpp`
     - `torch_antialias.cpp`
   - This indicates a modular op-by-op extension design rather than one monolithic kernel interface.

5. **Core rendering primitives**
   - The compiled backend in `csrc/common/` implements the actual rendering primitives:
     - rasterization: `rasterize.cu`
     - interpolation: `interpolate.cu`
     - texture sampling: `texture.cpp`, `texture_kernel.cu`
     - antialiasing: `antialias.cu`
   - These are the computational kernels that the Torch bindings expose to Python.
   - The primitives are designed to be combined into a rendering pipeline rather than a full engine.

6. **CUDA rasterization subsystem**
   - `csrc/common/cudaraster/` contains a dedicated rasterization implementation with its own internal structure:
     - raster implementation logic in `impl/`
     - kernel code in `RasterImpl_kernel.cu`
     - setup, coarse/fine/bin raster stages, buffer management, and utility helpers
   - This is the main low-level GPU rasterizer backend and likely the most performance-critical subsystem in the repo.

7. **Data flow through the system**
   - Typical flow is:
     - Python/Torch code calls a high-level op
     - Torch binding marshals tensors and parameters into native code
     - CUDA/C++ core rasterizes geometry and computes auxiliary data
     - downstream ops interpolate attributes, sample textures, and optionally antialias
     - results are returned as Torch tensors for autograd-based training
   - The architecture is centered on **tensor in / tensor out** GPU computation.

8. **Differentiability boundary**
   - Because the repo is for differentiable rendering, the important boundary is not just rendering, but **rendering with gradients**.
   - The native ops are packaged as PyTorch extension operations so they can participate in training workflows.
   - The repo therefore sits between classic graphics rasterization and ML autograd infrastructure.

9. **Build and packaging**
   - `setup.py`, `pyproject.toml`, and `MANIFEST.in` define packaging and extension build integration.
   - `Dockerfile` suggests a reproducible environment for CUDA/PyTorch builds.
   - The build is native-extension oriented, meaning deployment depends on compiling the C++/CUDA code against the local PyTorch/CUDA toolchain.

10. **Examples and validation**
    - `samples/torch/` provides runnable example pipelines:
      - `triangle.py`
      - `pose.py`
      - `cube.py`
      - `earth.py`
      - `envphong.py`
    - These are important as architectural references because they show how the primitives are composed in actual rendering tasks.
    - `samples/data/` holds the assets used by the demos.

11. **Documentation and external interface**
    - `docs/index.html` and `docs/img/` provide the user-facing documentation site and visuals.
    - The README positions the library as a research-grade NVIDIA release and points to external docs for detailed API usage.

12. **Key architectural takeaway**
    - The repo is a **layered GPU extension**:
      - **Python/Torch API** on top
      - **Torch C++ bindings** in the middle
      - **CUDA/C++ rendering kernels** at the bottom
    - The system is not a full renderer application; it is a **modular primitive library** meant to be embedded inside larger PyTorch-based differentiable rendering systems.

Main entry points: [`csrc/torch/torch_bindings.cpp`](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_bindings.cpp) (Main bindings), [`csrc/common/common.cpp`](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/common.cpp) (Common core), [`nvdiffrast/torch/ops.py`](https://github.com/nvlabs/nvdiffrast/blob/main/nvdiffrast/torch/ops.py) (Torch API), [`setup.py`](https://github.com/nvlabs/nvdiffrast/blob/main/setup.py) (Build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_python["Python API"]
  node_n_pkg_root["nvdiffrast<br/>python package<br/>[__init__.py]"]
  node_n_torch_api["Torch API<br/>python API<br/>[ops.py]"]
  node_n_torch_init["Torch init<br/>python init<br/>[__init__.py]"]
end

subgraph group_g_bindings["Torch bindings"]
  node_n_bindings["Main bindings<br/>C++ bridge<br/>[torch_bindings.cpp]"]
  node_n_bind_raster["Raster bind<br/>C++ binding"]
  node_n_bind_interp["Interp bind<br/>C++ binding"]
  node_n_bind_texture["Texture bind<br/>C++ binding<br/>[torch_texture.cpp]"]
  node_n_bind_aa["AA bind<br/>C++ binding"]
end

subgraph group_g_core["Native core"]
  node_n_common["Common core<br/>native core<br/>[common.cpp]"]
  node_n_rasterize["Rasterize<br/>GPU kernel<br/>[rasterize.cu]"]
  node_n_interpolate["Interpolate<br/>GPU kernel<br/>[interpolate.cu]"]
  node_n_texture["Texture<br/>sampling core<br/>[texture.cpp]"]
  node_n_texture_k["Texture kernel<br/>GPU kernel<br/>[texture_kernel.cu]"]
  node_n_antialias["Antialias<br/>GPU kernel<br/>[antialias.cu]"]
  node_n_cudaraster["CUDA raster<br/>raster backend<br/>[CudaRaster.hpp]"]
  node_n_raster_impl["Raster impl<br/>raster engine<br/>[RasterImpl.cpp]"]
  node_n_raster_kernel["Raster kernel<br/>GPU kernel"]
end

subgraph group_g_surface["Surface area"]
  node_n_samples["Samples<br/>examples<br/>[triangle.py]"]
  node_n_docs["Docs<br/>documentation<br/>[index.html]"]
  node_n_build["Build<br/>packaging<br/>[setup.py]"]
end

node_n_pkg_root -->|"exposes"| node_n_torch_api
node_n_torch_init -->|"exports"| node_n_torch_api
node_n_torch_api -->|"calls"| node_n_bindings
node_n_bindings -->|"routes"| node_n_bind_raster
node_n_bindings -->|"routes"| node_n_bind_interp
node_n_bindings -->|"routes"| node_n_bind_texture
node_n_bindings -->|"routes"| node_n_bind_aa
node_n_bind_raster -->|"invokes"| node_n_rasterize
node_n_bind_interp -->|"invokes"| node_n_interpolate
node_n_bind_texture -->|"invokes"| node_n_texture
node_n_bind_aa -->|"invokes"| node_n_antialias
node_n_common -->|"supports"| node_n_rasterize
node_n_common -->|"supports"| node_n_interpolate
node_n_common -->|"supports"| node_n_texture
node_n_common -->|"supports"| node_n_antialias
node_n_texture -->|"uses"| node_n_texture_k
node_n_cudaraster -->|"contains"| node_n_raster_impl
node_n_raster_impl -->|"drives"| node_n_raster_kernel
node_n_samples -->|"demonstrates"| node_n_torch_api
node_n_docs -->|"documents"| node_n_torch_api
node_n_build -->|"builds"| node_n_bindings
node_n_build -->|"builds"| node_n_common
node_n_build -->|"builds"| node_n_cudaraster

click node_n_pkg_root "https://github.com/nvlabs/nvdiffrast/blob/main/nvdiffrast/__init__.py"
click node_n_torch_api "https://github.com/nvlabs/nvdiffrast/blob/main/nvdiffrast/torch/ops.py"
click node_n_torch_init "https://github.com/nvlabs/nvdiffrast/blob/main/nvdiffrast/torch/__init__.py"
click node_n_bindings "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_bindings.cpp"
click node_n_bind_raster "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_rasterize.cpp"
click node_n_bind_interp "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_interpolate.cpp"
click node_n_bind_texture "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_texture.cpp"
click node_n_bind_aa "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_antialias.cpp"
click node_n_common "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/common.cpp"
click node_n_rasterize "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/rasterize.cu"
click node_n_interpolate "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/interpolate.cu"
click node_n_texture "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/texture.cpp"
click node_n_texture_k "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/texture_kernel.cu"
click node_n_antialias "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/antialias.cu"
click node_n_cudaraster "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/cudaraster/CudaRaster.hpp"
click node_n_raster_impl "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/cudaraster/impl/RasterImpl.cpp"
click node_n_raster_kernel "https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/cudaraster/impl/RasterImpl_kernel.cu"
click node_n_samples "https://github.com/nvlabs/nvdiffrast/blob/main/samples/torch/triangle.py"
click node_n_docs "https://github.com/nvlabs/nvdiffrast/blob/main/docs/index.html"
click node_n_build "https://github.com/nvlabs/nvdiffrast/blob/main/setup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_pkg_root,node_n_torch_api,node_n_torch_init toneBlue
class node_n_bindings,node_n_bind_raster,node_n_bind_interp,node_n_bind_texture,node_n_bind_aa toneAmber
class node_n_common,node_n_rasterize,node_n_interpolate,node_n_texture,node_n_texture_k,node_n_antialias,node_n_cudaraster,node_n_raster_impl,node_n_raster_kernel toneMint
class node_n_samples,node_n_docs,node_n_build toneRose
```

## Components

### Python API

Public PyTorch-facing package layer.

- [nvdiffrast](https://github.com/nvlabs/nvdiffrast/blob/main/nvdiffrast/__init__.py): python package · Top-level package entry point. · `nvdiffrast/__init__.py`
- [Torch API](https://github.com/nvlabs/nvdiffrast/blob/main/nvdiffrast/torch/ops.py): python API · Public PyTorch-facing operations. · `nvdiffrast/torch/ops.py`
- [Torch init](https://github.com/nvlabs/nvdiffrast/blob/main/nvdiffrast/torch/__init__.py): python init · Package export surface for torch integration. · `nvdiffrast/torch/__init__.py`

### Torch bindings

C++ bridge between Python and native ops.

- [Main bindings](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_bindings.cpp): C++ bridge · Entry point that registers native ops with PyTorch. · `csrc/torch/torch_bindings.cpp`
- [Raster bind](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_rasterize.cpp): C++ binding · Torch wrapper for rasterization. · `csrc/torch/torch_rasterize.cpp`
- [Interp bind](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_interpolate.cpp): C++ binding · Torch wrapper for interpolation. · `csrc/torch/torch_interpolate.cpp`
- [Texture bind](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_texture.cpp): C++ binding · Torch wrapper for texture sampling. · `csrc/torch/torch_texture.cpp`
- [AA bind](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/torch/torch_antialias.cpp): C++ binding · Torch wrapper for antialiasing. · `csrc/torch/torch_antialias.cpp`

### Native core

GPU rendering primitives and rasterizer backend.

- [Common core](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/common.cpp): native core · Shared native helpers and glue code. · `csrc/common/common.cpp`
- [Rasterize](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/rasterize.cu): GPU kernel · Geometry rasterization primitive. · `csrc/common/rasterize.cu`
- [Interpolate](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/interpolate.cu): GPU kernel · Attribute interpolation primitive. · `csrc/common/interpolate.cu`
- [Texture](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/texture.cpp): sampling core · Texture sampling implementation. · `csrc/common/texture.cpp`
- [Texture kernel](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/texture_kernel.cu): GPU kernel · Low-level texture sampling kernel. · `csrc/common/texture_kernel.cu`
- [Antialias](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/antialias.cu): GPU kernel · Edge smoothing and cleanup primitive. · `csrc/common/antialias.cu`
- [CUDA raster](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/cudaraster/CudaRaster.hpp): raster backend · Dedicated low-level rasterization subsystem. · `csrc/common/cudaraster/CudaRaster.hpp`
- [Raster impl](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/cudaraster/impl/RasterImpl.cpp): raster engine · Internal raster pipeline and orchestration. · `csrc/common/cudaraster/impl/RasterImpl.cpp`
- [Raster kernel](https://github.com/nvlabs/nvdiffrast/blob/main/csrc/common/cudaraster/impl/RasterImpl_kernel.cu): GPU kernel · Core rasterizer kernel implementation. · `csrc/common/cudaraster/impl/RasterImpl_kernel.cu`

### Surface area

Examples, docs, and packaging/build entry points.

- [Samples](https://github.com/nvlabs/nvdiffrast/blob/main/samples/torch/triangle.py): examples · Runnable PyTorch rendering demos. · `samples/torch/triangle.py`
- [Docs](https://github.com/nvlabs/nvdiffrast/blob/main/docs/index.html): documentation · User-facing documentation site and assets. · `docs/index.html`
- [Build](https://github.com/nvlabs/nvdiffrast/blob/main/setup.py): packaging · Native extension build and packaging setup. · `setup.py`

## Connections

- nvdiffrast → Torch API: exposes · Package surface routes users to torch ops.
- Torch init → Torch API: exports · Initialization layer re-exports public ops.
- Torch API → Main bindings: calls · Python API dispatches into registered extension ops.
- Main bindings → Raster bind: routes · Main registration layer forwards raster op calls.
- Main bindings → Interp bind: routes · Main registration layer forwards interpolation op calls.
- Main bindings → Texture bind: routes · Main registration layer forwards texture op calls.
- Main bindings → AA bind: routes · Main registration layer forwards antialias op calls.
- Raster bind → Rasterize: invokes · Torch raster binding reaches native rasterization core.
- Interp bind → Interpolate: invokes · Torch interpolation binding reaches native core.
- Texture bind → Texture: invokes · Torch texture binding reaches sampling core.
- AA bind → Antialias: invokes · Torch antialias binding reaches native primitive.
- Common core → Rasterize: supports · Shared helpers underpin rasterization and adjacent ops.
- Common core → Interpolate: supports · Shared helpers underpin interpolation.
- Common core → Texture: supports · Shared helpers underpin texture sampling.
- Common core → Antialias: supports · Shared helpers underpin antialiasing.
- Texture → Texture kernel: uses · Texture wrapper delegates to low-level GPU kernel.
- CUDA raster → Raster impl: contains · Raster backend is organized around internal implementation.
- Raster impl → Raster kernel: drives · Raster implementation coordinates the core kernel.
- Samples → Torch API: demonstrates · Examples show how to compose the public API.
- Docs → Torch API: documents · Documentation explains the exposed torch-facing interface.
- Build → Main bindings: builds · Packaging compiles and links the native extension.
- Build → Common core: builds · Packaging includes shared native rendering core.
- Build → CUDA raster: builds · Packaging includes the CUDA raster backend.
