Mednafen/Beetle PSX HW – Alpha test version

Parasite Eve with the experimental GL renderer. Note the screen residue glitches at the bottom.
Parasite Eve with the experimental GL renderer. Note the screen residue glitches at the bottom.

Here is the first release of Mednafen/Beetle PSX HW. You can download this core right now for Windows, Linux, and OSX.


See a complete screenshot gallery here.

Where to get it?

Rage Racer using experimental GL renderer
Rage Racer using experimental GL renderer
Final Fantasy VII using experimental GL renderer
Final Fantasy VII using experimental GL renderer

Go to RetroArch, go to Online Updater, go to ‘Update Cores’, and download ‘PlayStation (Mednafen PSX HW)’. You might need to update your core info files first before this will show up properly. To do this, go to ‘Online Updater’, and select Update Core Info Files’.

System requirements

You need to have a GPU that supports at least OpenGL 3.3 core context in order to use this. It might be possible to lower GPU requirements in time but now is not yet that time.


Gran Turismo 1 with the experimental GL renderer.
Gran Turismo 1 with the experimental GL renderer.

We have added an OpenGL renderer to Mednafen PSX. This renderer is based on simias’ GPU renderer for his Rust-based PlayStation emulator, Rustation.

Lots of people worked hard on bringing this to you. It was a joint team effort between r5z, simias, zeromus, and me to bring this from Rust over to C++, and in a way so that it still benefits Rustation as well.

This is probably the first OpenGL renderer for PSX that is not based on outdated fixed-function OpenGL code and which is, actually, well, open-source. Because we can assume shaders will be there, we can get reasonably close to emulating texture windows accurately (with Pete’s OGL1 GPU plugin, there were codepaths for doing it with paletted textures – the hacky approach – and the pixel shader approach). Therefore, the renderer is still kept pretty simple and easy to understand.

Unfinished business

Resident Evil 2 with the experimental GL renderer.
Resident Evil 2 with the experimental GL renderer.

There are several parts which are still not finished:

    VRAM-to-VRAM copies right now are completely broken. You might see several glitches during FMVs and/or other scenes that require framebuffer manipulation. Final Fantasy 7/8’s pre-battle swirls come to mind as examples of that.
    There are still several texture updating problems. The water in Tomb Raider 2 for instance can initially appear flat shaded until you take a savestate. Other problems include Resident Evil 3’s sprite-based inventory system, when you add or remove items from this list, the changes might not be reflected on-screen.
    There are still some graphics issues. One example is the broken opacity boxes around Silent Hill’s objects.
    There are still several crippling performance bottlenecks with this GL renderer. The first priority is getting the rendering to be as accurate as the software renderer until optimization becomes a priority.
    Toggling fullscreen will give you a black screen. This is yet to be implemented.
    There are currently some near/far issues right now where objects very close to the projection camera can appear glitched onscreen.
    There might still be some resolution issues where some portions of the screen don’t get clipped away as they should, so you might see some onscreen garbage in places that are normally obscured and not visible.


Let’s detail some options for this hardware-based core :

Internal GPU Resolution (Restart) – This lets you change the internal resolution. NOTE: In this alpha version, it will crash if you try to change this at runtime. Here is a way to work around it: go to Quick Menu -> Options, change ‘Renderer’ to ‘software’, restart the core. Change the Internal GPU Resolution. Then change ‘Renderer’ back to ‘opengl’, and restart. Your changes should take effect now. Right now the max resolution you can set it to is 8x.
Texture filtering – This only works with the OpenGL renderer. You can toggle between ‘nearest’ point filtering, 3-point filtering (N64-style quasi-linear filtering), and plain bilinear filtering. Both 3-point filtering and bilinear filtering can impact performance negatively right now, and on average bilinear filtering has less graphics issues than 3-point so far. If you want the best performance, go with ‘nearest’.
Internal color depth – This only works with the OpenGL renderer. You can toggle between 32bpp (32bit color) and 16bpp dithered mode.
Wireframe mode – It will toggle between wireframe mode and filled shading mode (the default).
Display full VRAM – This requires a restart in order to take effect. This allows you to see all the VRAM banks on-screen. Mainly useful for developers only.

Warning for people using Cg shaders

Street Fighter Ex Plus Alpha with the experimental GL renderer and bilinear filtering enabled.
Street Fighter Ex Plus Alpha with the experimental GL renderer and bilinear filtering enabled.

Cg shaders won’t work with this core as long as it requires OpenGL 3.3 core context. Cg is no longer alive from a public consumption perspective and as such they never saw fit to adding support for GL 3.3 core context.

So make sure to disable any Cg shaders you had running before trying to run this core.

When/if we lower GL requirements, this might no longer become an issue, but you will always have a better experience with this plugin using GL 3.3 or later.

Bug reports

Tekken 3 with experimental GL renderer
Tekken 3 with experimental GL renderer

You can post bugs and graphics issues here (preferably with screenshots).

Other Mednafen/Beetle PSX improvements

Final Fantasy VIII with experimental GL renderer
Final Fantasy VIII with experimental GL renderer

PBP support is now much more mature. There is support for encrypted official PS3/PSP PSOne games added now thanks to Zapeth.

He also submitted some accuracy improvements which should give the emulator a better score with the PSX benchmark test programs.

Upcoming news/announcements

Metal Gear Solid
Metal Gear Solid

In other news, expect a new point release of RetroArch soon. No Apple TV and Windows UWP support yet, but Blackberry 10 might be coming back for the 1.3.5 point release.

RetroArch 1.3.4 released

Version 1.3.4 has just been released.

Builds can be found here.

Old MacOS X builds (PowerPC and 32bit Intel) will be retroactively added soon, since these builds can’t be automated.

Graphics improvements


This is the simplified ribbon animation shown here. The more advanced one should be fullspeed on any GPU from 2008 and later.

With version 1.3.4, RetroArch is encroaching upon launcher territory and will try to position itself as a fancy convenient 10-foot interface with plenty of eye candy.

To start with, the XMB menu driver now has a ribbon animation running in the background that looks very similar to the graphics you’d see on the PS3 GameOS. There are two variations on this, a simplified version (which should run at fullspeed on even old 2005-2006-era GPUs) and a more advanced version with light sourcing.

The background color gradient can be changed easily by going to Settings -> Menu and changing Background Gradient. There are several predefined color variations you can select from.

Thumbnails and boxart

h0ybHdYWe now have our own server that is going to be serving up boxart/thumbnails to the frontend client. We call our thumbnail collection project ‘libretro-thumbnails‘.

Content in the horizontal playlist will have thumbnail icons shown next to it. By pressing the Y button on your RetroPad, you can switch inbetween the different thumbnail modes: Title screen, Snap shot, and Boxart.

In order to grab this boxart, you can go to Online Updater -> Update Thumbnails. Download the boxart set for the system you need and it will automatically extract it to the thumbnails directory. The boxart sets will be updated daily and it’s possible for people to contribute.

Nintendo 64 – LLE RDP and graphics plugin unification

There is going to be an entirely new project using Angrylion merely as a base but taking full advantage of the compute shader capabilities of OpenGL 4.3+/Vulkan. PLEASE NOTE: NOTHING IS READY YET, NOT EVEN SOMETHING THAT CAN BE PLAYED, so unless your idea is to watch some pictures, there is nothing to badger the developer about yet, so please don’t :).

At the same time while this is going on, I am busy consolidating all of the various graphics plugins in Mupen64 libretro so that we can arrive at a hybrid renderer solution. Most of the code in these HLE RDP plugins is about 80 to 90% copy pasta so it should not prove too hard unifying Rice/GLN64/Glide64/Gliden64 and arriving at one video renderer that combines the best of all of them. We could then allow for several different code paths (some meant for performance, others meant for accuracy) instead of requiring users to have to switch between graphics plugins and restarting Mupen64 again.



Simias has been putting a lot of effort into Rustation lately and the Mednafen/Beetle PSX-compatible renderer plugin. It’s not ready for release-time yet but we (well, mostly a guy called r5) are steadily working on a C++ conversion of the Rust code.

Some of the features that have been implemented so far include:

  • Alpha blending – not yet complete and accurate but covers most of the cases.
  • Internal resolution upscaling – up to 8x.
  • Bilinear and 3-point filtering sampling – the latter is the sub-bilinear filtering algorithm from the N64.
  • Preliminary perspective correction – this is Rustation-only for now.

In other news, PBP support has now been integrated into Mednafen/Beetle PSX. It won’t support real PS3/PSP PBP images yet, so you will have to go with pre-converted PBP images that are not encrypted. However, it might be possible to have it run real PBP encrypted images as well later on.

I’m going to be working on helping r5 out with this C++ conversion of the GL renderer so we have something preliminary to show soon.

Miscellaneous release notes

  • (Android) An important bug got fixed that prevented two buttons from being toggled at the same time. This should help with arcade games a lot.
  • (Android) Devices which qualify as a games console (like the Nvidia Shield Tablet/Console) will boot into the XMB menu driver instead of the default touch-oriented GUI instead.
  • (Mac OS X) Library / Application Support / RetroArch is used for storing configuration files now like it was in the past. Sorry about this inconvenience in the past version.
  • (Vulkan / Windows) Should be usable on Windows now.
  • Arcade games can be scanned now for FBA and MAME cores.

Lakka and GameGirl


A new version of Lakka is available at the same time as the RetroArch 1.3.4 release.

Here is a brief changelog:

  • Service management, start or stop samba, ssh, and bluetooth from the GUI
  • Cuboxi and Hummingboard builds fixed
  • Thumbnails updater, with 3 types of thumbnails
  • XMB PS3 Ribbon animation
  • DualShock bluetooth auto pairing
  • Switching audio devices from the GUI
  • Support for some chinese DualShock clones in bluez
  • FBA Scanning
  • DAT updated to 2016
  • Drop shadows in XMB
  • XMB Theme switching, with an alternative theme: RetroActive
  • Bluetooth and WiFi working on RPi3
  • RetroArch and libretro cores updated

Speaking of Lakka, their sister project GameGirl has been garnering a lot of attention so far on Hackaday. They even ran their own story on it here.

GameGirl won a grand total of $177 for seed funding during the Hackaday 2016 Prize contest, second highest project in terms of funding.

Basically, what we want to achieve with GameGirl is just a low-cost practical handheld version of a Lakka/RetroArch device. It is basically a Raspberry Pi Zero with a very nice shell and buttons provided by 8bitdo, along with a 120Hz screen.


The Lakka project (its lead developer, Kivutar, in particular) needs your help and support. Here is a wish list of hardware he currently needs in order to help improve the project and which he hasn’t been able to obtain yet. See the contribute section here.

If you want to get in touch with us about the GameGirl project, please visit us here through Discord.

Next big point release and stuff we are trying to get done by then

This list is subject to change and meant more as a statement of intent and an installment plan.

  • We’re going to get that Apple TV port out of the door for the next release.
  • Might be time to get that Windows Phone/UWP port out of the door before Windows Phone is completely dead :).
  • Likewise for Blackberry 10, time to get that port out of the door again before the platform is completely dead. A lot of mobile phone casualties of late. Seems Android and iOS are the only ones left standing at this point with even Intel exiting the mobile arms race.
  • Reicast working on mobile platforms.
  • Some exciting new cores.
  • Other features I can’t talk about yet.

RetroArch 1.3.2 released

From now on, there will be more frequent rolling updates.

We are close to automating releases on the buildbot so that we can have weekly releases for the most prominent platforms.

Version 1.3.2 is available here:

I will add OSX 32bit and PowerPC releases to this later on. PS3 will be back at some later undisclosed time, same with original Xbox and 360.

Regarding the releases from this point on: give us as much feedback as possible, and with each week we can try to address some of this feedback and make RetroArch better. A ‘Release early, release often’ approach instead of the drought of stable releases that was the norm before will hopefully result in more sustained progress.

RetroArch/libretro project status update


qTILoyDWe have decided to port over a promising Minecraft clone to the libretro API. The original source repository can be found here, and the libretro repository can be found here.

Windows/Linux/OSX users can already download this core by going to the Core Updater and downloading ‘Craft’. You can directly start the core since it requires no content to be loaded, it can be started as-is without needing any ROM or content file.

The original Craft upstream repository was a bit barebones, so we have decided to expand this port:

  • Biomes were added (these were located on a branch that was never merged into master), this adds hills / fortresses as can be seen in the screenshot
  • Water was added (this was located on a branch, never merged into master).
  • More sophisticated sunrise/sunset color blending (from Konstrukts).
  • A ‘Jumping Flash’ mode that allows you to jump infinitely into the air all while the camera faces downwards.
  • Configurable draw distance. The draw distance has a big effect on the framerate, a draw distance of 1 or 2 can make this core playable even on very lightweight computers.
  • Configurable field of view.
  • Gamepad support (including analog stick support) configurable analog sensitivity and deadzones, preliminary mouse and keyboard support.
  • Configurable resolutions, up to 4K.
  • A lot of changes under the hood, some of them which are detailed in the Making Of Article.

Some things have been stubbed out so far such as the libcurl support which is required for the login authentication system to work. Network support will undoubtedly become a priority in the upcoming weeks as we plan to flesh out the main game’s content.

So far, one user has reported that he has gotten it to work on a Raspberry Pi although there are still some graphics glitches. It does not work so far on Android/iOS, and we are eagerly intending to fix that as soon as possible.

Expect to see big changes for this core. It’s currently  very bare bones but it won’t be for long.


Crash Bandicoot running on Rustation libretro.

This is an up-and-coming Sony PlayStation emulator made by simias (Lionel Flandrin). The libretro repository can be found here, and the upstream repository here.

Rustation requires OpenGL and has been written entirely in Rust instead of C/C++. It interfaces with the libretro API through Rust bindings that have been written some time ago by an external contributor.

Mednafen/Beetle PSX

Beetle/Mednafen PSX using software resolution upscaling (at 4x).

Mednafen/Beetle PSX has been a libretro core for quite some time now. As a direct result of the work that has gone into Rustation in recent weeks, simias has backported a considerable number of enhancements to the Mednafen/Beetle PSX core.

These include:

CPU Overclocking – Turning this core option on will eliminate drastic framerate drops in many games without any perceivable side-effects. Plenty of PlayStation games struggled to maintain a consistent framerate, Tomb Raider for instance would often drop down to 20fps and even the low teens in certain scenes. Other examples include Castlevania: Symphony Of The Night: after beating a boss, a spot effect would bring the framerate to its knees for around 4 to 5 seconds.

Resolution upscaling – Mednafen/Beetle PSX is no longer limited to native resolution but can now  be upscaled to 2x , 4x or 8x its original size. This greatly enhances the quality of the graphics at the cost of performance (and some minor graphics glitches when going above 2x). The graphics are still software-rendered.

Dithering – Dithering would be used by Nintendo 64 and/or PlayStation games to simulate higher color depth at the side effect of having some dithering patterns which a CRT TV would smooth over anyway and make nearly imperceptible. The alternative would have been color banding which would have been worse and definitely noticeable. However, dithering is a little more noticeable now on high definition screens than it ever was on a CRT. Dithering is now configurable, it can be turned off, left to its original native scale or upscaled depending on the upscaled resolution (if going above 1x).

This is not all that simias has brought to the table though. The next feature is not yet ready but it will be a definite game changer once a little further along:

Upcoming – OpenGL rendering

Right now work is underway on an OpenGL renderer for Mednafen/Beetle PSX. Essentially this is Rustation’s renderer made to work as a video plugin for Mednafen/Beetle PSX. This is mutually beneficial for both the Rustation and Mednafen PSX project this way, the Rustation graphics renderer can be battle tested against a more mature emulator and Mednafen/Beetle PSX in turn is finally no longer limited to slow software rendering.

Some work-in-progress screenshots. Do note that many things are still missing, you might be able to tell some of them in the current screenshots (missing blending for some textures, no sprites/lines being sent yet to the external renderer, etc.)

Mednafen/Beetle PSX using Rustation OpenGL renderer
Mednafen/Beetle PSX using Rustation OpenGL renderer



This is a new core that is still a work-in-progress but is steadily coming along together with the help of MoochMcGee. It is a libretro port of PCem, a PC emulator that some could consider a rival to Dosbox.

In terms of features, it supports a large variety of graphics, sound cards and BIOS / machine models. It is also unique in that it has 3Dfx Voodoo support. There is also preliminary nVidia Riva 128/TNT emulation that might be further fleshed out.

Together with an x86/x64 dynarec, it has been possible to play Pentium/Windows 9x-era games with 3Dfx Voodoo support at playable framerates.

Right now, this core is not yet ready but is making considerable strides. Video is now working, the runloop is more or less implemented, all that remains is adding all the remaining options and improving keyboard/mouse support.



This is not a libretro core project but a hardware project. Jean-Andre Santoni (Lakka head developer) and engineer David Perrenoud have created an open-spec portable handheld console called the ‘GameGirl’.

Please check it out and like it .

It consists of a 120Hz 320×240 display connected to a Raspberry Pi Zero.

Its main distinguishing points are:

  • Uses the Lakka distribution (and therefore by all accounts is a RetroArch/Libretro handheld portable game console)
  • Thin and tiny (only 66 mm x 99 mm)
  • Very inexpensive
  • Ability to shutdown at any time because of the Lakka distribution (it has a read-only filesystem which allows the user to turn off the device at any one time without the risk of corrupting the filesystem)
  • Future prototyps will include a thin-film rechargeable battery and a proper speaker (current prototypes will have a buzzer
  • An inexpensive and convenient portable solution for Lutro-based games (Love2D based games) and the Craft Minecraft core is an enticing offer.

By liking the project on Hackaday, you can help along its funding.

Making Of: Craft core

qTILoyDWhile porting and rewriting ‘Craft’ for use as a libretro core, we decided it would be nice to document some of the steps involved for the purpose of education.

You can check out our source code repository here.

There might be addendums and followups to this article later on. Note that some of these steps are not things that are ‘required’ to be done for the purpose of porting software to the libretro API, they are simply best practices based on the subject matter at hand.

Step 1 – Getting it compiled
‘Craft’ uses Cmake as its build system. While libretro places no requirements on which build system you use for your project, usually out of habit and preference we prefer to write static Makefiles for convenience and portability instead.

We reuse a basic Makefile template for this that we import into other projects. The three files we will be creating are : Makefile.libretro, link.T, and Makefile.common. We will put these files into the root of the project (or any other place where the central Makefile is usually stored).

To make things easier to understand, Makefile.libretro is the general Makefile solution which includes Makefile.common. Makefile sets up all the platform targets that your core supports, while Makefile.common would be the equivalent of CMakeLists.txt. You define all the files here that will need to be compiled here.

A rundown on some of the variables inside Makefile.common :

SOURCES_C – You add C source code files to this variable.

SOURCES_CXX – You add C++ source code files to this variable.

INCFLAGS – You add include directories to this varaible.

Craft is a C-only program, so we will add all the source files to SOURCES_C.

First we will attempt to compile as many files as possible before we will move on to actually making it work with libretro. Later on, we might replace some of the dependencies that ‘Craft’ uses with some of our own for reasons of portability and consistency. Some dependencies we will avoid for now like glew and glfw, we will add our own substitutes for this later on.

You will notice after following this commit that there are still quite a number of undefined references left before the core will actually be assembled. That is because of some of the dependencies we have omitted so far (like glew and glfw), and because we have yet to write a libretro implementation.

The following are notes based on the dependencies found in Craft, if you don’t find any of these dependencies in another project you don’t need to be concerned about this.

NOTE: I defined SQLITE_OMIT_LOAD_EXTENSION and appended it to CFLAGS since we won’t be needing such functionality for the libretro port.

NOTE2: Although the developer of Craft has gone to great pains to make sure there are as few hard dependencies as possible (and the few there are, have their sources provided inside the project’s codebase) ,there are still some hard dependencies which will require us to pull in some sources later on, like ‘libcurl’. We will ignore this for now, and just dynamically link against it for now until we can get rid of this dependency by compiling it into the core itself.

Step 2 – Skeleton libretro application
We will add a skeleton libretro source file now to the project. We will add these files to the ‘src’ directory:
– libretro.c
– libretro.h

This will be the main program file of our libretro core. Unlike with normal programs, main() is not the default entry point. In a libretro core, there is no default entry point and instead you go through the libretro program lifecycle for initialization and deinitialization of a program. We will return to this later.

Most of the functions right now are purposeful stubs. We will start filling them in in later steps.

NOTE: Because ‘Craft’ is a program that requires no content to run (as in – you don’t need to provide it with say a ROM or an image file in order for it to start), we want the libretro core to start immediately after it has been loaded. Therefore we do a RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME call.

Step 3 – OpenGL context creation/state management
‘Craft’ uses several cross-platform OpenGL utility libraries in order to function. One is known as ‘glew’ (OpenGL Extension Wrangler Library), the other is called ‘GLFW’.

For libretro GL cores, we resort to several in-house libraries that can serve as replacements for these. For this port we will use two: glsym (equivalent to glew), and glsm (an OpenGL state machine).

We would like this port to work for both desktop OpenGL (2.0+) and mobile OpenGL ES (2.0 and up). Later on you will see that we will have to replace some functions like ‘glGetIntegerv’ inside the source code in order to meet this criteria. For now during this step we will focus solely on integrating glsm/glsym and setting up a working GL context.

We will add the following files to the project:
– deps/libretro-common/glsm/glsm.c
– deps/libretro-common/glsym/rglgen.c
– deps/libretro-common/glsym/glsym_gl.c (for desktop GL)
– deps/libretro-common/glsym/glsym_es2.c (for mobile GL)

In order to use the GL state machine, you first setup the GL state machine context inside the retro_load_game function. You can see this being done here:

A couple of notes on the second parameter we pass to glsm_ctl :

context_reset – this function callback is called after the GL context has been initialized. Usually you should try to clean up after yourself here, (re)initialize the graphics, reset the texture state, etc.

context_destroy – this function callback is called after the GL context has been destroyed. Usually you would destroy any allocated objects here related to GL or any other state.

stencil – set this to true if you require a stencil buffer.

The context_reset callback implementation needs some further explanation –

once we know that the GL context has been successfully created by the frontend, we then need to tell the GL state machine to reset its context and to set all default values for the state machine. We can do this by doing the following function calls:

This ends the context-related setup part of glsm. From there, the way you use it to simply call this at the start of each retro_run call –

and unbind the state again at the end of that same function call, like this –

Step 4 – Reimplementing the runloop
A regular program’s flow of control usually starts at the ‘main’ function. ‘Craft’ is no different. This function is defined inside the main.c file. From there, it sets up an infinite while loop that runs as long as the game keeps running. Once we exit the game, it will finally exit the function returning a value, signalling program exit.

To convert a program like ‘Craft’ over to the libretro API, we need to make several modifications so that the libretro application lifecycle is correctly implemented. We will go over some of the required functions to implement, and what to implement inside these callback functions.

To make Craft work as a libretro core, we have had to rewrite the entire main.c file and in specific the main() function. Instead of one long big function, we have had to create a couple of functions which will get called from our libretro function callbacks:

– void main_init(void);
– void main_deinit(void);
– void main_load_game(int argc, char *argv);
– void main_unload_game(void);
– void main_run(void);

– retro_init

This is the main starting point of a libretro core. You can initialize resources here that are needed for the program to run.

We will call ‘main_init’ from this function.
– retro_load_game

This is the function that gets called by the libretro frontend when the frontend passes content to the core and the core needs to do something with it. The retro_load_game function is always called no matter if we are starting the core with content or not.

In the case of ‘Craft’, we do not require any content to be loaded for the program to run. Therefore, we can mostly ignore the parameter ‘info’ passed to this function.

Because ‘Craft’ is a libretro GL core, we have to be aware of something: you can see that we early-return true inside this function. What will happen then is that GL context creation gets set up behind the scenes. Once the GL context is ready to be used, the function callback ‘context_reset’ gets called. Once this happens, we know that our GL context is ready to be used by the core.

This is why we have delayed the execution of ‘main_load_game’ instead of simply calling it inside this function. Instead, we will call ‘main_load_game’ from retro_run when we know the GL context is ready.

– retro_run

This is the libretro core’s equivalent of an infinite while loop, with the exception that retro_run is supposed to represent one video frame’s worth of execution. By default, we assume that the frame time will be equal to what you need for 60 frames per second gameplay, although it is possible to configure the frame time on a per-retro_run basis with libretro as well. This core will not require us to toy with this, so we ignore this aspect for now.

In a libretro core, it is assumed that you need to call the video_cb callback at least once for every retro_run iteration, same with the audio callback. Since “Craft’ doesn’t have any audio code, we won’t bother with this.

As we mentioned earlier during our explanation of ‘retro_load_game’, the initialization of the GL hardware context might take some time until it’s ready. Until then, we cannot use any GL functions. Once it’s ready, the ‘context_reset’ callback will set the static variable ‘init_program_now’ to true. We check for this inside retro_run :

if (init_program_now)
main_load_game(0, NULL);
init_program_now = false;
video_cb(NULL, game_width, game_height, 0);

As you can see, we call ‘main_load_game’ at this point to finally initialize the game. You will also notice that we set the init_program_now variable to false, so that this function will no longer be triggered. We then do an early return from the function and emit a duped frame. We are now ready to be rendering the game in subsequent iterations of retro_run.

At this point, the main execution flow in subsequent calls of retro_run will be as follows:

– bind the GL state machine


– poll input


– optionally process input

– call main_run so that we iterate the Craft core for one frame.

if (main_run() != 1)
{ }

– unbind the GL state machine


– render to screen

video_cb(RETRO_HW_FRAME_BUFFER_VALID, game_width, game_height, 0);

– retro_unload_game

It will call this function upon shutting down the core. In here, we deinitialize/free
any resources directly related to the ‘game’ content we had loaded.

For ‘Craft’, no game content has actually been loaded since the core does not
require external content in order to run.

We will call main_unload_game from this function.

– retro_deinit

This function is called after ‘retro_unload_game’. In here, we will deinitialize all
other resources related to the core itself that weren’t already deinitialized during

We will call ‘main_deinit’ from this function.

Step 5 – Baking in assets

The original ‘Craft’ will compile its shaders from source files stored inside a subdirectory, and it will also look up its textures inside a subdirectory.

Since these shaders are pretty much required for the program to work and because the textures are relatively small, we made the decision to bake these assets into the main code. That way, we will not burden the user with having to store these assets somewhere where the libretro core can find and use them. We can also later on make changes to them easier for the purpose of OpenGL ES compatibility.

To convert the PNG files, we will use a program called bin2c (which can be found on Github), and perform the following commands:

bin2c textures/font.png textures/font_texture.h font_texture

bin2c textures/sign.png textures/sign_texture.h sign_texture

bin2c textures/sky.png textures/sky_texture.h sky_texture

bin2c textures/texture.png textures/tiles_texture.h tiles_texture

We now include these headers inside the src/main.c file.

Craft uses a middleware tool called ‘lodepng’ in order to load and decode PNG files into memory. The original code would use lodepng’s file I/O loading function in order to load PNG files. Since we are going to be using PNG files from memory instead, we will need to use a different function provided by lodepng: lodepng_decode32. This will allow us to point it to a source memory buffer (the converted in-memory PNG file) and then have it dump its decoded output to a destination memory buffer, which we can then provide to OpenGL.

The code we arrived at ended up looking like this:

static void load_png_texture_data(const unsigned char *in_data, size_t in_size)
unsigned int error;
unsigned char *data;
unsigned int width, height;
error = lodepng_decode32(&data, &width, &height, in_data, in_size);
if (error) {
fprintf(stderr, “error %u: %s\n”, error, lodepng_error_text(error));
flip_image_vertical(data, width, height);
#if defined(HAVE_OPENGL) || defined(HAVE_OPENGLES)
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, width, height, 0, GL_RGBA,

We then call it from the function ‘upload_texture_data’ for each texture file, which in turn gets called like this:

upload_texture_data((const unsigned char*)&tiles_texture[0], tiles_texture_length, &info.texture, 0);
upload_texture_data((const unsigned char*)&font_texture[0], font_texture_length, &info.font, 1);
upload_texture_data((const unsigned char*)&sky_texture[0], sky_texture_length, &, 2);
upload_texture_data((const unsigned char*)&sign_texture[0], sign_texture_length, &info.sign, 3);

In followup articles, we might touch on the process of baking in the GLSL shaders required for this core to function, and backporting these shaders to GLSL 1.00 so that they can be used with OpenGL ES 2 (a current work-in-progress). It might also touch upon what was needed in order to get keyboard and mouse functionality to work with the libretro core, and some of the other development changes we made to the core so far.


Vulkan progress report and initial impressions


So it’s already a couple of days ago since Vulkan launched. We were one of the first non-test programs in the world to launch on Day One with a quite mature Vulkan implementation. So far it seems only ARM Mali, nVidia and Intel Broadwell Mesa drivers can handle all the features inside RetroArch’s Vulkan backend.

This is a followup to the earlier article which can be found here.

WSI XCB support

Back when RetroArch added Vulkan support on Launch Day, there was only a working Wayland implementation.

We support Vulkan over XCB now too. This means you can get Vulkan to run now on Linux with an nVidia GPU since their binary  blob driver doesn’t support Wayland.

I have tested the XCB context successfully on an Intel Ivy Bridge GPU as well. You need DRI3 support in order for this to work.

In case the Vulkan driver does not work for you on Intel, try creating the file ‘/etc/X11/xorg.conf.d/20-intel.conf. The file can be found here.

We recommend that if you have the option to choose between the two (and on some GPUs you simply might not have this option, like nVidia), that you pick Wayland over XCB and an X11 server. It’s a lot smoother.

Some Intel Ivy Bridge/Haswell snags and how we overcame some of them so far

Font glyph rendering now works correctly even on experimental Vulkan drivers that don't yet support swizzling for some functions.
Font glyph rendering now works correctly even on experimental Vulkan drivers that don’t yet support swizzling for some functions.

Mesa Ivy Bridge/Haswell drivers (you can find them here) are currently very incomplete for Vulkan, so we had to workaround some things in order to make RetroArch run with Vulkan on them.

Ivy Bridge/Haswell drivers currently don’t support push constants, so this commit was necessary in order to get past it.

This made RetroArch go ingame on Ivy Bridge, however, there were still a couple of issues. RGUI doesn’t work and just shows a black screen (it works on Broadwell though), XMB crashes on an assertion (works on Broadwell), and GLUI/MaterialUI showed messed up font glyphs.

The messed up font glyphs required another workaround since it seems Ivy Bridge/Haswell drivers don’t support swizzling yet for vkImageView. So this commit made most of the graphics issues with GLUI/MaterialUI go away.

In case you want to test RetroArch with Vulkan and you don’t know how to set it manually to GLUI/MaterialUI, open up a text editor, find your retroarch config file (usually it’s ~/.config/retroarch/retroarch.cfg”), find the line that says “menu_driver = ” and replace it with:

menu_driver = “glui”

In order to start RetroArch with the Vulkan driver, you can either try to set it to the Vulkan driver through the builtin GUI, or if this is not an option, open retroarch’s config file with a text editor (usually ~/.config/retroarch/retroarch.cfg”), find the line that says ‘video_driver =’ and replace it with:

video_driver = “vulkan”

There are still some remaining issues that are the fault of the driver. For instance, if we go to the ‘Video’ subsection of the Settings menu, you will see some debug lines in the terminal complaining about:

anv_device.c:1016: execbuf2 failed: Invalid argument (VK_ERROR_OUT_OF_DEVICE_MEMORY)

For some reason the few on/off icon labels it needs to draw apparently triggers this. On Broadwell this works fine so we just assume it’s another driver bug to do with experimental Ivy Bridge/Haswell support.

We also get spammed a lot with this warning message inside the menu:

genX_cmd_buffer.c:195 ASSERT: srcStageMask == 0

Other things that are currently broken on Ivy Bridge/Haswell – GPU Recording/Screenshot seems to cause a crash –

anv_cmd_buffer.c: 805: anv_cmd_buffer_emit_binding_table: Assertion ‘surface_state.alloc_size’ failed.

According to Themaister this works fine on Broadwell.

Fortunately, the Vulkan shaders that maister already made do seem to work already on Ivy Bridge/Haswell. Right now there is just a few tiny shaders, two variations on a CRT shader, and they both worked on Ivy Bridge and at fullspeed.

The repo can be found here.

To use these, you’d launch a game with RetroArch, go to the Quick Menu, go to Shader Options, select ‘Load Preset’ and then browse to the directory containing the shader files and select one of them.

Discrete card progress

Themaister today addressed some performance issues on discrete GPUs like Nvidia which don’t really like you doing linear texture uploads, which is actually preferred for integrated GPUs like Intel HD.

Some initial impressions

Screenshot of Ridge Racer running in Mednafen PSX libretro core with the Vulkan crt-lanczos shader applied (running on Ivy Bridge Intel Mesa Vulkan driver).
Screenshot of Ridge Racer running in Beetle/Mednafen PSX libretro core with the Vulkan crt-lanczos shader applied (running on Ivy Bridge Intel Mesa Vulkan driver).

So it’s early days but what are some of the things that stand out so far?

1 – GPU Recording is supposed to be much faster now vs. the PBO readback approach that we had to use with the OpenGL driver. I haven’t been able to test it though since the Ivy Bridge/Haswell driver currently crashes when selecting it. On Broadwell and nVidia I am told  it works though.

2 – When you have ‘logging enabled’ in RetroArch, it will always report frame time deviations at application exit inside the terminal. They are much lower with Vulkan than they ever were in GL. Frame time deviations as low as 0.005% and 0.035% are pretty much expected, with GL you could only dream of such low figures.

Because of these much lower deviations and because of much better control over buffer swap management (see point 3), audio/video sync is just so much nicer. You especially notice it with cores like Beetle/Mednafen PSX when you are running a game that is interlaced, the deinterlacing seems to render a lot smoother and has less ugly ghosting side effects as before.

3 – Vulkan gives you much more control over the swap chain. Because of this, fastforwarding will no longer screen tear like it did with OpenGL. This is actually a very cool improvement. RetroArch allows you to set the maximum fast forwarding runspeed. If you set it to 2x and then run a game that runs internally at a 30fps framerate, you can actually make it run at double the framerate by just fastforwarding it, and unlike with OpenGL, you won’t experience any video tearing. Of course your audio will also be sped up by 2x but hey :).

4 – I can notice on average so far a 3 to 4fps increase when running Vulkan over XCB compared to the OpenGL driver running in X11. To preface this: this is using a software rendered core like Mednafen PSX, as in, the 3 to 4fps speed increase appears to be mainly faster blitting and reduced overhead.

With Vulkan, it is possible to increase performance of our libretro cores even further with software rendered cores. A new environment callback added to the libretro API called RETRO_ENVIRONMENT_GET_CURRENT_SOFTWARE_FRAMEBUFFER allows us to grab a pointer to GPU memory which we can use as a framebuffer for the core. With OpenGL, how video rendering would work with a software rendered core is as follows: the core maintains its own internal framebuffer, it updates this as it pleases, then at the end of a frame it sends the frame to the frontend through the video_refresh_t callback. The libretro frontend would then take this frame, copy it to the GPU through glTexImage2D or glTexSubImage2D, and then render it.

With this new environ callback (and video driver backends that support it like Vulkan), this additional copy can be entirely skipped, leading to a performance increase. I have already implemented this for a few cores like TyrQuake and FCEUmm.

5 – Shader passes are already a thing, and we can already stack shaders like we could with the OpenGL and Direct3D 9 drivers. Shader parameters aren’t implemented yet but something will be worked out.

Obviously this will have some consequences for the common-shaders repository as it currently exists. Obviously we will not at any point just remove the currently existing Cg/GLSL shaders that currently exist, but we might have to make an entirely different repository for Vulkan.

6 – Comparing actual Vulkan cores like the libretro-test-vulkan core to the GL test core serves no purpose so far since the test cores don’t even render the same thing, so I’m not going to be making any comparisons there. In short, there will be advantages for both hardware-accelerated cores and software rendered cores with Vulkan.

What remains to be done?

1 – Waiting on better drivers, obviously. There is only so much stuff that can currently be worked around with the Ivy Bridge/Haswell drivers. Hopefully a lot of these workarounds will in the future no longer be needed.

2 – There are currently some rendering issues with the ‘Zarch ‘menu driver (not that we intend that to be used right now for endusers but still, we need it rendering correctly with Vulkan too anyway for feature parity).

3 – More WSI context support. Win32 still has to be done (don’t have the hardware or the OS on my side, hopefully others can hop in here and help out), Android (I will be able to look at this myself and at least nVidia should have Vulkan drivers ready for use on Shield devices, I suppose), and Mir (we don’t actually support Mir yet on a context driver level, but it might be time to look into that). Native DRM/KMS context driver support is something I personally am really hopeful for.

Day 1 Vulkan support


Today Hans-Kristian Arntzen (also known as Themaister) sent us a big pull request giving RetroArch complete Vulkan support, the new graphics library API that has been unveiled and released to the public today.

See the pull request here.

Features/what has been ported

  • A full-featured graphics driver for Vulkan was written.
  • It should be compatible with MaterialUI/XMB and the other hardware-accelerated menu drivers that were previously GL-only.
  • Overlays should work through Vulkan. (by overlays we mean the gamepad overlays in RetroArch)
  • Font rendering should work through Vulkan.
  • Shader support. Vulkan support will mean some changes for shaders that will be unveiled later on.
  • Asynchronous GPU recording.
  • Libretro cores can be written against Vulkan as well. A test core was included for this in the repo, you can find it here.

Libretro cores that use Vulkan will require an additional header, libretro_vulkan.h.

Compilation instructions

If you want to play with this with the current drivers out today, here is a short tutorial. It assumes you are running Linux, you have a Vulkan-compatible driver installed for your graphics card, and it assumes you are running a Wayland window manager. It has been successfully tested on ARM Mali GPUs and Intel HD GPUs so far.

1 – First make sure you have the necessary Vulkan headers and libraries installed for your graphics card.

2 – We are assuming you are running Linux and you have Wayland setup. DRM/KMS and GLX support will come later.

3 – Download the latest source from RetroArch (the github repository can be found here), preferably by cloning the repository with your git client.

4 – Download all the necessary submodules by doing:

git submodule init

git submodule update

This will fetch glslang which you will need in order to compile the Vulkan bits.

5 – When inside the retroarch directory, run ‘configure’.

If Vulkan was detected, you should see the following line:

‘Checking function vkCreateInstance in -lvulkan … yes”

6 – Now run make in order to compile.

7 – Once compilation is done, try running the RetroArch executable. You might have to change the video driver directly in your retroarch.cfg file by searching for the line :

video_driver =

and changing it to :

video_driver = “vulkan”

8 – Start up the RetroArch executable you just compiled. Assuming you are running in Wayland and assuming your Vulkan driver is working, you should now be greeted by the menu.

Some additional instructions for Intel Mesa Vulkan users

We use Mesa’s vulkan branch for testing RetroArch with Vulkan on Intel HD GPUs. The Intel driver’s support for Ivy Bridge and Haswell is currently marked as ‘experimental’, so expect bugs with it until they improve the driver. Broadwell and Skylake should be stable.

Note – you might have to compile the driver specifically with Wayland support enabled – this is not guaranteed to be enabled by default (in fact, it seems to default to X11 support if you don’t specify anything).

To recompile it with Wayland support, run this command while inside the source directory –

./configure –with-gallium-drivers= –with-egl-platforms=wayland,x11 –with-dri-drivers=i965

After that, run make again to recompile the drivers. After it has finished, copy and the symlink files to your system library directory.

EDIT: So far we have been able to reproduce the following issues while testing RetroArch with the Vulkan backend on Ivy Bridge and Haswell (the GPUs that currently are not fully supported by the driver and are marked as ‘experimental’) :

Ivy Bridge – crashes at an assertion :

anv_nir_lower_push_constants.c:47: lower_push_constants_block: Assertion ‘state->is_scalar’ failed.

Haswell – gets ingame but shows a black screen instead of the menu. However, by navigating blindly to select a game – or by directly launching a game from the commandline – it will still output graphics.

We will have to wait for further driver improvements for now before it’s possible to run RetroArch with Vulkan on these slightly older GPUs.

Compiling a Vulkan core

In case you have RetroArch setup with Vulkan, you can play any of the non-libretro GL based cores. But what about a libretro core that is specifically made for Vulkan?  That can be done as well.

Themaister has made a Vulkan test core as a proof of concept. You can view the source here.

Follow these steps in order to compile it and test it on your device:

1 – Go to the retroarch source directory, go to cores/libretro-test-vulkan

2 – Run make inside the directory.

3 – If everything went well, it should create a file called ‘’. Move this file to the directory containing all your other libretro cores.

4 – Start up RetroArch, go to Load Core. Select the Vulkan test core. Select ‘Start Core’.

F-Droid changes

We changed the signature used to sign our nightly builds to match the signature used on the Google Play version so you may need to uninstall and reinstall in order to get updated.
In most cases it should be possible to backup the configuration, it should be located in /storage/emulated/0/Android/data/com.retroarch/files/retroarch.cfg, reinstall, run RetroArch once and copy it over to the same location.

It’s an inconvenience but it had to be done at some point.

RetroArch 1.3 released

RetroArch 1.3 was just released for iOS, OSX, Windows, Linux, Android, Wii, Gamecube, PS3, PSP, PlayStation Vita and 3DS.

You can get them from this page:

Once again the changelist is huge but we will run down some of the more important things we should mention:

Continue reading “RetroArch 1.3 released”

Getting Started with RetroArch

In the past month I have seen a few guides about configuring RetroArch, while good some fail to explain some concepts, so I thought why not, I’ll make a series of blog posts about configuring RetroArch, starting from the basics.


  • Core — a core is a program that runs in RetroArch (or another libretro frontend)
  • Frontend — a frontend in this context is a program that can run libretro cores (RetroArch, Minir, Kodi’s Retroplayer are examples of this)
  • Content — content is a game/program that is run by a core, some cores also require no content
  • Retropad — retropad is RetroArch’s input abstraction controller, it’s the interface between the physical controller and the core inputs
  • Save Files — save files are saves that are made from within a game, usually cross platform and should work across emulators in most cases
  • Save States — save states are snapshots of the content menory at a particular moment, these are not always cross platform and most certainly won’t work on a different emulator that the one used to create them
  • System Files — additional files that might or not be part of the romset that might be needed to get some content to work (usually referred to by the BIOS term)
  • Autoconf Profile — a configuration file that has button definitions for a particular gamepad

Continue reading “Getting Started with RetroArch”