macOS (Metal / OSX64)

Gorilla3D supports macOS 64-Bit (Intel x64) through Apple's Metal graphics API. OpenGL has been deprecated on macOS by Apple — the framework therefore targets Metal as the primary backend on this platform.

macOS support is currently in active development. A working subset of the framework is verified, but several features are not yet implemented or have known issues. See the matrix below for details before committing to macOS for a production release.

Prerequisites

  • A Mac with an Apple-supported macOS version (we test on the latest two major releases).
  • Xcode with the matching command-line tools — required by PAServer to link Metal binaries.
  • PAServer for macOS (Platform Assistant), reachable from your Delphi IDE.
  • A Delphi version that supports the OSX64 target with Metal — Delphi 11 Alexandria or later is recommended.
  • Gorilla3D package paths registered in the IDE for the OSX64 platform.

Apple Silicon (M1 / M2 / M3 / …)

The current macOS build targets Intel x64. On Apple-Silicon Macs the binary runs through Rosetta 2. A native OSXARM64 build is on the roadmap and will be added once we've stabilized the Metal toolchain for OSX64.

Setting up PAServer on macOS

  1. Copy the matching PAServer-XX.X.pkg from your Delphi installation to the Mac and run it.
  2. Launch PAServer (it lives in /Applications) and note the password printed in the terminal window.
  3. In the IDE go to Tools > Options > Deployment > Connection Profile Manager and create a new macOS profile pointing at the Mac's hostname / IP and that password.
  4. Use SDK Manager to import the macOS SDK on first connection — PAServer will copy the required headers / frameworks back to the IDE.

Building & Deploying

  1. Add macOS 64-Bit as a target platform.
  2. Pick the macOS connection profile and SDK.
  3. Configure code-signing under Project > Options > Provisioning (required for distribution; ad-hoc signing is enough during development).
  4. Add deployment entries for your assets and any third-party .dylib files.
  5. Build in Release for store / notarized distribution; Debug lets you step through code via PAServer.

Shaders on Metal — GLSL Translation vs. Hand-written MSL

Gorilla3D's renderer is built around GLSL — every default material, render pass and behaviour ships its shader source as GLSL. Metal does not understand GLSL, so on macOS the framework needs to either translate GLSL into Metal Shading Language (MSL) at runtime, or fall back to hand-written MSL snippets that the framework compiles directly.

Both approaches coexist in the same project. You normally start with the parser and only hand-write MSL when the parser cannot represent a particular construct.

Shader Architectures

Each material / render pass stores its shaders in a list of architectures. Two are relevant on macOS:

  • GLSL-Arch — the GLSL source that drives OpenGL, OpenGL ES and (after on-the-fly translation) Vulkan. The Metal backend feeds this through the TGorillaParserGLSL translator and emits MSL.
  • Metal-Arch — hand-written MSL source that bypasses the translator entirely.

When the Metal backend prepares a shader, it picks the architecture in the following order:

  1. If a Metal-Arch is registered → compile that MSL directly (fastest, no parsing).
  2. Else if a GLSL-Arch is registered → run the GLSL→MSL parser, compile the generated MSL.
  3. If both are missing the pipeline state is nil and the framework logs an error and skips the draw.

Materials that already have a working GLSL implementation do not need a Metal-Arch entry in most cases — the parser handles them. Add a Metal-Arch only when you hit one of the parser limitations described below.

Path A — Translating GLSL to MSL

The translator (Gorilla.Material.Parser.GLSL.pas / Gorilla.Material.Parser.C.pas) walks the GLSL AST and emits MSL on the fly. It handles the bulk of the framework's built-in materials, including PBR, Lambert/Phong/BlinnPhong, Atlas, SplatMap, Layered, Layer3D and most material behaviours (color adjust, rim light, caustics, wobble, wind, …).

The translator also performs a few Metal-specific adaptations automatically:

  • Buffer slots are remapped — Gorilla3D uses a fixed Metal buffer layout: buffer(0) = vertex data, buffer(1) = model matrix, buffer(2) = ShaderData UBO, buffer(N+2) = additional registered uniform blocks.
  • std140 offsets are computed for the ShaderData struct so CPU-side uniform writes land at the same byte offset MSL reads from. The CPU buffer is uploaded as a single setVertexBytes / setFragmentBytes per draw.
  • Identifier remapping — bare uniform names (_ProjectionMatrix, _ViewMatrix, …) inside the shader body are rewritten to struct-member access (params._ProjectionMatrix, …) where appropriate.
  • Vertex input patching — when the active mesh's vertex declaration does not provide an attribute the shader references (e.g. the shader expects colorf0 but the mesh has no vertex colors), the missing field is replaced by a constant default (float4(0)) so MSL still compiles.
  • Texture & sampler indices are assigned in their own namespace ([[texture(N)]], [[sampler(N)]]) and never collide with buffer indices.

Translator limitations to be aware of

The parser cannot represent every GLSL idiom. The cases below are the ones you are most likely to run into:

  • Loose top-level uniform declarations are dropped. Only uniform <Name> { … } blocks are translated. A bare uniform mat4 MyMatrix; will be silently ignored in the MSL output. Wrap individual uniforms in a layout block, or provide a Metal-Arch shader that accepts the value as a buffer.
  • Custom struct names other than ShaderData (e.g. SkyBoxShaderData) are not auto-mapped to the params argument inside main(). Either rename to ShaderData or hand-write the MSL.
  • Helper functions cannot reference ShaderData fields directly — only main() has params in scope. Pass the matrices/values as parameters into helpers (this is how Gorilla.Material.Behaviour.Wind.pas does it).
  • Built-in function coverage — the translator ships overloads for the GLSL built-ins it has seen so far. If you use a less common built-in (mod() on a vector, smoothstep overloads, …) and get an MSL compile error, register it via DoRegisterEmbeddedFunc() or write the MSL by hand.

Path B — Hand-written MSL (Metal-Arch)

When a shader cannot go through the translator (or when you simply want the lowest-overhead path), register an MSL source string under the Metal-Arch architecture. The framework compiles it with MTLLibrary newLibraryWithSource: and runs it directly.

The MSL must follow Gorilla3D's binding contract:

Stage Binding Semantics
Vertex [[buffer(0)]] VertexInput — generated from the mesh's vertex declaration via <#VertexDeclaration#>.
Vertex [[buffer(1)]] ModelMatrixInput — per-instance model matrix (used for GPU instancing).
Vertex/FS [[buffer(2)]] ShaderData — the std140-packed uniform block computed by the framework.
Vertex/FS [[buffer(N+2)]] Additional registered UBOs (e.g. behaviour parameter blocks). N is the GLSL binding.
FS [[texture(N)]] / [[sampler(N)]] Texture and sampler bindings, separate namespace from buffers.

The framework provides a few placeholder tokens you can drop into your MSL source so the compiler stays in sync with the runtime:

  • <#VertexDeclaration#> — replaced by the active mesh's VertexInput struct.
  • <#TVaryingStruct#> — replaced by the shared vertex→fragment varying struct.
  • <#TRenderTargets#> — replaced by the MRT output struct (5 color attachments matching Gorilla3D's forward renderer).

The framework also takes care of:

  • Y-flip — set the projection-Y sign explicitly in the vertex shader (sign(params._ProjMatrix[1][1])) instead of negating in the matrix; FMX's projection convention conflicts with Metal's NDC.
  • Winding order — setFrontFacingWinding(MTLWindingClockwise) is configured globally to match FMX, no shader work required.
  • Depth range — Metal NDC depth is [0..1]. The framework remaps the projection automatically; do not redo it in the shader.

Example — registering a Metal-Arch fragment shader

The pattern below mirrors how Gorilla.SkyBox.pas registers its hand-written shaders. Use it as a template when you need to bypass the translator for a custom material:

const
  MSL_VS =
    '#include <metal_stdlib>'#13#10 +
    'using namespace metal;'#13#10 +
    '<#VertexDeclaration#>'#13#10 +
    'struct ModelMatrixInput { float4x4 ModelMatrix; };'#13#10 +
    'struct ShaderData { float4x4 _ProjMatrix; float4x4 _ViewMatrix; };'#13#10 +
    '<#TVaryingStruct#>'#13#10 +
    'vertex TVaryingStruct vertexMain('#13#10 +
    '    VertexInput in [[stage_in]],'#13#10 +
    '    constant ModelMatrixInput& mm [[buffer(1)]],'#13#10 +
    '    constant ShaderData& params [[buffer(2)]]) { /* ... */ }';
  MSL_FS =
    '#include <metal_stdlib>'#13#10 +
    'using namespace metal;'#13#10 +
    '<#TVaryingStruct#>'#13#10 +
    '<#TRenderTargets#>'#13#10 +
    'fragment TRenderTargets fragmentMain(TVaryingStruct in [[stage_in]],'#13#10 +
    '    texturecube<float> cubeMap [[texture(0)]],'#13#10 +
    '    sampler cubeSampler [[sampler(0)]]) { /* ... */ }';

procedure RegisterMyMaterialShaders(const AMat : TGorillaMaterial);
begin
  AMat.AddShaderArch('Metal-Arch', stVertex,   MSL_VS, 'vertexMain');
  AMat.AddShaderArch('Metal-Arch', stFragment, MSL_FS, 'fragmentMain');
end;

If you also keep the GLSL source for the OpenGL / Vulkan paths, simply register both architectures — the Metal backend picks Metal-Arch and the OpenGL / Vulkan backends pick GLSL-Arch.

When to use which path

  • Stick with GLSL for ordinary node-based materials, PBR, behaviours, and pass-through render targets. Less code, single source of truth across all backends.
  • Add a Metal-Arch shader when:
    • The material uses a UBO struct with a name other than ShaderData (e.g. SkyBoxShaderData).
    • The shader relies on loose top-level uniforms that the translator drops.
    • You hit an MSL compile error from a missing built-in / unsupported overload and don't want to extend the translator.
    • You are writing a new render pass with custom MRT layouts that don't map cleanly to GLSL.

Diagnosing shader problems on Metal

The framework writes MSL compile errors to FMX.Types.Log together with the generated source. Typical patterns:

  • no member named 'colorf0' in 'VertexInput' → the shader references a vertex attribute the mesh doesn't provide. The translator will normally patch this; if you are on Metal-Arch, declare a fallback or fix the mesh's vertex declaration.
  • use of undeclared identifier '_ModelViewProjMatrix' → a loose uniform was dropped by the translator. Wrap it in a uniform ShaderData { … } block, or move it to Metal-Arch.
  • 'params' is unused / struct member not found → a helper function references params which is only in scope inside main(). Pass the value through as a parameter.
  • No pipeline state created, draw skipped → both Metal-Arch and GLSL-Arch produced no output. Check the log for the underlying parse / compile error.

Tip: enable verbose logging on the Metal context to dump the generated MSL during development. Strip the dump again before shipping — the translator runs on every shader (re)compile.

Verified Feature Matrix

Legend: ✅ working — ❓ partially / not verified — ❌ not working / known issue

Feature Metal / OSX64
FMX Primitives ❌ stretched (model-matrix issue)
FMX MaterialSources ❌
Gorilla3D Primitives ✅
Gorilla3D Model ✅
Gorilla3D Model — STATIC ✅
Gorilla3D Model — Uncached Animations ✅
Gorilla3D Model — Cached Animations ✅
Gorilla3D Model — Instancing ✅
Texture formats other than BGRA ❌
Default Materials (Lambert, Phong, BlinnPhong) ✅
Sharing a G3D material with multiple objects ✅
Cross-Material (FMX ↔ G3D) ❓
Pure Color material ❓
VertexColor material ❓
POM material ❌
PBR material ❌
Atlas material ✅
SplatMap material ✅
Layered materials ✅
Layer3D / Layout3D ✅
TextLayer3D ✅
Material Behaviours — fragment shaders (color adjust, rim light, caustics) ✅
Material Behaviours — vertex shaders (wobble, wind) ✅
Depth render pass ✅
Blur render pass ❌
EmissiveBlur ❌
Global Illumination ❌
WBOIT rendering ✅
Composite rendering ✅
OutputLayers ✅
Skybox — Procedural ✅
Skybox — Blank ✅
Skybox — CubeMap ✅
Reflection render pass ✅
Refraction render pass ✅
Environment mapping ❌
MSAA ❌
FXAA ❌
PostFX (with concat) ❌
User shader via VertexShader / SurfaceShader ❌
Water surface material ❌
Particle system — untextured ✅
Particle system — textured (smoke emitter) ❌ particles too small and too dark
Volume rendering ❌

Known Issues & Recommendations

  • FMX primitives are stretched — the FMX-to-Metal model matrix conversion is currently incorrect. As a workaround, prefer Gorilla3D primitives / models, which are verified to render correctly.
  • FMX MaterialSources are tied to the same code path and therefore also affected.
  • Texture formats other than BGRA — Metal's MTLPixelFormat enumeration does not 1:1 map to OpenGL formats. The framework currently expects BGRA8 input on macOS; convert your textures before assignment.
  • POM and PBR materials rely on shader features that are not yet ported to MSL (Metal Shading Language). Use Lambert / Phong / BlinnPhong instead.
  • Post-processing (Blur, EmissiveBlur, GI, MSAA, FXAA, PostFX, user shaders) is not yet available on Metal. If your project depends on screen-space effects, target Windows or Android until macOS post-processing lands.
  • Water surface, environment mapping, volume rendering are all not yet implemented for the Metal backend.
  • Textured particle systems render too small and too dark on Metal — this is a normalization issue in the particle shader. Untextured particles are unaffected.

If macOS is on your release path, plan around these gaps and reach out to support so we can prioritize the features you depend on.

Troubleshooting

  • PAServer connection fails — make sure the Mac firewall allows incoming connections on PAServer's port (default 64211). Also check that the IDE's profile uses the same password PAServer printed.
  • "Metal not available" — your Mac's GPU is not on Apple's Metal-compatible list. Metal is required; OpenGL on macOS is deprecated and not supported by Gorilla3D.
  • Stretched / squashed models for FMX shapes — known bug, see above. Switch to Gorilla3D primitives.
  • App crashes on first texture upload — likely a non-BGRA texture format. Convert the texture, or load it through TGorillaTextureBitmap which handles channel order normalization.
  • Build runs through Rosetta — on Apple Silicon this is currently expected. Native ARM64 support is planned.

Next Steps