docs: add macOS host 3D acceleration guide
Martin Wimpress
parent
4695a97053
commit
ae981fae0f
|
|
@ -0,0 +1,193 @@
|
|||
# macOS QEMU 3D Acceleration
|
||||
|
||||
This guide covers 3D graphics acceleration for VMs running on macOS hosts. Stock QEMU packages lack OpenGL support on macOS, but acceleration is possible with patched builds.
|
||||
|
||||
## Current State
|
||||
|
||||
**Stock Homebrew and Nixpkgs QEMU on macOS lack OpenGL support.** This is by design - the OpenGL dependencies (libepoxy, virglrenderer) target Linux in these packages.
|
||||
|
||||
The result: software rendering only, which is slower but stable.
|
||||
|
||||
## How 3D Acceleration Works on macOS
|
||||
|
||||
macOS deprecated OpenGL in favour of Metal. To enable GPU acceleration in QEMU:
|
||||
|
||||
1. **ANGLE** translates OpenGL ES calls to Metal
|
||||
2. **virglrenderer** provides VirGL 3D support to guests
|
||||
3. **`gl=es`** display option enables this pathway (not `gl=on` or `gl=core`)
|
||||
|
||||
This requires patched QEMU and virglrenderer builds with ANGLE integration.
|
||||
|
||||
## GL Mode Comparison
|
||||
|
||||
| Mode | Backend | Stability | Performance | Notes |
|
||||
|------|---------|-----------|-------------|-------|
|
||||
| `gl=off` | Software | Stable | Slow | Default for stock QEMU |
|
||||
| `gl=core` | Native OpenGL.framework | Unstable | Variable | macOS OpenGL is deprecated |
|
||||
| `gl=es` | ANGLE/Metal | Stable | Fast | Recommended when available |
|
||||
|
||||
## How to Get GL-Enabled QEMU
|
||||
|
||||
### Option A: Homebrew Tap (Recommended)
|
||||
|
||||
The simplest method using Konstantin Nazarov's maintained tap:
|
||||
|
||||
```bash
|
||||
brew install knazarov/qemu-virgl/qemu-virgl
|
||||
```
|
||||
|
||||
Repository: https://github.com/knazarov/homebrew-qemu-virgl
|
||||
|
||||
### Option B: Build from Source
|
||||
|
||||
Building requires Akihiko Odaki's patched forks.
|
||||
|
||||
**Dependencies:**
|
||||
|
||||
```bash
|
||||
brew install glib meson pipenv pixman pkg-config spice-protocol
|
||||
```
|
||||
|
||||
**Required repositories:**
|
||||
|
||||
- QEMU: https://github.com/akihikodaki/qemu
|
||||
- virglrenderer: https://github.com/akihikodaki/virglrenderer
|
||||
- libepoxy (with macOS support)
|
||||
- ANGLE libraries
|
||||
|
||||
**Configure flags:**
|
||||
|
||||
```bash
|
||||
./configure \
|
||||
--enable-cocoa \
|
||||
--enable-opengl \
|
||||
--enable-virglrenderer \
|
||||
--enable-hvf \
|
||||
--target-list=aarch64-softmmu,x86_64-softmmu
|
||||
```
|
||||
|
||||
For detailed build instructions, see Odaki's guide: https://gist.github.com/akihikodaki/87df4149e7ca87f18dc56807ec5a1bc5
|
||||
|
||||
### Option C: UTM
|
||||
|
||||
UTM bundles all patches and ANGLE libraries in a GUI application:
|
||||
|
||||
https://github.com/utmapp/UTM
|
||||
|
||||
Pre-packaged with everything needed for GL acceleration, but provides a GUI rather than CLI.
|
||||
|
||||
## Building a Nix Package with VirGL Support
|
||||
|
||||
Creating a custom Nix overlay for GL-enabled QEMU on macOS requires:
|
||||
|
||||
1. Override `openGLSupport = true` in the QEMU derivation
|
||||
2. Add macOS-compatible dependencies:
|
||||
- libepoxy (with macOS/ANGLE support)
|
||||
- virglrenderer (from Odaki's fork or with his patches)
|
||||
- ANGLE libraries (libEGL.dylib, libGLESv2.dylib)
|
||||
3. Apply patches from Odaki's QEMU fork
|
||||
|
||||
**Note:** Upstream QEMU and Nixpkgs do not fully support this configuration. You will need to:
|
||||
|
||||
- Patch virglrenderer for OpenGL ES compatibility
|
||||
- Ensure ANGLE libraries are available at runtime via `DYLD_LIBRARY_PATH` or installed in the package prefix
|
||||
|
||||
Reference the build scripts in Odaki's repository for patch requirements.
|
||||
|
||||
## Quickemu Support
|
||||
|
||||
[PR #1812](https://github.com/quickemu-project/quickemu/pull/1812) adds automatic GL detection and enablement for macOS hosts.
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. `check_cocoa_gl_es_support()` tests whether QEMU accepts `gl=es`:
|
||||
```bash
|
||||
qemu-system-* -display cocoa,gl=es -M none
|
||||
```
|
||||
2. Also checks for ANGLE libraries (`libEGL.dylib`) in:
|
||||
- QEMU's prefix (`<qemu-dir>/lib/`)
|
||||
- Homebrew locations (`/opt/homebrew/lib/`, `/usr/local/lib/`)
|
||||
- `DYLD_LIBRARY_PATH` entries
|
||||
3. Automatically uses `gl=es` when available
|
||||
4. Falls back to `gl=off` for stock QEMU builds
|
||||
|
||||
**Display devices used:**
|
||||
|
||||
| Guest Architecture | GL Device |
|
||||
|--------------------|-----------|
|
||||
| x86_64 | `virtio-vga-gl` |
|
||||
| aarch64 | `virtio-gpu-gl-pci` |
|
||||
|
||||
**Diagnostic output:**
|
||||
|
||||
When GL is enabled, quickemu displays:
|
||||
```
|
||||
- Display: COCOA, virtio-vga-gl, GL (es), VirGL (on) @ (1280 x 800)
|
||||
```
|
||||
|
||||
When falling back to software rendering:
|
||||
```
|
||||
- Display: COCOA, virtio-vga, GL (off), VirGL (off) @ (1280 x 800)
|
||||
```
|
||||
|
||||
## Version Requirements
|
||||
|
||||
| Component | Minimum | Recommended |
|
||||
|-----------|---------|-------------|
|
||||
| QEMU | 6.0+ | 8.0+ with Odaki patches |
|
||||
| macOS | 11.0 (Big Sur) | 13.0+ (Ventura) |
|
||||
| virglrenderer | 0.9.0+ | Latest from Odaki fork |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "OpenGL support was not enabled in this build of QEMU"
|
||||
|
||||
You are using stock QEMU without GL support. Install a GL-enabled build (see options above).
|
||||
|
||||
### Verifying GL is working
|
||||
|
||||
**From quickemu output:**
|
||||
|
||||
Look for `GL (es)` and `VirGL (on)` in the display status line.
|
||||
|
||||
**Inside the guest:**
|
||||
|
||||
```bash
|
||||
glxinfo | grep "OpenGL renderer"
|
||||
```
|
||||
|
||||
Should show something like:
|
||||
```
|
||||
OpenGL renderer string: virgl (ANGLE (Apple, Apple M2, OpenGL 4.1 Metal - 89.4))
|
||||
```
|
||||
|
||||
### Guest shows software rendering despite GL-enabled QEMU
|
||||
|
||||
1. Verify ANGLE libraries are accessible:
|
||||
```bash
|
||||
ls -la /opt/homebrew/lib/libEGL.dylib # Homebrew location
|
||||
```
|
||||
|
||||
2. Check QEMU accepts `gl=es`:
|
||||
```bash
|
||||
qemu-system-aarch64 -display cocoa,gl=es -M none
|
||||
```
|
||||
No error output means GL is supported.
|
||||
|
||||
3. Ensure the guest has Mesa with virgl support installed.
|
||||
|
||||
### Performance is poor with GL enabled
|
||||
|
||||
- Verify you are using `gl=es`, not `gl=core`
|
||||
- Check Activity Monitor for GPU usage - Metal should show activity
|
||||
- Some guests may need updated Mesa drivers for optimal virgl performance
|
||||
|
||||
## References
|
||||
|
||||
- Akihiko Odaki's Guide: https://gist.github.com/akihikodaki/87df4149e7ca87f18dc56807ec5a1bc5
|
||||
- Odaki's QEMU Fork: https://github.com/akihikodaki/qemu
|
||||
- Odaki's virglrenderer Fork: https://github.com/akihikodaki/virglrenderer
|
||||
- Homebrew Tap: https://github.com/knazarov/homebrew-qemu-virgl
|
||||
- UTM Project: https://github.com/utmapp/UTM
|
||||
- ANGLE Project: https://chromium.googlesource.com/angle/angle
|
||||
- Quickemu PR #1812: https://github.com/quickemu-project/quickemu/pull/1812
|
||||
1
Home.md
1
Home.md
|
|
@ -10,4 +10,5 @@ This wiki describes how to get up and running with Quickemu and also covers more
|
|||
- [**Advanced quickget features**](https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features) 🤓
|
||||
- [**Alternative frontends**](https://github.com/quickemu-project/quickemu/wiki/07-Alternative-frontends) 🧑💻
|
||||
- [**References**](https://github.com/quickemu-project/quickemu/wiki/08-References) 📚️
|
||||
- [**macOS Host Support**](https://github.com/quickemu-project/quickemu/wiki/09-macOS-Host-Support) 🍎
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue