Processing HDR images with Metal

At a glance

Project structure

Source bundle/
├── Application/
│   ├── iOS/
│   │   ├── AAPLViewControllerIOS.m
│   │   ├── WindowSceneDelegate.m
│   │   ├── AAPLAppDelegate.h
│   │   └── AAPLAppDelegate.m
│   ├── main.m
│   └── macOS/
│       └── AAPLWindowController.m
└── Renderer/
    ├── AAPLShaders.metal
    ├── AAPLRenderer.m
    └── AAPLShaderTypes.h

Structure observations

• The entry/composition boundary and renderer or operation boundary are separate in the source; AAPLRenderer 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["AAPLWindowController"]
    N2["AAPLRenderer"]
    N3["HDR scene renderer and post processor"]
    N4["tone-map/bloom shader stages"]
    N1 --> N2
    N2 --> N3
    N3 --> N4

Reference code

Renderer/AAPLRenderer.m:808 — ordered bloom and tone-mapping stages

        [self encodeBloomSetupWithCommandBuffer:commandBuffer];
        [self encodeBloomSamplingFiltersWithCommandBuffer:commandBuffer];
        [self encodeBloomCompositeAndToneMappingWithCommandBuffer:commandBuffer view:view];

Interpretation

This is the dominant control/data path: platform code composes AAPLRenderer; that object controls HDR scene renderer and post processor; GPU-visible work ends in tone-map/bloom shader stages. The arrows summarize responsibility transfer, not a claim that every node directly calls the next.

Ownership and state

classDiagram
    AAPLViewControllerIOS *-- AAPLRenderer : _renderer

Ownership evidence

Application/iOS/AAPLViewControllerIOS.m:90 — AAPLViewControllerIOS creates and stores _renderer

    _renderer = [[AAPLRenderer alloc] initWithMetalKitView:_view cameraStepCount:kDefaultCameraStepCount resolutionScale:kDefaultResolutionScale];

    NSAssert(_renderer, @"Renderer failed initialization");

    [_renderer mtkView:_view drawableSizeWillChange:_view.drawableSize];

    _view.delegate = _renderer;

Class and protocol design

Framework delegate conformance is a callback seam; the source does not justify calling the whole app protocol-oriented.

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/AAPLShaders.metal:218 — representative GPU entry/helper

vertex GeometryVertexOut GeometryVertex(const uint vertexID [[ vertex_id ]],
                                        const uint instanceID [[instance_id]],
                                        const VertexIn input [[stage_in]],
                                        const device AAPLUniforms& uniforms [[buffer(AAPLBufferIndexUniforms)]])
{
    // ...
}

Design patterns

Naming conventions

• Role suffixes make ownership visible: AAPLWindowController, AAPLRenderer, AAPLAppDelegate, WindowSceneDelegate.
• Method names describe setup or encoding actions: initWithMetalKitView, setTonemapWhitepoint, cameraAnimationStepCount, minimumResolutionScale, maximumResolutionScale, setResolutionScale, updateWithDevice.
• Shader entry points use stage/operation names: GeometryVertex, GeometryFragment, SkyDomeVertex, SkyDomeFragment, FSQVertex, LogLuminanceFragment.
• AAPL is a sample namespace prefix, not a recommendation for production module naming; retain semantic suffixes such as Renderer, Manager, Scene, or Adapter.

Architecture takeaways

• Keep AAPLWindowController focused on composition; AAPLRenderer is the owner of HDR scene renderer and post processor.
• Treat tone-map/bloom shader stages as a separate execution/compilation boundary with explicit resource and data-layout contracts.
• The verified ownership edge is AAPLViewControllerIOS → _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