Shaders¶
RetroArch allows to apply shaders on top the visual output of the emulator core. This guide will give you the basics on how to apply shaders and where to put your own.
Applying shaders¶
Generally, KNULLI expects you to make all your emulator settings from EmulationStation, the KNULLI frontend. Configuration files for each emulator are generated on demand when launching a game, based on the settings you made in EmulationStation. Consequently, settings you make in RetroArch while a game is running do not stick by default, as they will only apply for the game that is currently running and will be dropped the next time you launch a game, because the configuration is re-generated from scratch.
If you want RetroArch to handle your shaders instead of EmulationStation/KNULLI, you need to disable shaders in EmulationStation for the respective games/systems and create overrides from within RetroArch.
Disable shaders for the game/system in EmulationStation¶
It may seem counter-intuitive, but to enable shaders from within RetroArch, you first need to disable shaders in EmulationStation. To do so
- either go to the Advanced Game Options by holding the launch button (A or B, depending on your setup) on the game in the game list to disable shaders for the game.
- or go to the System Settings by bringing up the main menu via Start, head to ++"Game Settings, then head to Per System Advanced Configuration to disable shaders for the system*.
- Find the menu for Game Rendering & Shaders and make sure that Shader Set is set to None.
Create an override file¶
Overrides can be applied to override the generated configuration on a per-game or per-core level. If you want to apply shaders for a single game or for the entire emulation core, you should first make sure to create an override for the system:
- Launch the game you want to apply the overrides to (or a game which uses the core you want to apply the overrides to).
- While the game is running, hold Function and press B to bring up the RetroArch menu.
- In the RetroArch menu, go to Overrides and either
- Save Core Overrides to create an override file for the entire emulation core.
- Save Content Directory Overrides to create an override file for all games of the current emulation core in a specific folder (e.g., only for
roms/gb
but not forroms/gba
). - Save Game Overrides to create an override file for the game you are currently running.
You can also delete existing override files from this menu.
Apply shaders¶
Once you have an override file in place, hold Function and press B to bring up the RetroArch menu (if it is not open, yet). Find the Shaders section in the quick menu and open it. In this menu, you can load and remove shaders.
You can apply more than one shader on top of each other, which is why you can append and prepend shaders, to make sure the shaders are support in whatever order you prefer them to be applied. There are countless possibilities, how to combine shaders, so we will not go into details here.
Tutorial on shaders and overlays
Our friend Russ from Retro Game Corps has created a very thorough guide on how to use shaders and overlays. In this guide, he is giving countless examples on how to properly stack shaders and which shaders tie in well with which overlays and how to set them up. His guide is not KNULLI-specific, however, it is compatible with KNULLI. If you are new to shaders or if you need inspiration on how to tweak your shader setup, have a look here!
If you choose to load, append, or prepend a shader, a menu will open which will bring up all the pre-defined shaders which come with KNULLI. At the top of the screen, you will see the folder you are currently in, which is /usr/share/batocera/shaders
. By selecting Parent Directory
, you can navigate up to the parent directory of the folder you are currently in.
Known issue: RetroArch top-level file system shortcuts currently do not work with KNULLI
Once you reached the top level of the file system (/
) you can opt to select Parent Directory
one last time. If you do so, you will end up seeing a list of shortcuts to file system locations. Instead of the folder icon () you will see a database-like icon () in front of all the options. Make sure not to enter this menu.
Once you reached this level of the navigation menu and attempt to reach any destination on your SD card from here, all your folders will appear empty even though they are not. You will not be able to find any shaders until you cancel the operation and bring up the menu again.
You cannot do any permanent damage, however, if you are not aware of this issue, you might be lead into thinking your shaders are broken or in the wrong place. Most likely, they are not. Most likely, you ran into a bug within RetroArch on KNULLI devices.
Adding your own shaders¶
KNULLI already comes with a lot of pre-defined shaders which are stored in the read-only part of the KNULLI file system in a folder called /usr/share/batocera/shaders
. However, you are not supposed to delete or add any shaders there. Instead, KNULLI expects your own shaders to be stored in the shaders
folder in your userdata
/SHARE
folder. (If you want to learn more about the shaders
folder, have a look at the through documentation in the Batocera wiki.)
If you do not have such a folder, yet, access your userdata
folder (e.g., via network transfer) and add the shaders
folder. Afterwards, you can copy all your RetroArch shaders into that folder.
Create a shortcut to your own shaders folder¶
As explained above, navigating from the default shaders folder to your custom shaders folder can be annoying if you have to do it regularly. However, depending on your choice of filesystem, it might be possible to create a shortcut from the read-only shaders folder that comes with KNULLI to your own shaders
folder. If you regularly deal with your own custom shaders, this feature might come in handy to avoid navigating the entire file system every time you want to find your own shaders.
The easiest way would be to create a symbolic when your device is starting up. This could be achieved by simply adding/editing a custom.sh
bash script in your system
folder:
- Go to your
system
folder (e.g., via network transfer). - If it does not exist, yet, create a new text file
custom.sh
.- Windows users need to make sure the file extension is correct. (Please make sure your file extensions are visible before proceeding!)
- Edit
custom.sh
with a text editor (preferrably something like Notepad++). - It might be required to manually assure UTF-8 encoding and Linux line endings!
- If the file is empty, add the line at the top of the file.
- Now add the line at the end of the file.
After rebooting your system, it should now automatically create a link which makes /userdata/shaders
available at /usr/share/batocera/shaders/userdata-shaders
. Consequently, when you bring up the menu for loading, prepending, or appending shaders, you should find the subfolder userdata-shaders
among the other contents of /usr/share/batocera/shaders
. When entering userdata-shaders
, you should find all your custom shaders you have stored in /userdata/shaders
.
Permanent link in overlay
It would also be possible to store a permanent link in the overlay
file rather than re-creating the link on every boot. To do so, simply SSH into the device, create the link with the command shown above and run batocera-save-overlay
to make the change permanent. However, by creating the link via custom.sh
on boot, the link would survive re-flashing SD 1 on dual SD card setups and can also be included in your backups of the entire userdata
folder.