facebook/igl: a low-level cross-platform GPU interface for C++

What IGL replaces, and for whom

A renderer that targets more than one platform usually ends up with a backend per graphics API: Metal on Apple hardware, Vulkan on Android and Windows, OpenGL ES where nothing newer is available, WebGL in the browser. Each backend has its own resource model, its own shader language and its own synchronisation rules. IGL takes the position that the differences can be hidden behind one interface, and the README frames the goal plainly: it "encapsulates common GPU functionality with a low-level cross-platform interface" across OpenGL, Metal and Vulkan.

The audience is narrower than the phrase cross-platform graphics library suggests. The README lists minimal overhead for C++ as one of three design priorities, and states that IGL supports new or existing native rendering code without the overhead of language interop or other language runtimes. That rules out the common use case of a Python or JavaScript application wanting to draw something. IGL is for teams already writing rendering code in C++ who want to stop maintaining separate backends, and who are willing to adopt a command-buffer style API rather than the immediate-mode style that OpenGL encourages.

The third stated priority is reach and scale in production, and it is the most concrete claim in the README: the library has been battle-tested for device reliability, with the long-tail of Android devices and Quest 2/3/Pro compatibility called out by name for OpenGL and Vulkan. That is a statement about where the project's testing effort has gone, and it tells you the maintainers care more about mobile and headset coverage than about, say, exotic desktop drivers.

Command buffers, state containers and the backend split

IGL's API shape follows modern graphics APIs rather than OpenGL. The README says the library embraces modern abstractions such as command buffers, state containers and bindless, and that this is deliberate: it gives more control than OpenGL's state machine API, which in turn lets the Metal and Vulkan backends stay leaner because they do not have to emulate a stateful global context.

That choice has a cost the README does not spell out. Code written against a state-machine API has to be restructured to record commands and bind state explicitly. If you are porting an existing OpenGL renderer, the port is not a shim; it is a rewrite of the parts that touch the API. The payoff is that the same recorded commands can be replayed on Metal or Vulkan without a translation layer that guesses what you meant.

The backend coverage is uneven by design, and the platform matrix makes the gaps visible. Vulkan 1.2 is supported on Windows, Linux, macOS through MoltenVK, and Android including Quest 2/3/Pro, but not on iOS. Metal 2 runs only on macOS and iOS. OpenGL 3.1 through 4.6 covers Windows, Linux and macOS but not iOS or Android, while OpenGL ES covers the mobile targets and, through Angle, Windows and Linux. WebGL 2.0 is listed as a supported backend, which is what makes the WebAssembly target possible. If your product needs one backend on every platform, the matrix will not give it to you; you pick per platform and accept that the code path differs.

Building IGL from source and running a sample

There is no package manager step in the README. IGL is built from a checkout, and the first thing the build instructions ask for is the deployment scripts, which download external third-party dependencies. The README points at LICENSE.md for the full dependency list.

python3 deploy_content.py
python3 deploy_deps.py

Those two commands populate the third-party tree. They need network access, and they are a prerequisite for every platform below, so run them once before configuring anything.

On Linux the README gives an explicit package list before the CMake configure step. Note that it includes the GLFW and GLEW development packages, which the desktop samples rely on.

sudo apt-get install clang xorg-dev libxinerama-dev libxcursor-dev libgles2-mesa-dev libegl1-mesa-dev libglfw3-dev libglew-dev libstdc++-12-dev
cd build
cmake .. -G "Unix Makefiles"

On macOS the README configures with Xcode and disables Vulkan in the same command, which is worth noticing: the default macOS configuration is not the one the instructions use.

cd build
cmake .. -G "Xcode" -DIGL_WITH_VULKAN=OFF

The WebAssembly path is different again. The README asks for Emscripten and Ninja, then uses emcmake to wrap the configure step.

cd build
emcmake cmake .. -G Ninja
cmake --build .

After a successful build, the samples are the place to start. The repository has samples/android/, samples/desktop/, samples/ios/ and samples/wasm/, so there is a runnable target for each platform family. The README does not document how to launch an individual sample binary, so expect to read the sample's own build file rather than the top-level README. Android is the exception: the README says the Gradle project lives in build/android/, which means Android is built through Gradle rather than the CMake commands above.

Where IGL is the wrong tool

The clearest limitation is the one the README states as a feature. IGL is a C++ library with no language interop layer, so an application written in Rust, C#, Python or JavaScript cannot call it without writing its own binding, and the README offers none. If your renderer lives in a managed runtime, the interop cost you were trying to avoid comes back.

Platform support is the second boundary. iOS has no Vulkan entry in the matrix and no OpenGL entry, so the only backend listed for iOS is Metal 2. macOS has no OpenGL ES support, so an application that standardised on OpenGL ES for mobile cannot use that path on the desktop. WebAssembly is listed as a supported platform and WebGL 2.0 as a backend, but the README does not say which features degrade on the web target, and it does not document a fallback when WebGL 2.0 is unavailable.

The build story is the third constraint. Dependencies arrive through two Python scripts rather than a lockfile-driven package manager, so a hermetic or offline build needs its own mirroring step. The README does not document a supported way to point those scripts at an internal artifact store. Teams with strict supply-chain review will have to read LICENSE.md and the third-party tree before they can approve the dependency set, and the README does not enumerate it inline.

How IGL differs from bgfx and wgpu-native

The nearest comparison in this space is bgfx, which also offers one C++ API over many backends and also covers desktop, mobile and web. The difference is in the abstraction level. bgfx presents a higher-level, more self-contained rendering API with its own shader compilation pipeline and a C-style interface, which makes it easier to bind from other languages and easier to pick up. IGL goes the other way: the README explicitly says it is designed to give more control than OpenGL's state machine and to expose modern abstractions like command buffers and bindless. If you want the library to own more of the rendering decisions, bgfx is closer to that. If you want to keep control and only remove the per-backend duplication, IGL is the closer fit.

wgpu-native is a different kind of alternative. It implements the WebGPU standard in Rust and exposes a C API, so its abstraction is fixed by a specification rather than by the maintainers' priorities, and it inherits WebGPU's portability guarantees. That specification also constrains what you can express. IGL's README describes no such standard behind the interface; the API is the project's own design, which means it can track Metal and Vulkan more directly but gives you no spec to check behaviour against.

A fourth option is to do nothing and keep hand-written backends. That is a real choice, and for a project that ships on two platforms with one API each, it is often cheaper than adopting any abstraction layer. IGL pays off when the number of backend and platform combinations crosses the point where maintaining them separately stops being tractable.

Licence, releases and what an upgrade costs

The README states that IGL is released under the MIT license, with LICENSE.md holding the full text and the third-party acknowledgements. One component is carved out: the SparkSL Compiler is released under the SparkSL Compiler License, with the full text linked from the releases page rather than the repository, and the README points to a separate SparkSL.LICENSE download. That is the part of the dependency set to read first if your legal review treats bundled compilers differently from the MIT-licensed core. Nothing here is legal advice; the licences themselves are the authority.

The release cadence is visible from the tags: 1.0.0 in July 2024, v1.1.0 in June 2025, and v1.1.1 in July 2025. The repository is not archived and the last push was on 2026-09-23, so the project is being worked on, but the gap between the 1.0.0 and 1.1.0 tags is roughly eleven months, and the README does not describe a stability or deprecation policy for the API. Plan for the possibility that a minor release changes interfaces.

Upgrade cost is dominated by the build rather than the API. Because dependencies are fetched by deploy_content.py and deploy_deps.py, moving to a new tag means re-running those scripts and re-validating the third-party set, not just bumping a version string. The README does not document a rollback procedure for those scripts, so a team that pins a tag should also pin or mirror the dependency artefacts it produces.

Editorial conclusion

Adopt IGL if you maintain C++ rendering code that has to run on Android, iOS, desktop and WebAssembly and you want command buffers and explicit state instead of an OpenGL-style state machine. Do not adopt it if you need a scripting-language binding or you cannot vendor third-party dependencies into your build. Before committing, run the deploy scripts, build one desktop sample, and confirm that the backend you need is marked supported for your target platform in the README table.

Frequently asked questions

Official sources

1. facebook/igl on GitHub
2. Issues
3. README
4. Releases