# feederbrian/appgl-runtime architecture

> Architecture diagram of the GitHub repository feederbrian/appgl-runtime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/feederbrian/appgl-runtime
- Repository: https://github.com/feederbrian/appgl-runtime

## Overview

AppGL is a macOS OpenGL 4.6-to-Metal translation layer. The principal workflow starts with an application’s OpenGL calls, routes them through installed dispatch into per-context state and object handling, translates shaders and draw state, then submits work to Metal. The README also identifies runtime-selected feature flags and the fp64, fragment-shading-rate, and sparse-texture extensions. The sampled source is partial, so links for unsampled subsystem internals are omitted where their wiring is uncertain.

Main entry points: [`src/context/GLContext.h`](https://github.com/feederbrian/appgl-runtime/blob/main/src/context/GLContext.h) (GL context), [`src/runtime/AppGLRuntime.cpp`](https://github.com/feederbrian/appgl-runtime/blob/main/src/runtime/AppGLRuntime.cpp) (Runtime), [`src/extensions/ExtensionRegistry.h`](https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/ExtensionRegistry.h) (Extension registry), [`src/shader/ShaderTranslator.cpp`](https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/ShaderTranslator.cpp) (Shader translation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["GL interface"]
  node_api["OpenGL API<br/>[AppGL.h]"]
  node_dispatch["GL dispatch"]
end

subgraph group_runtime["Runtime and state"]
  node_runtime["Runtime<br/>[AppGLRuntime.cpp]"]
  node_context["GL context<br/>[GLContext.h]"]
  node_state["GL state tracker<br/>[GLStateTracker.h]"]
  node_objects["GL object store<br/>[GLObjectStore.cpp]"]
  node_capabilities["Capabilities<br/>[GLCapabilities.h]"]
  node_flags["Feature flags"]
end

subgraph group_translation["Translation and rendering"]
  node_shader["Shader translation"]
  node_rewrite["Compatibility rewrite"]
  node_reflection["GLSL reflection<br/>[GLSLReflection.cpp]"]
  node_pipeline["Pipeline cache<br/>[PipelineCache.cpp]"]
  node_framegraph["Metal frame graph<br/>[MetalFrameGraph.h]"]
  node_submission["Metal submission"]
end

subgraph group_extensions["Extensions"]
  node_registry["Extension registry"]
  node_fp64["fp64 emulation<br/>[Fp64Module.h]"]
  node_shadingrate["Shading rate"]
  node_sparse["Sparse texture"]
end

subgraph group_diagnostics["Diagnostics"]
  node_diagnostics["Diagnostics"]
  node_coverage["Coverage tracking<br/>[CoverageStore.cpp]"]
  node_trace["Trace log<br/>[TraceLog.cpp]"]
end

node_application(("OpenGL application"))
node_metal["Metal runtime"]

node_application -->|"calls GL"| node_api
node_api -->|"dispatches"| node_dispatch
node_dispatch -->|"enters runtime"| node_runtime
node_runtime -->|"manages context"| node_context
node_context -->|"updates state"| node_state
node_context -->|"accesses objects"| node_objects
node_context -->|"checks support"| node_capabilities
node_runtime -->|"reads flags"| node_flags
node_context -->|"translates shaders"| node_shader
node_shader -->|"rewrites shaders"| node_rewrite
node_shader -->|"reflects GLSL"| node_reflection
node_context -->|"uses cache"| node_pipeline
node_context -->|"encodes draws"| node_framegraph
node_framegraph -->|"submits commands"| node_submission
node_submission -->|"executes commands"| node_metal
node_context -->|"uses extensions"| node_registry
node_registry -->|"dispatches extension"| node_fp64
node_registry -->|"dispatches extension"| node_shadingrate
node_registry -->|"dispatches extension"| node_sparse
node_runtime -->|"exposes diagnostics"| node_diagnostics
node_diagnostics -->|"reports coverage"| node_coverage
node_diagnostics -->|"reports trace"| node_trace

click node_api "https://github.com/feederbrian/appgl-runtime/blob/main/include/AppGL/AppGL.h"
click node_dispatch "https://github.com/feederbrian/appgl-runtime/blob/main/src/loader/DispatchInstall.cpp"
click node_runtime "https://github.com/feederbrian/appgl-runtime/blob/main/src/runtime/AppGLRuntime.cpp"
click node_context "https://github.com/feederbrian/appgl-runtime/blob/main/src/context/GLContext.h"
click node_state "https://github.com/feederbrian/appgl-runtime/blob/main/src/state/GLStateTracker.h"
click node_objects "https://github.com/feederbrian/appgl-runtime/blob/main/src/objects/GLObjectStore.cpp"
click node_capabilities "https://github.com/feederbrian/appgl-runtime/blob/main/src/caps/GLCapabilities.h"
click node_flags "https://github.com/feederbrian/appgl-runtime/blob/main/src/runtime/AppGLFeatureFlags.h"
click node_shader "https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/ShaderTranslator.cpp"
click node_rewrite "https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/CompatShaderRewrite.cpp"
click node_reflection "https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/GLSLReflection.cpp"
click node_pipeline "https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/PipelineCache.cpp"
click node_framegraph "https://github.com/feederbrian/appgl-runtime/blob/main/src/context/MetalFrameGraph.h"
click node_submission "https://github.com/feederbrian/appgl-runtime/blob/main/src/context/MetalCommandSubmission.h"
click node_registry "https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/ExtensionRegistry.h"
click node_fp64 "https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/fp64/Fp64Module.h"
click node_shadingrate "https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/fragment_shading_rate/FragmentShadingRateModule.h"
click node_sparse "https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/sparse_texture/SparseTextureModule.h"
click node_diagnostics "https://github.com/feederbrian/appgl-runtime/blob/main/src/runtime/AppGLDiagnostics.cpp"
click node_coverage "https://github.com/feederbrian/appgl-runtime/blob/main/src/debug/CoverageStore.cpp"
click node_trace "https://github.com/feederbrian/appgl-runtime/blob/main/src/debug/TraceLog.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_dispatch toneBlue
class node_runtime,node_context,node_state,node_objects,node_capabilities,node_flags toneAmber
class node_shader,node_rewrite,node_reflection,node_pipeline,node_framegraph,node_submission toneMint
class node_registry,node_fp64,node_shadingrate,node_sparse toneRose
class node_diagnostics,node_coverage,node_trace,node_application,node_metal toneIndigo
```

## Components

### GL interface

- [OpenGL API](https://github.com/feederbrian/appgl-runtime/blob/main/include/AppGL/AppGL.h): `include/AppGL/AppGL.h`
- [GL dispatch](https://github.com/feederbrian/appgl-runtime/blob/main/src/loader/DispatchInstall.cpp): `src/loader/DispatchInstall.cpp`

### Runtime and state

- [Runtime](https://github.com/feederbrian/appgl-runtime/blob/main/src/runtime/AppGLRuntime.cpp): `src/runtime/AppGLRuntime.cpp`
- [GL context](https://github.com/feederbrian/appgl-runtime/blob/main/src/context/GLContext.h): `src/context/GLContext.h`
- [GL state tracker](https://github.com/feederbrian/appgl-runtime/blob/main/src/state/GLStateTracker.h): `src/state/GLStateTracker.h`
- [GL object store](https://github.com/feederbrian/appgl-runtime/blob/main/src/objects/GLObjectStore.cpp): `src/objects/GLObjectStore.cpp`
- [Capabilities](https://github.com/feederbrian/appgl-runtime/blob/main/src/caps/GLCapabilities.h): `src/caps/GLCapabilities.h`
- [Feature flags](https://github.com/feederbrian/appgl-runtime/blob/main/src/runtime/AppGLFeatureFlags.h): `src/runtime/AppGLFeatureFlags.h`

### Translation and rendering

- [Shader translation](https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/ShaderTranslator.cpp): `src/shader/ShaderTranslator.cpp`
- [Compatibility rewrite](https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/CompatShaderRewrite.cpp): `src/shader/CompatShaderRewrite.cpp`
- [GLSL reflection](https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/GLSLReflection.cpp): `src/shader/GLSLReflection.cpp`
- [Pipeline cache](https://github.com/feederbrian/appgl-runtime/blob/main/src/shader/PipelineCache.cpp): `src/shader/PipelineCache.cpp`
- [Metal frame graph](https://github.com/feederbrian/appgl-runtime/blob/main/src/context/MetalFrameGraph.h): `src/context/MetalFrameGraph.h`
- [Metal submission](https://github.com/feederbrian/appgl-runtime/blob/main/src/context/MetalCommandSubmission.h): `src/context/MetalCommandSubmission.h`

### Extensions

- [Extension registry](https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/ExtensionRegistry.h): `src/extensions/ExtensionRegistry.h`
- [fp64 emulation](https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/fp64/Fp64Module.h): `src/extensions/fp64/Fp64Module.h`
- [Shading rate](https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/fragment_shading_rate/FragmentShadingRateModule.h): `src/extensions/fragment_shading_rate/FragmentShadingRateModule.h`
- [Sparse texture](https://github.com/feederbrian/appgl-runtime/blob/main/src/extensions/sparse_texture/SparseTextureModule.h): `src/extensions/sparse_texture/SparseTextureModule.h`

### Diagnostics

- [Diagnostics](https://github.com/feederbrian/appgl-runtime/blob/main/src/runtime/AppGLDiagnostics.cpp): `src/runtime/AppGLDiagnostics.cpp`
- [Coverage tracking](https://github.com/feederbrian/appgl-runtime/blob/main/src/debug/CoverageStore.cpp): `src/debug/CoverageStore.cpp`
- [Trace log](https://github.com/feederbrian/appgl-runtime/blob/main/src/debug/TraceLog.cpp): `src/debug/TraceLog.cpp`

### Other components

- **OpenGL application**
- **Metal runtime**

## Connections

- OpenGL application → OpenGL API: calls GL
- OpenGL API → GL dispatch: dispatches
- GL dispatch → Runtime: enters runtime
- Runtime → GL context: manages context
- GL context → GL state tracker: updates state
- GL context → GL object store: accesses objects
- GL context → Capabilities: checks support
- Runtime → Feature flags: reads flags
- GL context → Shader translation: translates shaders
- Shader translation → Compatibility rewrite: rewrites shaders
- Shader translation → GLSL reflection: reflects GLSL
- GL context → Pipeline cache: uses cache
- GL context → Metal frame graph: encodes draws
- Metal frame graph → Metal submission: submits commands
- Metal submission → Metal runtime: executes commands
- GL context → Extension registry: uses extensions
- Extension registry → fp64 emulation: dispatches extension
- Extension registry → Shading rate: dispatches extension
- Extension registry → Sparse texture: dispatches extension
- Runtime → Diagnostics: exposes diagnostics
- Diagnostics → Coverage tracking: reports coverage
- Diagnostics → Trace log: reports trace