Metal file as part of an iOS framework

Question

I am trying to create a framework that works with METAL Api (iOS). I am pretty new to this platform and I would like to know how to build the framework to work with .metal files

Answer 1

The approach suggested by the questioner could not possibly work (hence, the lack of sample code). A Metal shader (.metal) is just a collection of functions, it does not a MTLLibrary (.metallib) make. Here is working code that compiles a Metal shader from a character (const char *) array (not the same as NSString); it is followed by instructions for converting a .metal file to a .metallib file prior to runtime.

Compiling a Metal Shader during Runtime

The following sample could also be used to provide users with a Shader Editor, and can allow you to update just the shader portion of your app without requiring the user to update the entire app:

NSError* error = NULL;
const char* vshSource =
"using namespace metal;\n"
"typedef struct {\n"
"    packed_float2 position;\n"
"    packed_float2 texcoord;\n"
"} Vertex;\n"

"typedef struct {\n"
"    float3x3 matrix;\n"
"    float3 offset;\n"
"} ColorConversion;\n"

"typedef struct {\n"
"    float4 position [[position]];\n"
"    float2 texcoord;\n"
"} Varyings;\n"

"vertex Varyings vertexPassthrough(\n"
"device Vertex* verticies [[ buffer(0) ]],\n"
"unsigned int vid [[ vertex_id ]]\n"
") {\n"
"   Varyings out;\n"
"   device Vertex& v = verticies[vid];\n"
"    out.position = float4(float2(v.position), 0.0, 1.0);\n"
"    out.texcoord = v.texcoord;\n"
"    return out;\n"
"}\n";

const char* fshSource =
"using namespace metal;\n"
"typedef struct {\n"
    "packed_float2 position;\n"
    "packed_float2 texcoord;\n"
"} Vertex;\n"

"typedef struct {\n"
    "float3x3 matrix;\n"
    "float3 offset;\n"
"} ColorConversion;\n"

"typedef struct {\n"
    "float4 position [[position]];\n"
    "float2 texcoord;\n"
"} Varyings;\n"

"fragment half4 fragmentColorConversion(\n"
                                       "Varyings in [[ stage_in ]],\n"
                                       "texture2d textureBGRA [[ texture(0) ]],\n"
                                       "constant ColorConversion &colorConversion [[ buffer(0) ]]\n"
                                       ") {\n"
    "constexpr sampler s(address::clamp_to_edge, filter::linear);\n"
    "return half4(half3(textureBGRA.sample(s, in.texcoord).rgb), 1.0);\n"
"}\n";

id  vertexProgram;
id  vertexLibrary = [_device newLibraryWithSource:[NSString stringWithUTF8String:vshSource] options:NULL error:&error];
if (NULL != vertexLibrary)
{
    vertexProgram = [vertexLibrary newFunctionWithName:@"vertexPassthrough"];
} else {
    NSLog(@"Error compiling vertex program: %@", error.description);
}

id  fragmentProgram;
id  fragmentLibrary = [_device newLibraryWithSource:[NSString stringWithUTF8String:fshSource] options:NULL error:&error];
if (NULL != fragmentLibrary)
{
    fragmentProgram = [fragmentLibrary newFunctionWithName:@"fragmentColorConversion"];
}  else {
    NSLog(@"Error compiling fragment program: %@", error.description);
}

The following are excerpts from an Apple Developer Documentation publication; although the information is relatively rudimentary, use it as a basis for a common framework shared by you and your audience when communicating about its subject matter.

Creating Libraries During the App Build Process

The accepted answer is flat-out wrong for the same reasons; and, it's claims about performance trade-offs are questionable. Here are the only definitive statements that can be made about compiling Metal shaders and creating Metal libraries, followed by actual code:

Functions and Libraries

This chapter describes how to create a MTLFunction object as a reference to a Metal shader or compute function and how to organize and access functions with a MTLLibrary object.

MTLFunction Represents a Shader or Compute Function

A MTLFunction object represents a single function that is written in the Metal shading language and executed on the GPU as part of a graphics or compute pipeline. For details on the Metal shading language, see the Metal Shading Language Guide.

To pass data or state between the Metal runtime and a graphics or compute function written in the Metal shading language, you assign an argument index for textures, buffers, and samplers. The argument index identifies which texture, buffer, or sampler is being referenced by both the Metal runtime and Metal shading code.

For a rendering pass, you specify a MTLFunction object for use as a vertex or fragment shader in a MTLRenderPipelineDescriptor object, as detailed in Creating a Render Pipeline State. For a compute pass, you specify a MTLFunction object when creating a MTLComputePipelineState object for a target device, as described in Specify a Compute State and Resources for a Compute Command Encoder.

A Library Is a Repository of Functions

A MTLLibrary object represents a repository of one or more MTLFunction objects. A single MTLFunction object represents one Metal function that has been written with the shading language. In the Metal shading language source code, any function that uses a Metal function qualifier (vertex, fragment, or kernel) can be represented by a MTLFunction object in a library. A Metal function without one of these function qualifiers cannot be directly represented by a MTLFunction object, although it can called by another function within the shader.

The MTLFunction objects in a library can be created from either of these sources:

• Metal shading language code that was compiled into a binary library format during the app build process.
• A text string containing Metal shading language source code that is compiled by the app at runtime.

Compiling shader language source files and building a library (.metallib file) during the app build process achieves better app performance than compiling shader source code at runtime. You can build a library within Xcode or by using command line utilities.

Using Xcode to Build a Library

Any shader source files that are in your project are automatically used to generate the default library, which you can access from Metal framework code with the newDefaultLibrary method of MTLDevice.

Using Command Line Utilities to Build a Library

Figure 8-1 shows the command line utilities that form the compiler toolchain for Metal shader source code. When you include .metal files in your project, Xcode invokes these tools to build a library file that you can access in your app at run time.

To compile shader source into a library without using Xcode:

1. Use the metal tool to compile each .metal file into a single .air file, which stores an intermediate representation (IR) of shader language code.
2. Optionally, use the metal-ar tool to archive several .air files together into a single .metalar file. (metal-ar is similar to the Unix ar.)
3. Use the metallib tool to build a Metal .metallib library file from IR .air files or from archive .metalar files.

Example: Building a Library File with Command Line Utilities

xcrun -sdk macosx metal MyLibrary.metal -o MyLibrary.air
    xcrun -sdk macosx metallib MyLibrary.air -o MyLibrary.metallib

To access the resulting library in framework code, call the newLibraryWithFile:error: method:

NSError *libraryError = NULL;
NSString *libraryFile = [[NSBundle mainBundle] pathForResource:@"MyLibrary" ofType:@"metallib"];
id  myLibrary = [_device newLibraryWithFile:libraryFile error:&libraryError];
if (!myLibrary) {
    NSLog(@"Library error: %@", libraryError);
}