Training a neural network to render irradiance in real time

At a glance

Project structure

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

Structure observations

• Architecturally prominent files are ranked from entry points and role-named declarations; resource-only paths are omitted.
• Primary languages: C/Objective-C header, Metal, Objective-C, Python.
• The verified tree contains 5 project/configuration file(s) and 11 source declaration(s).

Overall architecture

flowchart LR
    N1["main"]
    N2["ViewController"]
    N3["Renderer"]
    N4["MetalKit / metal_stdlib APIs"]
    N1 --> N2
    N2 --> N3
    N3 --> N4

Reference code

Application/main.m:10 — architecture anchor

int main(int argc, const char * argv[]) {
    return NSApplicationMain(argc, argv);
}

Interpretation

The arrows summarize the source-visible entry, role-named types or folders, and framework direction; when nodes come from structural folders, the sequence is a high-level interpretation rather than proof that every adjacent node calls the next. Ownership is claimed only where the next section cites a stored property or assignment. The diagram is intentionally limited to the dominant path into Metal.

Ownership and state

classDiagram
    IrradianceTechnique o-- uint32_t : totalSteps
    Renderer o-- float : cameraYaw
    Renderer o-- float : cameraPitch
    Renderer o-- float : cameraDistance

Ownership evidence

Renderer/IrradianceTechnique.h:24 — stored dependency or nearest verified ownership anchor

@protocol IrradianceTechnique <NSObject>
// ...
@property (nonatomic, readonly) uint32_t totalSteps;
// ...
@end

Composition arrows indicate a source-visible construction expression or locally owned value state; aggregation means the owner stores or receives a dependency without proving exclusive lifetime ownership.

Concurrency, scheduling, and thread safety

Evidence limit: actor isolation, async/await, or Task creation does not by itself prove background-thread execution; Sendable conformance alone does not prove thread-safe mutation.

No source-visible execution, scheduling, or synchronization boundary was found in the indexed source.

@MainActor/MainActor.run, DispatchQueue.main, and RunLoop.main are reported as distinct isolation, queue, and event-loop mechanisms. A plain Task is kept separate from Task.detached; neither is labeled as a background thread.

State propagation, frameworks, and dependencies

Evidence limit: an import proves a source-level compilation dependency at the cited line; it does not prove runtime use, architectural adoption, or whether a Swift package is a direct application dependency.

receive(on:) describes downstream delivery scheduling, while subscribe(on:) describes upstream subscription/request/cancel scheduling. An import Combine alone establishes neither behavior nor a Store, reducer, Redux, or other application architecture.

Class and protocol design

Renderer/IrradianceTechnique.h:12 — representative type boundary

@protocol IrradianceTechnique <NSObject>
// ...
@end

The source explicitly defines local protocol relationships: IrradianceMonteCarloTechnique → IrradianceTechnique, IrradianceMPPTechnique → IrradianceTechnique, IrradianceMLEncoderTechnique → IrradianceTechnique.

Access control

Reference code

Renderer/IrradianceTechnique.h:24 — representative boundary

@protocol IrradianceTechnique <NSObject>
// ...
@property (nonatomic, readonly) uint32_t totalSteps;
// ...
@end

Swift declarations without a modifier are internal; explicit private, fileprivate, private(set), public, or open entries above are interpreted by language semantics. Objective-C/C samples instead rely on header and implementation boundaries, which are not equivalent to Swift lexical privacy.

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    participant IrradianceTrainer
    participant _device
    participant _commandAllocator
    participant _commandBuffer
    participant enc
    participant MTL4ArgumentTableDescriptor
    participant argTable
    participant _commandQueue
    participant _event
    IrradianceTrainer->>_device: newBufferWithLength()
    IrradianceTrainer->>_commandAllocator: reset()
    IrradianceTrainer->>_commandBuffer: beginCommandBufferWithAllocator()
    IrradianceTrainer->>enc: setComputePipelineState()
    IrradianceTrainer->>MTL4ArgumentTableDescriptor: new()
    IrradianceTrainer->>argTable: setAddress()
    IrradianceTrainer->>_commandQueue: commit()
    IrradianceTrainer->>_event: waitUntilSignaledValue()

Reference code

Renderer/IrradianceTrainer.m:257 — dispatchKaimingInit()

- (void)dispatchKaimingInit
{
    // ...
    id<MTLBuffer> paramsBuffer = [_device newBufferWithLength:MLP_NUM_LAYERS * sizeof(KaimingInitParams)
                                                     options:MTLResourceStorageModeShared];
    KaimingInitParams *paramsPtr = (KaimingInitParams *)paramsBuffer.contents;
    for (uint32_t i = 0; i < MLP_NUM_LAYERS; i++) {
        uint32_t k = _model->layers[i].cols, n = _model->layers[i].rows;
        paramsPtr[i] = (KaimingInitParams){ .cols = k, .rows = n, .fanIn = (i == 0) ? 3 : k, .seed = arc4random() };
    }
    [_commandAllocator reset];
    [_commandBuffer beginCommandBufferWithAllocator:_commandAllocator];
    [_commandBuffer useResidencySet:_residencySet];
    id<MTL4ComputeCommandEncoder> enc = [_commandBuffer computeCommandEncoder];
    [enc setComputePipelineState:_kaimingInitPipelineState];
    MTL4ArgumentTableDescriptor *atd = [MTL4ArgumentTableDescriptor new];
    atd.maxBufferBindCount = 3;
    for (uint32_t i = 0; i < MLP_NUM_LAYERS; i++) {
        NSError *error;
        id<MTL4ArgumentTable> argTable = [_device newArgumentTableWithDescriptor:atd error:&error];
        [argTable setAddress:_masterWeightBuffers[i].gpuAddress atIndex:0];
        [argTable setResource:_model->layers[i].weights.gpuResourceID atBufferIndex:1];
        [argTable setAddress:paramsBuffer.gpuAddress + i * sizeof(KaimingInitParams) atIndex:2];
        [enc setArgumentTable:argTable];
        [enc dispatchThreads:MTLSizeMake(_model->layers[i].cols, _model->layers[i].rows, 1)
            threadsPerThreadgroup:MTLSizeMake(16, 2, 1)];
    }
    [enc endEncoding];
    [_commandBuffer endCommandBuffer];
    _eventValue++;
    [_commandQueue commit:&_commandBuffer count:1];
    [_commandQueue signalEvent:_event value:_eventValue];
    [_event waitUntilSignaledValue:_eventValue timeoutMS:UINT64_MAX];
}

Naming conventions

• Types: Controller: ViewController; Delegate: AppDelegate; Renderer: Renderer.
• Protocols: IrradianceTechnique.
• Methods: load_hdr, _dirs_to_uv, _sample_env, _cosine_sample_hemisphere, _uniform_sphere, _compute_irradiance, __init__, forward.
• Files: Application/AppDelegate.h, Application/AppDelegate.m, Application/ViewController.h, Application/ViewController.m, Renderer/IrradianceTechnique.h, Renderer/Renderer.h.

Architecture takeaways

• main is the main source-visible entry or composition anchor for this sample.
• Framework work reaches Cocoa, MetalKit, metal_stdlib, simd through a deliberately small high-level chain; the detailed API graph remains inside the cited implementation files.
• Stored-property evidence identifies lifecycle collaboration; it does not by itself prove exclusive object ownership.
• Access-control conclusions separate verified language visibility from the likely design rationale.
• Local protocol relationships provide an explicit substitution boundary.

Source map

• Official Apple documentation