--- title: Shader libraries framework: metal role: collectionGroup role_heading: API Collection path: metal/shader-libraries --- # Shader libraries Manage and load your app’s Metal shaders. ## Overview 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 libraries](metal/metal-libraries.md) - [Metal dynamic libraries](metal/metal-dynamic-libraries.md) - [Metal binary archives](metal/metal-binary-archives.md) - [MTL4Compiler](metal/mtl4compiler.md) - [MTL4CompilerDescriptor](metal/mtl4compilerdescriptor.md) - [MTL4CompilerTaskOptions](metal/mtl4compilertaskoptions.md) - [MTL4CompilerTaskStatus](metal/mtl4compilertaskstatus.md) - [MTL4Archive](metal/mtl4archive.md) - [MTL4BinaryFunction](metal/mtl4binaryfunction.md) - [MTL4BinaryFunctionDescriptor](metal/mtl4binaryfunctiondescriptor.md) - [MTL4BinaryFunctionOptions](metal/mtl4binaryfunctionoptions.md) - [MTL4PipelineStageDynamicLinkingDescriptor](metal/mtl4pipelinestagedynamiclinkingdescriptor.md) ### Pipeline compilation - [MTL4BlendState](metal/mtl4blendstate.md) - [MTL4FunctionDescriptor](metal/mtl4functiondescriptor.md) - [MTL4IndirectCommandBufferSupportState](metal/mtl4indirectcommandbuffersupportstate.md) - [MTL4LibraryDescriptor](metal/mtl4librarydescriptor.md) - [MTL4LibraryFunctionDescriptor](metal/mtl4libraryfunctiondescriptor.md) - [MTL4LogicalToPhysicalColorAttachmentMappingState](metal/mtl4logicaltophysicalcolorattachmentmappingstate.md) - [MTL4NewBinaryFunctionCompletionHandler](metal/mtl4newbinaryfunctioncompletionhandler.md) - [MTL4NewMachineLearningPipelineStateCompletionHandler](metal/mtl4newmachinelearningpipelinestatecompletionhandler.md) - [MTL4ShaderReflection](metal/mtl4shaderreflection.md) - [MTL4SpecializedFunctionDescriptor](metal/mtl4specializedfunctiondescriptor.md) - [MTL4AlphaToCoverageState](metal/mtl4alphatocoveragestate.md) - [MTL4AlphaToOneState](metal/mtl4alphatoonestate.md) - [MTL4StaticLinkingDescriptor](metal/mtl4staticlinkingdescriptor.md) - [MTL4StitchedFunctionDescriptor](metal/mtl4stitchedfunctiondescriptor.md) - [MTLFunctionReflection](metal/mtlfunctionreflection.md) - [MTLNewDynamicLibraryCompletionHandler](metal/mtlnewdynamiclibrarycompletionhandler.md) ### Pipeline harvesting - [MTL4PipelineDataSetSerializer](metal/mtl4pipelinedatasetserializer.md) - [MTL4PipelineDataSetSerializerConfiguration](metal/mtl4pipelinedatasetserializerconfiguration.md) - [MTL4PipelineDataSetSerializerDescriptor](metal/mtl4pipelinedatasetserializerdescriptor.md) - [MTL4PipelineDescriptor](metal/mtl4pipelinedescriptor.md) - [MTL4PipelineOptions](metal/mtl4pipelineoptions.md) ### Shader library management - [MTLLibrary](metal/mtllibrary.md) - [MTLDynamicLibrary](metal/mtldynamiclibrary.md) - [MTLBinaryArchive](metal/mtlbinaryarchive.md) - [MTLCompileOptions](metal/mtlcompileoptions.md) - [MTLLibraryType](metal/mtllibrarytype.md) - [MTLLanguageVersion](metal/mtllanguageversion.md) - [MTLCompileSymbolVisibility](metal/mtlcompilesymbolvisibility.md) - [MTLLibraryOptimizationLevel](metal/mtllibraryoptimizationlevel.md) ### Shader functions - [MTLFunctionDescriptor](metal/mtlfunctiondescriptor.md) - [MTLFunction](metal/mtlfunction.md) - [MTLFunctionHandle](metal/mtlfunctionhandle.md) - [MTLVisibleFunctionTableDescriptor](metal/mtlvisiblefunctiontabledescriptor.md) - [MTLVisibleFunctionTable](metal/mtlvisiblefunctiontable.md) - [MTLIntersectionFunctionDescriptor](metal/mtlintersectionfunctiondescriptor.md) - [MTLIntersectionFunctionTableDescriptor](metal/mtlintersectionfunctiontabledescriptor.md) - [MTLIntersectionFunctionTable](metal/mtlintersectionfunctiontable.md) ### Stitched function libraries - [Customizing shaders using function pointers and stitching](metal/customizing-shaders-using-function-pointers-and-stitching.md) - [MTLStitchedLibraryDescriptor](metal/mtlstitchedlibrarydescriptor.md) - [MTLFunctionStitchingGraph](metal/mtlfunctionstitchinggraph.md) - [MTLFunctionStitchingInputNode](metal/mtlfunctionstitchinginputnode.md) - [MTLFunctionStitchingFunctionNode](metal/mtlfunctionstitchingfunctionnode.md) - [MTLFunctionStitchingNode](metal/mtlfunctionstitchingnode.md) - [MTLFunctionStitchingAttributeAlwaysInline](metal/mtlfunctionstitchingattributealwaysinline.md) - [MTLFunctionStitchingAttribute](metal/mtlfunctionstitchingattribute.md) ### Compile-time variant functions - [MTLFunctionConstant](metal/mtlfunctionconstant.md) - [MTLFunctionConstantValues](metal/mtlfunctionconstantvalues.md) ### Introspection data - [MTLComputePipelineReflection](metal/mtlcomputepipelinereflection.md) - [MTLAutoreleasedComputePipelineReflection](metal/mtlautoreleasedcomputepipelinereflection.md) - [MTLRenderPipelineReflection](metal/mtlrenderpipelinereflection.md) - [MTLAutoreleasedRenderPipelineReflection](metal/mtlautoreleasedrenderpipelinereflection.md) - [MTLBindingType](metal/mtlbindingtype.md) - [MTLBinding](metal/mtlbinding.md) - [MTLBindingAccess](metal/mtlbindingaccess.md) - [MTLBufferBinding](metal/mtlbufferbinding.md) - [MTLTextureBinding](metal/mtltexturebinding.md) - [MTLThreadgroupBinding](metal/mtlthreadgroupbinding.md) - [MTLObjectPayloadBinding](metal/mtlobjectpayloadbinding.md) ### Function arguments - [MTLAttribute](metal/mtlattribute.md) - [MTLVertexAttribute](metal/mtlvertexattribute.md) - [MTLArgument](metal/mtlargument.md) - [MTLAutoreleasedArgument](metal/mtlautoreleasedargument.md) - [MTLArgumentType](metal/mtlargumenttype.md) - [MTLArgumentAccess](metal/mtlargumentaccess.md) ### Shader types - [MTLType](metal/mtltype.md) - [MTLDataType](metal/mtldatatype.md) - [MTLArrayType](metal/mtlarraytype.md) - [MTLStructType](metal/mtlstructtype.md) - [MTLStructMember](metal/mtlstructmember.md) - [MTLPointerType](metal/mtlpointertype.md) - [MTLTextureReferenceType](metal/mtltexturereferencetype.md) ### Shader logging - [MTLLogStateDescriptor](metal/mtllogstatedescriptor.md) - [MTLLogState](metal/mtllogstate.md) ### Errors - [MTLLibraryError](metal/mtllibraryerror-swift.struct.md) - [MTLLibraryError.Code](metal/mtllibraryerror-swift.struct/code.md) - [MTLLibraryErrorDomain](metal/mtllibraryerrordomain.md) ## See Also ### Shader compilation and libraries - [Using the Metal 4 compilation API](metal/using-the-metal-4-compilation-api.md) - [Using function specialization to build pipeline variants](metal/using-function-specialization-to-build-pipeline-variants.md)