Creating a 3D application with hydra rendering

At a glance

Project structure

Source bundle/
└── source/
    ├── AAPLRenderer.mm
    ├── AAPLViewController.mm
    ├── BlitShaders.metal
    ├── main.mm
    ├── AAPLAppDelegate.h
    ├── AAPLAppDelegate.mm
    ├── AAPLRenderer.h
    ├── AAPLViewController.h
    └── AAPLCamera.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["AAPLViewController"]
    N2["AAPLRenderer"]
    N3["Objective-C++ Hydra renderer integration"]
    N4["Hydra render delegate backed by Metal"]
    N1 --> N2
    N2 --> N3
    N3 --> N4

Reference code

source/AAPLRenderer.mm:368 — feature handoff or setup anchor

    HgiMetal* hgi = static_cast<HgiMetal*>(_hgi.get());
    hgi->StartFrame();
    
    // Draw the scene using Hydra, and recast the result to a MTLTexture.
    CGSize viewSize = [view drawableSize];
    HgiTextureHandle hgiTexture = [self drawWithHydraAt:timeCode viewSize:viewSize];
    id<MTLTexture> texture = static_cast<HgiMetalTexture*>(hgiTexture.Get())->GetTextureId();

Interpretation

This is the dominant control/data path: platform code composes AAPLRenderer; that object controls Objective-C++ Hydra renderer integration; GPU-visible work ends in Hydra render delegate backed by Metal. The arrows summarize responsibility transfer, not a claim that every node directly calls the next.

Ownership and state

classDiagram
    AAPLViewController *-- AAPLRenderer : _renderer

Ownership evidence

source/AAPLViewController.mm:35 — 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

source/BlitShaders.metal:17 — full-screen blit vertex entry point

vertex VertexOut vtxBlit(uint vid [[vertex_id]])
{
    // ...
}

Design patterns

Naming conventions

• Role suffixes make ownership visible: AAPLViewController, AAPLRenderer, AAPLAppDelegate.
• Method names describe setup or encoding actions: applicationDidFinishLaunching, applicationWillTerminate, applicationShouldTerminateAfterLastWindowClosed, initWithMetalKitView, setupScene, requestFrame, initializeMaterial.
• Shader entry points use stage/operation names: vtxBlit, fragBlitLinear.
• 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 Objective-C++ Hydra renderer integration.
• Treat Hydra render delegate backed by Metal 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