Q100308: Understanding Mari's Shader Compilation Modes for optimal performance



Different Shader Compilation Modes allow artists to benefit from viewport optimization and better performance overall. As some modes may be better for specific tasks, the user can also try changing mode if they're focusing on a particularly demanding task that requires optimal performance. This article explains the difference between the three compilation modes and how you can choose which mode to use.



In older versions of Mari, when an artist performed certain operations, Mari would need to recompile an Optimized shader in order to display the results on the canvas. These operations could range from an artist adding a new procedural layer to the layerstack, tweaking layer visibility, changing a blending mode or even rearranging the layer order. Depending on the complexity of the project, these shader compilations could take a relatively long time, which was both frustrating and time consuming for the artist.

Please review the following information on the Shader Compilation Modes which the artist can now take advantage of for improved performance:


Dynamic mode has very fast compilation rates at the cost of being a heavy shader to render. This means that, whilst your computer will remain active, you will experience a slower frame rate. Dynamic mode works by caching multiple operations to be used quickly so that, whilst initially you may still get a spinning wheel, from the second time you perform a specific operation your shader shouldn't need to recompile.


Optimized mode, once compiled, is a lighter shader to render so often offers faster frame rates. However, when compared to Dynamic mode, the process of compiling the shader is slower, causing Mari’s spinning wheel to appear in the viewport more often.

AUTOMATIC - Set by default

Automatic mode is not a single type of Shader Compilation but rather makes use of combining both the Dynamic and Optimized modes for a parallel compile which provides faster, cleaner results in the Mari viewport. Whilst working in this mode, artists will experience the maximum amount of optimizations and should rarely have to wait for the canvas to update.


By activating Legacy mode, you will be using Mari in the same state as previous versions predating 3.3v1. Whilst you will not be able to make use of the shader compilation features, you will still experience optimizations in GPU texture management and in colorspace export speeds.

Note: Legacy Shader Compilation Mode has been removed since Mari 4.8v1 as it is no longer stable, while the replacement Optimized shader mode is now very stable and well established. This is referenced in the Release Notes under ID 491857


To select the Shader Compilation Mode, open Mari's Preferences, select the GPU tab, and scroll down to "Compilation Mode".




If you are experiencing performance issues, there are further settings and options that can be changed to improve Mari’s efficiency. The following article explains other potential causes of slow performance to consider:

Q100253: Troubleshooting Mari performance issues



As we understand that performance issues can sometimes be directly dependent on your project and setup, if you are still experiencing issues after testing the advice in these articles please contact us via the Support Portal and let us know the steps you have taken so far. All initial information we require for investigation is outlined in the following article:

Q100090: Reporting a Mari issue

For more information on how to open a support request, please refer to this article:

Q100064: How to raise a support ticket

    We're sorry to hear that

    Please tell us why