Training a neural network to render irradiance in real time

At a glance

Project structure

Source bundle/
├── train_irradiance.py
├── Application/
│   ├── ViewController.m
│   ├── main.m
│   ├── AppDelegate.h
│   └── AppDelegate.m
└── Renderer/
    ├── Composite.metal
    ├── Renderer.m
    ├── IrradianceModel.h
    └── ShaderTypes.h

Structure observations

• The entry/composition boundary and renderer or operation boundary are separate in the source; IrradianceMLEncoderTechnique is the principal feature coordinator.
• GPU-specific logic stays in Metal shader files; shared headers bridge host/shader layouts where present.
• The tree above is intentionally pruned to composition, resource, and shader files.

Overall architecture

flowchart LR
    N1["Python training/export"]
    N2["model weights"]
    N3["Irradiance ML technique"]
    N4["Renderer composition"]
    N1 --> N2
    N2 --> N3
    N3 --> N4

Reference code

train_irradiance.py:233 — offline model tracing and Core ML conversion

def main() -> None:
    # ...

Interpretation

This diagram crosses an offline/runtime boundary: Python produces model weights; it does not call the app renderer. At runtime, the irradiance ML technique consumes the exported representation and the renderer composites the result.

Ownership and state

classDiagram
    ViewController *-- Renderer : _renderer

Ownership evidence

Application/ViewController.m:35 — ViewController creates and stores _renderer

@implementation ViewController
// ...
    _renderer = [[Renderer alloc] initWithMetalKitView:_view];
// ...
@end

Class and protocol design

A local protocol/conformance boundary is present, so protocol-oriented collaboration is claimed only for that seam.

Access control

This sample does not use Swift private, fileprivate, or public for its native boundary. Objective-C/Objective-C++ use header versus implementation placement, C++ uses access specifiers/linkage, Python uses module conventions, and Metal entry points cross a compiled-library boundary; these are not Swift access levels.

Logic ownership and placement

Shader boundary reference

Renderer/Irradiance.metal:194 — neural irradiance compute kernel and tensor bindings

kernel void irradianceMLPComputeShader(
    uint2 threadPos [[thread_position_in_grid]],
    uint  lane      [[thread_index_in_simdgroup]],
    uint  sgIdx     [[simdgroup_index_in_threadgroup]],
    texture2d<half> normalBuffer   [[texture(TextureIndexNormalBuffer)]],
    tensor<device half, dextents<int, 3>> irradianceOutput [[buffer(BufferIndexOutputTensor)]],
    tensor<device half, extents<int, NUM_INPUT, NUM_HIDDEN>>  layer0Weights [[buffer(BufferIndexMLPLayer0)]],
    tensor<device half, extents<int, NUM_HIDDEN, NUM_HIDDEN>> layer1Weights [[buffer(BufferIndexMLPLayer1)]],
    tensor<device half, extents<int, NUM_HIDDEN, MLP_OUTPUT>> layer2Weights [[buffer(BufferIndexMLPLayer2)]],
    const device half *bias0 [[buffer(BufferIndexMLPBias0)]],
    const device half *bias1 [[buffer(BufferIndexMLPBias1)]],
    const device half *bias2 [[buffer(BufferIndexMLPBias2)]])
{
    // ...
}

Design patterns

Naming conventions

• Role suffixes make ownership visible: ViewController, Renderer, AppDelegate.
• Method names describe setup or encoding actions: load_hdr, _dirs_to_uv, _sample_env, _cosine_sample_hemisphere, _uniform_sphere, _compute_irradiance, __init__.
• Shader entry points use stage/operation names: fullscreenVertexShader, compositeFragmentShader, geometryVertexShader, geometryFragmentShader, irradianceMCComputeShader, textureToTensorKernel.
• Names favor concrete domain roles and target-local types; no broad public library namespace is introduced.

Architecture takeaways

• Keep Python training/export focused on composition; IrradianceMLEncoderTechnique is the owner of Python training/export plus app inference.
• Treat Metal neural irradiance evaluation as a separate execution/compilation boundary with explicit resource and data-layout contracts.
• The verified ownership edge is ViewController → _renderer; broader exclusive ownership is not inferred.
• Access-control rationale follows concrete language boundaries rather than translating every header or shader symbol into Swift terms.

Source map

• Official Apple documentation