CharlesWiltgen

axiom-metal-migration-ref

@CharlesWiltgen/axiom-metal-migration-ref
CharlesWiltgen
160
11 forks
Updated 1/6/2026
View on GitHub

Use when converting shaders or looking up API equivalents - GLSL to MSL, HLSL to MSL, GL/DirectX to Metal mappings, MTKView setup code

Installation

$skills install @CharlesWiltgen/axiom-metal-migration-ref
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Path.claude-plugin/plugins/axiom/skills/axiom-metal-migration-ref/SKILL.md
Branchmain
Scoped Name@CharlesWiltgen/axiom-metal-migration-ref

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions


name: axiom-metal-migration-ref description: Use when converting shaders or looking up API equivalents - GLSL to MSL, HLSL to MSL, GL/DirectX to Metal mappings, MTKView setup code skill_type: reference version: 1.0.0 apple_platforms: [iOS 12+, macOS 10.14+, tvOS 12+]

Metal Migration Reference

Complete reference for converting OpenGL/DirectX code to Metal.

When to Use This Reference

Use this reference when:

  • Converting GLSL shaders to Metal Shading Language (MSL)
  • Converting HLSL shaders to MSL
  • Looking up GL/D3D API equivalents in Metal
  • Setting up MTKView or CAMetalLayer
  • Building render pipelines
  • Using Metal Shader Converter for DirectX

Part 1: GLSL to MSL Conversion

Type Mappings

GLSLMSLNotes
voidvoid
boolbool
intint32-bit signed
uintuint32-bit unsigned
floatfloat32-bit
doubleN/AUse float (no 64-bit float in MSL)
vec2float2
vec3float3
vec4float4
ivec2int2
ivec3int3
ivec4int4
uvec2uint2
uvec3uint3
uvec4uint4
bvec2bool2
bvec3bool3
bvec4bool4
mat2float2x2
mat3float3x3
mat4float4x4
mat2x3float2x3Columns x Rows
mat3x4float3x4
sampler2Dtexture2d<float> + samplerSeparate in MSL
sampler3Dtexture3d<float> + sampler
samplerCubetexturecube<float> + sampler
sampler2DArraytexture2d_array<float> + sampler
sampler2DShadowdepth2d<float> + sampler

Built-in Variable Mappings

GLSLMSLStage
gl_PositionReturn [[position]]Vertex
gl_PointSizeReturn [[point_size]]Vertex
gl_VertexID[[vertex_id]] parameterVertex
gl_InstanceID[[instance_id]] parameterVertex
gl_FragCoord[[position]] parameterFragment
gl_FrontFacing[[front_facing]] parameterFragment
gl_PointCoord[[point_coord]] parameterFragment
gl_FragDepthReturn [[depth(any)]]Fragment
gl_SampleID[[sample_id]] parameterFragment
gl_SamplePosition[[sample_position]] parameterFragment

Function Mappings

GLSLMSLNotes
texture(sampler, uv)tex.sample(sampler, uv)Method on texture
textureLod(sampler, uv, lod)tex.sample(sampler, uv, level(lod))
textureGrad(sampler, uv, ddx, ddy)tex.sample(sampler, uv, gradient2d(ddx, ddy))
texelFetch(sampler, coord, lod)tex.read(coord, lod)Integer coords
textureSize(sampler, lod)tex.get_width(lod), tex.get_height(lod)Separate calls
dFdx(v)dfdx(v)
dFdy(v)dfdy(v)
fwidth(v)fwidth(v)Same
mix(a, b, t)mix(a, b, t)Same
clamp(v, lo, hi)clamp(v, lo, hi)Same
smoothstep(e0, e1, x)smoothstep(e0, e1, x)Same
step(edge, x)step(edge, x)Same
mod(x, y)fmod(x, y)Different name
fract(x)fract(x)Same
inversesqrt(x)rsqrt(x)Different name
atan(y, x)atan2(y, x)Different name

Shader Structure Conversion

GLSL Vertex Shader:

#version 300 es
precision highp float;

layout(location = 0) in vec3 aPosition;
layout(location = 1) in vec2 aTexCoord;

uniform mat4 uModelViewProjection;

out vec2 vTexCoord;

void main() {
    gl_Position = uModelViewProjection * vec4(aPosition, 1.0);
    vTexCoord = aTexCoord;
}

MSL Vertex Shader:

#include <metal_stdlib>
using namespace metal;

struct VertexIn {
    float3 position [[attribute(0)]];
    float2 texCoord [[attribute(1)]];
};

struct VertexOut {
    float4 position [[position]];
    float2 texCoord;
};

struct Uniforms {
    float4x4 modelViewProjection;
};

vertex VertexOut vertexShader(
    VertexIn in [[stage_in]],
    constant Uniforms& uniforms [[buffer(1)]]
) {
    VertexOut out;
    out.position = uniforms.modelViewProjection * float4(in.position, 1.0);
    out.texCoord = in.texCoord;
    return out;
}

GLSL Fragment Shader:

#version 300 es
precision highp float;

in vec2 vTexCoord;
uniform sampler2D uTexture;

out vec4 fragColor;

void main() {
    fragColor = texture(uTexture, vTexCoord);
}

MSL Fragment Shader:

fragment float4 fragmentShader(
    VertexOut in [[stage_in]],
    texture2d<float> tex [[texture(0)]],
    sampler samp [[sampler(0)]]
) {
    return tex.sample(samp, in.texCoord);
}

Precision Qualifiers

GLSL precision qualifiers have no direct MSL equivalent — MSL uses explicit types:

GLSLMSL Equivalent
lowp floathalf (16-bit)
mediump floathalf (16-bit)
highp floatfloat (32-bit)
lowp intshort (16-bit)
mediump intshort (16-bit)
highp intint (32-bit)

Buffer Alignment (Critical)

GLSL/C assumes:

  • vec3: 12 bytes, any alignment
  • vec4: 16 bytes

MSL requires:

  • float3: 12 bytes storage, 16-byte aligned
  • float4: 16 bytes storage, 16-byte aligned

Solution: Use simd types in Swift for CPU-GPU shared structs:

import simd

struct Uniforms {
    var modelViewProjection: simd_float4x4  // Correct alignment
    var cameraPosition: simd_float3         // 16-byte aligned
    var padding: Float = 0                   // Explicit padding if needed
}

Or use packed types in MSL (slower):

struct VertexPacked {
    packed_float3 position;  // 12 bytes, no padding
    packed_float2 texCoord;  // 8 bytes
};

Part 2: HLSL to MSL Conversion

Type Mappings

HLSLMSLNotes
floatfloat
float2float2
float3float3
float4float4
halfhalf
intint
uintuint
boolbool
float2x2float2x2
float3x3float3x3
float4x4float4x4
Texture2Dtexture2d<float>
Texture3Dtexture3d<float>
TextureCubetexturecube<float>
SamplerStatesampler
RWTexture2Dtexture2d<float, access::read_write>
RWBufferdevice float* [[buffer(n)]]
StructuredBufferconstant T* [[buffer(n)]]
RWStructuredBufferdevice T* [[buffer(n)]]

Semantic Mappings

HLSL SemanticMSL Attribute
SV_Position[[position]]
SV_Target0Return value / [[color(0)]]
SV_Target1[[color(1)]]
SV_Depth[[depth(any)]]
SV_VertexID[[vertex_id]]
SV_InstanceID[[instance_id]]
SV_IsFrontFace[[front_facing]]
SV_SampleIndex[[sample_id]]
SV_PrimitiveID[[primitive_id]]
SV_DispatchThreadID[[thread_position_in_grid]]
SV_GroupThreadID[[thread_position_in_threadgroup]]
SV_GroupID[[threadgroup_position_in_grid]]
SV_GroupIndex[[thread_index_in_threadgroup]]

Function Mappings

HLSLMSLNotes
tex.Sample(samp, uv)tex.sample(samp, uv)Lowercase
tex.SampleLevel(samp, uv, lod)tex.sample(samp, uv, level(lod))
tex.SampleGrad(samp, uv, ddx, ddy)tex.sample(samp, uv, gradient2d(ddx, ddy))
tex.Load(coord)tex.read(coord.xy, coord.z)Split coord
mul(a, b)a * bOperator
saturate(x)saturate(x)Same
lerp(a, b, t)mix(a, b, t)Different name
frac(x)fract(x)Different name
ddx(v)dfdx(v)Different name
ddy(v)dfdy(v)Different name
clip(x)if (x < 0) discard_fragment()Manual
discarddiscard_fragment()Function call

Metal Shader Converter (DirectX → Metal)

Apple's official tool for converting DXIL (compiled HLSL) to Metal libraries.

Requirements:

  • macOS 13+ with Xcode 15+
  • OR Windows 10+ with VS 2019+
  • Target devices: Argument Buffers Tier 2 (macOS 14+, iOS 17+)

Workflow:

# Step 1: Compile HLSL to DXIL using DXC
dxc -T vs_6_0 -E MainVS -Fo vertex.dxil shader.hlsl
dxc -T ps_6_0 -E MainPS -Fo fragment.dxil shader.hlsl

# Step 2: Convert DXIL to Metal library
metal-shaderconverter vertex.dxil -o vertex.metallib
metal-shaderconverter fragment.dxil -o fragment.metallib

# Step 3: Load in Swift
let vertexLib = try device.makeLibrary(URL: vertexURL)
let fragmentLib = try device.makeLibrary(URL: fragmentURL)

Key Options:

OptionPurpose
-o <file>Output metallib path
--minimum-gpu-familyTarget GPU family
--minimum-os-build-versionMinimum OS version
--vertex-stage-inSeparate vertex fetch function
-dualSourceBlendingEnable dual-source blending

Supported Shader Models: SM 6.0 - 6.6 (with limitations on 6.6 features)

Part 3: OpenGL API to Metal API

View/Context Setup

OpenGLMetal
NSOpenGLViewMTKView
GLKViewMTKView
EAGLContextMTLDevice + MTLCommandQueue
CGLContextObjMTLDevice

Resource Creation

OpenGLMetal
glGenBuffers + glBufferDatadevice.makeBuffer(bytes:length:options:)
glGenTextures + glTexImage2Ddevice.makeTexture(descriptor:) + texture.replace(region:...)
glGenFramebuffersMTLRenderPassDescriptor
glGenVertexArraysMTLVertexDescriptor
glCreateShader + glCompileShaderBuild-time compilation → MTLLibrary
glCreateProgram + glLinkProgramMTLRenderPipelineDescriptorMTLRenderPipelineState

State Management

OpenGLMetal
glEnable(GL_DEPTH_TEST)MTLDepthStencilDescriptorMTLDepthStencilState
glDepthFunc(GL_LESS)descriptor.depthCompareFunction = .less
glEnable(GL_BLEND)pipelineDescriptor.colorAttachments[0].isBlendingEnabled = true
glBlendFuncsourceRGBBlendFactor, destinationRGBBlendFactor
glCullFaceencoder.setCullMode(.back)
glFrontFaceencoder.setFrontFacing(.counterClockwise)
glViewportencoder.setViewport(MTLViewport(...))
glScissorencoder.setScissorRect(MTLScissorRect(...))

Draw Commands

OpenGLMetal
glDrawArrays(mode, first, count)encoder.drawPrimitives(type:vertexStart:vertexCount:)
glDrawElements(mode, count, type, indices)encoder.drawIndexedPrimitives(type:indexCount:indexType:indexBuffer:indexBufferOffset:)
glDrawArraysInstancedencoder.drawPrimitives(type:vertexStart:vertexCount:instanceCount:)
glDrawElementsInstancedencoder.drawIndexedPrimitives(...instanceCount:)

Primitive Types

OpenGLMetal
GL_POINTS.point
GL_LINES.line
GL_LINE_STRIP.lineStrip
GL_TRIANGLES.triangle
GL_TRIANGLE_STRIP.triangleStrip
GL_TRIANGLE_FANN/A (decompose to triangles)

Part 4: Complete Setup Examples

MTKView Setup (Recommended)

import MetalKit

class GameViewController: UIViewController {
    var metalView: MTKView!
    var renderer: Renderer!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create Metal view
        guard let device = MTLCreateSystemDefaultDevice() else {
            fatalError("Metal not supported")
        }

        metalView = MTKView(frame: view.bounds, device: device)
        metalView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        metalView.colorPixelFormat = .bgra8Unorm
        metalView.depthStencilPixelFormat = .depth32Float
        metalView.clearColor = MTLClearColor(red: 0, green: 0, blue: 0, alpha: 1)
        metalView.preferredFramesPerSecond = 60
        view.addSubview(metalView)

        // Create renderer
        renderer = Renderer(metalView: metalView)
        metalView.delegate = renderer
    }
}

class Renderer: NSObject, MTKViewDelegate {
    let device: MTLDevice
    let commandQueue: MTLCommandQueue
    var pipelineState: MTLRenderPipelineState!
    var depthState: MTLDepthStencilState!
    var vertexBuffer: MTLBuffer!

    init(metalView: MTKView) {
        device = metalView.device!
        commandQueue = device.makeCommandQueue()!
        super.init()

        buildPipeline(metalView: metalView)
        buildDepthStencil()
        buildBuffers()
    }

    private func buildPipeline(metalView: MTKView) {
        let library = device.makeDefaultLibrary()!

        let descriptor = MTLRenderPipelineDescriptor()
        descriptor.vertexFunction = library.makeFunction(name: "vertexShader")
        descriptor.fragmentFunction = library.makeFunction(name: "fragmentShader")
        descriptor.colorAttachments[0].pixelFormat = metalView.colorPixelFormat
        descriptor.depthAttachmentPixelFormat = metalView.depthStencilPixelFormat

        // Vertex descriptor (matches shader's VertexIn struct)
        let vertexDescriptor = MTLVertexDescriptor()
        vertexDescriptor.attributes[0].format = .float3
        vertexDescriptor.attributes[0].offset = 0
        vertexDescriptor.attributes[0].bufferIndex = 0
        vertexDescriptor.attributes[1].format = .float2
        vertexDescriptor.attributes[1].offset = MemoryLayout<SIMD3<Float>>.stride
        vertexDescriptor.attributes[1].bufferIndex = 0
        vertexDescriptor.layouts[0].stride = MemoryLayout<Vertex>.stride
        descriptor.vertexDescriptor = vertexDescriptor

        pipelineState = try! device.makeRenderPipelineState(descriptor: descriptor)
    }

    private func buildDepthStencil() {
        let descriptor = MTLDepthStencilDescriptor()
        descriptor.depthCompareFunction = .less
        descriptor.isDepthWriteEnabled = true
        depthState = device.makeDepthStencilState(descriptor: descriptor)
    }

    func mtkView(_ view: MTKView, drawableSizeWillChange size: CGSize) {
        // Handle resize
    }

    func draw(in view: MTKView) {
        guard let drawable = view.currentDrawable,
              let descriptor = view.currentRenderPassDescriptor,
              let commandBuffer = commandQueue.makeCommandBuffer(),
              let encoder = commandBuffer.makeRenderCommandEncoder(descriptor: descriptor) else {
            return
        }

        encoder.setRenderPipelineState(pipelineState)
        encoder.setDepthStencilState(depthState)
        encoder.setVertexBuffer(vertexBuffer, offset: 0, index: 0)
        encoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: vertexCount)
        encoder.endEncoding()

        commandBuffer.present(drawable)
        commandBuffer.commit()
    }
}

CAMetalLayer Setup (Custom Control)

import Metal
import QuartzCore

class MetalLayerView: UIView {
    var metalLayer: CAMetalLayer!
    var device: MTLDevice!
    var commandQueue: MTLCommandQueue!
    var displayLink: CADisplayLink?

    override class var layerClass: AnyClass { CAMetalLayer.self }

    override init(frame: CGRect) {
        super.init(frame: frame)
        setup()
    }

    private func setup() {
        device = MTLCreateSystemDefaultDevice()!
        commandQueue = device.makeCommandQueue()!

        metalLayer = layer as? CAMetalLayer
        metalLayer.device = device
        metalLayer.pixelFormat = .bgra8Unorm
        metalLayer.framebufferOnly = true

        displayLink = CADisplayLink(target: self, selector: #selector(render))
        displayLink?.add(to: .main, forMode: .common)
    }

    override func layoutSubviews() {
        super.layoutSubviews()
        metalLayer.drawableSize = CGSize(
            width: bounds.width * contentScaleFactor,
            height: bounds.height * contentScaleFactor
        )
    }

    @objc func render() {
        guard let drawable = metalLayer.nextDrawable(),
              let commandBuffer = commandQueue.makeCommandBuffer() else {
            return
        }

        let descriptor = MTLRenderPassDescriptor()
        descriptor.colorAttachments[0].texture = drawable.texture
        descriptor.colorAttachments[0].loadAction = .clear
        descriptor.colorAttachments[0].storeAction = .store
        descriptor.colorAttachments[0].clearColor = MTLClearColor(red: 0, green: 0, blue: 0, alpha: 1)

        guard let encoder = commandBuffer.makeRenderCommandEncoder(descriptor: descriptor) else {
            return
        }

        // Draw commands here
        encoder.endEncoding()

        commandBuffer.present(drawable)
        commandBuffer.commit()
    }
}

Compute Shader Setup

class ComputeProcessor {
    let device: MTLDevice
    let commandQueue: MTLCommandQueue
    var computePipeline: MTLComputePipelineState!

    init() {
        device = MTLCreateSystemDefaultDevice()!
        commandQueue = device.makeCommandQueue()!

        let library = device.makeDefaultLibrary()!
        let function = library.makeFunction(name: "computeKernel")!
        computePipeline = try! device.makeComputePipelineState(function: function)
    }

    func process(input: MTLBuffer, output: MTLBuffer, count: Int) {
        let commandBuffer = commandQueue.makeCommandBuffer()!
        let encoder = commandBuffer.makeComputeCommandEncoder()!

        encoder.setComputePipelineState(computePipeline)
        encoder.setBuffer(input, offset: 0, index: 0)
        encoder.setBuffer(output, offset: 0, index: 1)

        let threadGroupSize = MTLSize(width: 256, height: 1, depth: 1)
        let threadGroups = MTLSize(
            width: (count + 255) / 256,
            height: 1,
            depth: 1
        )

        encoder.dispatchThreadgroups(threadGroups, threadsPerThreadgroup: threadGroupSize)
        encoder.endEncoding()

        commandBuffer.commit()
        commandBuffer.waitUntilCompleted()
    }
}
// Compute shader
kernel void computeKernel(
    device float* input [[buffer(0)]],
    device float* output [[buffer(1)]],
    uint id [[thread_position_in_grid]]
) {
    output[id] = input[id] * 2.0;
}

Part 5: Storage Modes & Synchronization

Buffer Storage Modes

ModeCPU AccessGPU AccessUse Case
.sharedRead/WriteRead/WriteSmall dynamic data, uniforms
.privateNoneRead/WriteStatic assets, render targets
.managed (macOS)Read/WriteRead/WriteLarge buffers with partial updates
// Shared: CPU and GPU both access (iOS typical)
let uniformBuffer = device.makeBuffer(length: size, options: .storageModeShared)

// Private: GPU only (best for static geometry)
let vertexBuffer = device.makeBuffer(bytes: vertices, length: size, options: .storageModePrivate)

// Managed: Explicit sync (macOS)
#if os(macOS)
let buffer = device.makeBuffer(length: size, options: .storageModeManaged)
// After CPU write:
buffer.didModifyRange(0..<size)
#endif

Texture Storage Modes

let descriptor = MTLTextureDescriptor.texture2DDescriptor(
    pixelFormat: .rgba8Unorm,
    width: 1024,
    height: 1024,
    mipmapped: true
)

// For static textures (loaded once)
descriptor.storageMode = .private
descriptor.usage = [.shaderRead]

// For render targets
descriptor.storageMode = .private
descriptor.usage = [.renderTarget, .shaderRead]

// For CPU-readable (screenshots, readback)
descriptor.storageMode = .shared  // iOS
descriptor.storageMode = .managed  // macOS
descriptor.usage = [.shaderRead, .shaderWrite]

Resources

WWDC: 2016-00602, 2018-00604, 2019-00611

Docs: /metal/migrating-opengl-code-to-metal, /metal/shader-converter, /metalkit/mtkview

Skills: axiom-metal-migration, axiom-metal-migration-diag


Last Updated: 2025-12-29 Platforms: iOS 12+, macOS 10.14+, tvOS 12+ Status: Complete shader conversion and API mapping reference