Shader libraries
Manage and load your app’s Metal shaders.
Overview
A Metal library represents a collection of one or more shaders. Xcode creates a library from the shader source files in a project, a Metal intermediate representation (IR) file, or a binary archive file. You can also create IR files from Metal source code by running the Metal compiler in a command-line environment.
Apps create the default library instance by calling a Metal device’s makeDefaultLibrary() method. The default library contains all the shaders from a project’s shader source files, which Xcode compiles at build time. Apps create additional libraries by passing an IR file to an MTLDevice instance’s makeLibrary(URL:) method or one of its sibling methods. The device can also create a library directly from source code by passing it as a string to the makeLibrary(source:options:) method. See Shader library and archive creation for more information.
You can apply a shader from a library to a pipeline state’s entry point, such as the computeFunction property for a compute pass. Start by retrieving an MTLFunction instance from a library, which is a reference to the library’s shader, by calling its makeFunction(name:) method or a sibling method. Then set the function instance to the appropriate property of a pipeline descriptor. For example, an app can retrieve a vertex stage’s entry point shader from a library and assign it to the vertexFunction property of an MTLRenderPipelineDescriptor.
Dynamic libraries are a collection of other shaders, typically utility functions, that support the entry point shaders for a pipeline state. To create a dynamic library, pass an MTLLibrary instance to a device’s makeDynamicLibrary(library:) method, or pass a file URL to makeDynamicLibrary(url:). Add a dynamic library to a pipeline state by including it in an array of a pipeline descriptor’s preloaded libraries property. For example, if a vertex shader calls a shader in a dynamic library, directly or indirectly, add that dynamic library to the vertexPreloadedLibraries property’s array. You can also build dynamic libraries with the Metal compiler in Terminal.
Binary archives are precompiled static libraries for specific GPU architectures that allow you to avoid the cost of runtime shader compilation. Because Metal automatically builds and caches shaders on the device running an app, use binary archives as part of your distributed app, or deliver them through content updates. See Creating binary archives from device-built pipeline state objects for more information on how to build and distribute binary archives for any device that supports Metal.
Topics
Shader compilation
Metal librariesMetal dynamic librariesMetal binary archivesMTL4CompilerMTL4CompilerDescriptorMTL4CompilerTaskOptionsMTL4CompilerTaskStatusMTL4ArchiveMTL4BinaryFunctionMTL4BinaryFunctionDescriptorMTL4BinaryFunctionOptionsMTL4PipelineStageDynamicLinkingDescriptor
Pipeline compilation
MTL4BlendStateMTL4FunctionDescriptorMTL4IndirectCommandBufferSupportStateMTL4LibraryDescriptorMTL4LibraryFunctionDescriptorMTL4LogicalToPhysicalColorAttachmentMappingStateMTL4NewBinaryFunctionCompletionHandlerMTL4NewMachineLearningPipelineStateCompletionHandlerMTL4ShaderReflectionMTL4SpecializedFunctionDescriptorMTL4AlphaToCoverageStateMTL4AlphaToOneStateMTL4StaticLinkingDescriptorMTL4StitchedFunctionDescriptorMTLFunctionReflectionMTLNewDynamicLibraryCompletionHandler
Pipeline harvesting
MTL4PipelineDataSetSerializerMTL4PipelineDataSetSerializerConfigurationMTL4PipelineDataSetSerializerDescriptorMTL4PipelineDescriptorMTL4PipelineOptions
Shader library management
MTLLibraryMTLDynamicLibraryMTLBinaryArchiveMTLCompileOptionsMTLLibraryTypeMTLLanguageVersionMTLCompileSymbolVisibilityMTLLibraryOptimizationLevel
Shader functions
MTLFunctionDescriptorMTLFunctionMTLFunctionHandleMTLVisibleFunctionTableDescriptorMTLVisibleFunctionTableMTLIntersectionFunctionDescriptorMTLIntersectionFunctionTableDescriptorMTLIntersectionFunctionTable
Stitched function libraries
Customizing shaders using function pointers and stitchingMTLStitchedLibraryDescriptorMTLFunctionStitchingGraphMTLFunctionStitchingInputNodeMTLFunctionStitchingFunctionNodeMTLFunctionStitchingNodeMTLFunctionStitchingAttributeAlwaysInlineMTLFunctionStitchingAttribute
Compile-time variant functions
Introspection data
MTLComputePipelineReflectionMTLAutoreleasedComputePipelineReflectionMTLRenderPipelineReflectionMTLAutoreleasedRenderPipelineReflectionMTLBindingTypeMTLBindingMTLBindingAccessMTLBufferBindingMTLTextureBindingMTLThreadgroupBindingMTLObjectPayloadBinding