Rendering a scene with forward plus lighting using tile shaders

At a glance

Project structure

Source bundle/
├── Renderer/
│   ├── AAPLRenderer.m
│   ├── AAPLCulling.metal
│   ├── AAPLShaderCommon.h
│   └── AAPLMesh.h
└── Application/
    ├── AAPLViewController.m
    ├── main.m
    ├── WindowSceneDelegate.m
    ├── AAPLAppDelegate.h
    └── AAPLAppDelegate.m

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["AAPLViewController"]
    N2["AAPLRenderer"]
    N3["forward-plus light culling and rendering"]
    N4["tile shader and raster lighting stages"]
    N1 --> N2
    N2 --> N3
    N3 --> N4

Reference code

Renderer/AAPLRenderer.m:694 — feature handoff or setup anchor

        [renderEncoder dispatchThreadsPerTile:MTLSizeMake(AAPLTileWidth, AAPLTileHeight, 1)];
        [renderEncoder popDebugGroup];
                // Perform tile culling, to minimize the number of lights rendered per tile.
        [renderEncoder pushDebugGroup:@"Prepare Light Lists"];
        [renderEncoder setRenderPipelineState:_lightCullingPipelineState];
        [renderEncoder setThreadgroupMemoryLength:AAPLThreadgroupBufferSize offset:0 atIndex:AAPLThreadgroupBufferIndexLightList];
        [renderEncoder setThreadgroupMemoryLength:AAPLTileDataSize offset:AAPLThreadgroupBufferSize atIndex:AAPLThreadgroupBufferIndexTileData];
        [renderEncoder setTileBuffer:_frameDataBuffers[_currentBufferIndex] offset:0 atIndex:AAPLBufferIndexFrameData];

Interpretation

This is the dominant control/data path: platform code composes AAPLRenderer; that object controls forward-plus light culling and rendering; GPU-visible work ends in tile shader and raster lighting stages. The arrows summarize responsibility transfer, not a claim that every node directly calls the next.

Ownership and state

classDiagram
    AAPLViewController *-- AAPLRenderer : _renderer

Ownership evidence

Application/AAPLViewController.m:29 — AAPLViewController creates and stores _renderer

@implementation AAPLViewController
// ...
    _renderer = [[AAPLRenderer alloc] initWithMetalKitView:_view];
// ...
@end

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

kernel void create_bins(imageblock<ColorData,imageblock_layout_implicit> imageBlock,
                        constant AAPLFrameData & frameData    [[ buffer(AAPLBufferIndexFrameData) ]],
                        device vector_float4* light_positions [[ buffer(AAPLBufferIndexLightsPosition) ]],
                        threadgroup TileData *tile_data       [[ threadgroup(AAPLThreadgroupBufferIndexTileData) ]],
                        ushort2 thread_local_position         [[ thread_position_in_threadgroup ]],
                        uint thread_linear_id                 [[ thread_index_in_threadgroup ]],
                        uint quad_lane_id                     [[ thread_index_in_quadgroup ]])
{
    // ...
}

Design patterns

Naming conventions

• Role suffixes make ownership visible: AAPLViewController, AAPLRenderer, AAPLAppDelegate, WindowSceneDelegate.
• Method names describe setup or encoding actions: application, applicationShouldTerminateAfterLastWindowClosed, newMeshesFromURL, viewDidLoad, scene, sceneDidDisconnect, initWithMetalKitView.
• Shader entry points use stage/operation names: create_bins, cull_lights, depth_pre_pass_vertex, depth_pre_pass_fragment, fairy_vertex, fairy_fragment.
• 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 AAPLViewController focused on composition; AAPLRenderer is the owner of forward-plus light culling and rendering.
• Treat tile shader and raster lighting stages as a separate execution/compilation boundary with explicit resource and data-layout contracts.
• The verified ownership edge is AAPLViewController → _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