Usually, when we talk about tools, we mean something for writing code, debugging, and profiling. But engineers often forget the most important tool: documentation. In this episode I'll cover what you should always keep on your desktop, what information each source provides, and when you need to dig into the code yourself.
It's your main source of truth. Unfortunately, official documentation isn't great for learning Metal. To use it effectively, you need a basic understanding of the principles. The good thing is that you can find everything you need there.
I highly recommend looking through the entire set of docs. Even if you don't need something now, you may need it in the future, so you'll already know it exists and can quickly find it.
The core Metal documentation covers the whole framework and includes many explanatory articles. It's the most informative part of the official docs (outside of the MSL spec), but it can be a heavy read. Look through it even if you're starting with third-party guides and tutorials.
The full specification. If you're working with shaders you should always have a tab with this open in your browser or keep a downloaded copy handy.
Metal Shading Language Specification
You need this if you want to support more than the latest devices. Older hardware may come with older chipsets and, as a result, fewer supported features. This table maps every feature to every Apple chipset, so it's the second tab you should keep open when you actively work with Metal.
It has basic documentation listing all classes, structures, and functions, but most entries are barely documented or not documented at all. You need to understand the principles behind the algorithms implemented in these MPS modules, or ask on forums and tap your friends.
Example: some time ago I needed to implement pyramid blending using MPS, but the documentation never explained how the MPSImageLaplacianPyramid, MPSImageLaplacianPyramidAdd, and MPSImageLaplacianSubtract kernels differ or what they do, so I found the information only in one place on the internet.
This API is documented even more poorly and its examples are often outdated, but you can still grasp the principles and then rely on experimentation.
Metal Performance Shaders Graph
Here you can find basic explanations, code samples, and documentation for some features. I say "some" because there are just brief descriptions for most entries.
This little framework is documented well enough. Because it's a higher-level API, the guides are clearer, so scan the docs and move on.
WWDC often provides additional information and tricks, but in the Metal world it's more about basic how-tos. If you need something deeper, you have to dig into the documentation and the code. The best part of these videos is the direction they give you to explore on your own.
As I mentioned above, there can be cases where the documentation has nothing about what you need. In that situation, check the forums or ask there. Also don't hesitate to browse forums about similar GPU technologies (OpenGL, WebGL, Vulkan); you'll often find similar principles, shared issues, or at least good ideas.
If you can't find something in the documentation, you still have a chance to dig up what you need in code comments (Cmd+Click a symbol and jump to the headers). Those comments should become part of the docs automatically, but they're often out of sync, so look at the code itself.
Sometimes you can find good insights in sample code. Just keep in mind that some of these examples might be outdated, and some work only on betas because they were made for demos and WWDC keynotes.
One of the reasons I'm writing this series is the poor documentation and learning materials. When I started with Metal (from its launch), there was nothing at all, and I had to rely on my OpenGL knowledge and analogies (now Vulkan is closer to Metal).
LLMs work well with the material they've trained on. Metal isn't very popular, doesn't have many open-source projects, and lacks great documentation or long discussions, so don't expect amazing results. But you can still ask for basic code and get a starting point.