Metal Framework

This article applies to macOS only.

See also: Multiplatform Programming Guide

Overview

Graphics processors are designed to quickly render graphics and perform data-parallel calculations. The Apple Metal framework allows you to communicate directly with the graphics processor available on a device. Applications that render complex scenes or that perform advanced scientific calculations can use this power to achieve maximum performance. Such applications include:

• Games that render sophisticated 3D environments;
• Video processing applications, like Final Cut Pro;
• Data-crunching applications, such as those used to perform scientific research.

Metal works hand-in-hand with other Apple frameworks that supplement its capability. MetalKit simplifies the task of getting your Metal content onscreen. Metal Performance Shaders implement custom rendering functions or to take advantage of a large library of existing functions.

Many high level Apple frameworks are built on top of Metal to take advantage of its performance, including Core Image, SpriteKit, and SceneKit. Using one of these high-level frameworks shields you from the details of graphics processor programming, but writing custom Metal code enables you to achieve the highest level of performance.

Metal and Lazarus

Metal support in Lazarus uses Ryan Joseph's lazmetalcontrol.

Requirements

• You will need to have the latest version of Lazarus installed on a macOS computer (or better yet, have the latest Lazarus SVN version).
• You will need to download the Lazarus Metal Package (lazmetalcontrol) by Ryan Joseph.
• From Lazarus, choose the Package menu -> Open Package File and select lazmetalcontrol.lpk - install this into Lazarus.
• To use Metal you will need macOS 10.11 (El Capitan) or later and a Mac computer that supports Metal - typically Macs from 2012 and later.

Errata

The Lazarus 2.0.6 release for macOS contained a regression for OpenGL support. See Bugtracker Issue #35797 GLCocoaNSContext.pas now requires "cocoa_extra" in the Uses section.

Lazarus Example Code

ChrisR has created a few Lazarus projects that can be compiled for Apple's Metal Framework. The projects can be downloaded from GitHub and will compile on Lazarus provided you have met the requirements outlined above.

Unfortunately the documentation is sparse, but both the main page and the line project include some useful information.

Most of the projects can also be compiled to support OpenGL 3.3 Core - providing support for Windows, Linux and older Macs. By keeping a thin layer for either OpenGL or Metal, one can retain most of the Lazarus write once, compile everywhere magic.

These example projects all use Lazarus. However, Ryan's repository also includes some examples of how to use Metal directly from Free Pascal without Lazarus.

See this Forum post with demo project for offscreen rendering in Metal.

Metal debugging in Xcode

If your Lazarus application uses Metal graphics, Igor Kokarev explains below how you can save a GPU trace to a file and then open it in Xcode to check the performance of Metal, view much useful information about your 3D commands and even see a visualization of your 3D scene. Note that this requires macOS 10.15 Catalina or newer and FPC 3.2.0.

Step 1 Download Ryan Joseph's lazmetalcontrol.

Step 2 Replace the file MTLCaptureManager.inc with this one:

{ Parsed from Metal.framework /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Metal.framework/Headers/MTLCaptureManager.h }

{$ifdef TYPES}
type
  MTLCaptureDescriptorPtr = ^MTLCaptureDescriptor;
  MTLCaptureManagerPtr = ^MTLCaptureManager;
{$endif}

{$ifdef EXTERNAL_SYMBOLS}
//var
//  MTLCaptureErrorDomain: NSErrorDomain; cvar; external;
{$endif}

{$ifdef TYPES}
type
  MTLCaptureError = NSInteger;
  MTLCaptureErrorPtr = ^MTLCaptureError;

const
  MTLCaptureErrorNotSupported = 1;
  MTLCaptureErrorAlreadyCapturing = 2;
  MTLCaptureErrorInvalidDescriptor = 3;

type
  MTLCaptureDestination = NSInteger;
  MTLCaptureDestinationPtr = ^MTLCaptureDestination;

const
  MTLCaptureDestinationDeveloperTools = 1;
  MTLCaptureDestinationGPUTraceDocument = 2;
{$endif}

{$ifdef CLASSES}

type
  MTLCaptureDescriptor = objcclass external (NSObject, NSCopyingProtocol)
  private
    _captureObject: id;
    _destination: MTLCaptureDestination;
    _outputURL: NSURL;
  public
    procedure setCaptureObject(newValue: id); message 'setCaptureObject:';
    function captureObject: id; message 'captureObject';
    procedure setDestination(newValue: MTLCaptureDestination); message 'setDestination:';
    function destination: MTLCaptureDestination; message 'destination';
    procedure setOutputURL(newValue: NSURL); message 'setOutputURL:';
    function outputURL: NSURL; message 'outputURL';

    { Adopted protocols }
    function copyWithZone (zone: NSZonePtr): id; message 'copyWithZone:';
  end;

type
  MTLCaptureManager = objcclass external (NSObject)
  private
    _isCapturing: objcbool;
    _defaultCaptureScope: MTLCaptureScopeProtocol;
  public
    class function sharedCaptureManager: MTLCaptureManager; message 'sharedCaptureManager';
    function init: id; message 'init'; { unavailable in macos, ios }
    function newCaptureScopeWithDevice (device: id): id; message 'newCaptureScopeWithDevice:';
    function newCaptureScopeWithCommandQueue (commandQueue: id): id; message 'newCaptureScopeWithCommandQueue:';
    function supportsDestination (destination: MTLCaptureDestination): objcbool; message 'supportsDestination:'; { available in macos(10.15), ios(13.0) }
    function startCaptureWithDescriptor_error (descriptor: MTLCaptureDescriptor; error: NSErrorPtr): objcbool; message 'startCaptureWithDescriptor:error:'; { available in macos(10.15), ios(13.0) }
    procedure startCaptureWithDevice (device: id); message 'startCaptureWithDevice:'; deprecated 'Use startCaptureWithDescriptor:error: instead in macos(10.13, 10.15), ios(11.0, 13.0)';
    procedure startCaptureWithCommandQueue (commandQueue: id); message 'startCaptureWithCommandQueue:'; deprecated 'Use startCaptureWithDescriptor:error: instead in macos(10.13, 10.15), ios(11.0, 13.0)';
    procedure startCaptureWithScope (captureScope: id); message 'startCaptureWithScope:'; deprecated 'Use startCaptureWithDescriptor:error: instead in macos(10.13, 10.15), ios(11.0, 13.0)';
    procedure stopCapture; message 'stopCapture';
    procedure setDefaultCaptureScope(newValue: id); message 'setDefaultCaptureScope:';
    function defaultCaptureScope: id; message 'defaultCaptureScope';
    function isCapturing: objcbool; message 'isCapturing';
  end;
{$endif}

This updated header includes a new Cocoa interface - MTLCaptureDescriptor.

Step 3 Insert a new text line in the existing file DefinedClassesMetal.pas:

MTLCaptureDescriptor = objcclass external;

Ryan will probably include both changes (Steps 2 and 3) in a future update to his Metal framework.

Step 4 Add this key and value to the Info.plist file in your application bundle:

<key>MetalCaptureEnabled</key>
  <true/>

Note: remove this key when you do a release build for your application because this key has a small negative effect on Metal performance.

Step 5 Add the following code for your Metal application:

captureManager:    MTLCaptureManager;
captureDescriptor: MTLCaptureDescriptor;

procedure TMetalContext.StartMetalDebug;
var
  nserr:   NSError;
  //str:     string;
begin
  // GPU trace for debugging of Metal
  captureManager := MTLCaptureManager.sharedCaptureManager;
  if captureManager.supportsDestination(MTLCaptureDestinationGPUTraceDocument) then 
    begin
      captureDescriptor := MTLCaptureDescriptor.alloc.init.autorelease;
      captureDescriptor.SetCaptureObject(device);
      captureDescriptor.SetDestination(MTLCaptureDestinationGPUTraceDocument);
      captureDescriptor.setOutputURL(NSURL.URLWithString(StrToNSStr('file:///Users/mac/Development/myapp.gputrace')));

      if not captureManager.startCaptureWithDescriptor_error(captureDescriptor, @nserr) then 
        begin
          // Metal captiring failed.
          exit;
        end;
     
      //str := NSStrToStr(nserr.localizedDescription);
    end;
end;

procedure TMetalContext.StopMetalDebug;
begin
  captureManager.stopCapture;
end;

A saved file with GPU trace should use the .gputrace file extension.

When you call stopCapture() the application will save the *.gputrace file. Double click on this file in the Finder and it will be opened in Xcode for you to explore the Metal performance and 3D data.

As it is only possible to capture one frame at a time, just call the start and stop commands before and after you render each frame.

More information is available in the Apple documentation:

• Capturing GPU Command Data Programmatically.

External links

• Apple: Sample Code
• Apple: Metal Framework Documentation
• Apple: Metal Programming Guide
• Apple: Metal Best Practices Guide
• Apple: Metal Videos
• Apple: Metal Forum

• Apple: Porting Your Metal Code to Apple Silicon