Graphics backend
Which graphics API OctoMY uses, how to change it, and what it costs
Graphics backend
OctoMY renders through Qt's RHI, which can drive several graphics APIs. This page says which one you get, how to choose a different one, and when that is worth doing.
Which one you get
You do not normally choose. Each platform has an order, and the first backend that comes up wins:
| Platform | Order |
|---|---|
| Linux | Vulkan, then OpenGL |
| Windows | Vulkan, then Direct3D 12, then OpenGL |
| Android | OpenGL ES only |
Android is deliberate rather than a gap: Vulkan inside an embedded
QRhiWidget is unreliable on several common Android GPUs, and OpenGL ES 3.x is
present on every Android 7 or newer device.
The log line naming the backend appears at startup:
createOffscreenRhi: Vulkan offscreen context on NVIDIA GeForce RTX 5070
Choosing one
octomy-hub --rhi-backend=d3d12
The flag is spelled the same in every OctoMY application.
Accepted names: vulkan, d3d12, d3d11, metal, opengl, null.
There is no environment variable for this.
OCTOMY_RHI_BACKENDandOCTOMY_RHI_SOFTWAREworked in earlier builds and were removed: OctoMY runs on devices where setting an environment variable is awkward or impossible, so settings live on the command line, in the node config, or in the settings UI — somewhere that travels with the install. Use the flag.
An override does not fall back. If you ask for a backend and it cannot be created, startup fails and says so rather than quietly using another one — an override that silently degrades cannot be told apart from one that was ignored.
A name we do not implement on this platform is reported, not ignored.
d3d11 and metal are in the vocabulary so a bug report can name them, but
only vulkan, d3d12 and opengl have code behind them today.
Software rendering
octomy-hub --rhi-software
Asks the driver for a software rasteriser. Useful in a virtual machine, over a remote desktop, or when you suspect a driver bug. It works with whichever backend is selected — you do not need to pick an old API to get it.
When it is worth doing
Diagnosing a rendering problem. If something renders wrong, trying another backend tells you quickly whether the bug is ours or the driver's.
A driver you do not trust. Some Vulkan drivers are worse than the vendor's Direct3D path on the same hardware, and the reverse is also true.
Not for speed, without measuring. On Windows there is a real trade here and it does not point the same way for everyone: the zero-copy path that hands a rendered texture from the render worker to the window without a round-trip through system memory is Vulkan-only. Selecting Direct3D 12 is correct and supported, and it moves the 3D editor and the paint canvas onto a per-frame copy instead. Whether that costs you anything depends on your GPU, your resolution and your driver.
When the fallback happens it says so:
Shape-2 zero-copy unavailable on this device — using readback present
If you are comparing backends for performance, read that line first. Comparing a Vulkan run against a Direct3D run without noticing it means comparing two different present paths and attributing the difference to the API.
Related
- Build priority — why builds run at low priority
- Collect useful logs — enabling the RHI category when you are reporting a rendering problem