What is libretro?

Download the RetroArch/Libretro Technical Brochure (PDF)

Libretro is a simple API that allows for the creation of games and emulators. It is very simple in nature, yet very powerful. The simplicity of it all requires some explanation in order to truly grasp how useful it can be to your own projects.

When you choose to use the libretro API, your program gets turned into a single library file (called a ‘libretro core’). A frontend that supports the libretro API can then load that library file and run the app. The frontend’s responsibility is to provide all the implementation-specific details, such as video/audio/input drivers. The libretro core’s responsibility is solely to provide the main program. You therefore don’t have to worry about writing different video drivers for Direct3D, OpenGL or worrying about catering to all possible input APIs/sound APIs/supporting all known joypads/etc. This is none of your concern at the libretro core implementation level.

Any project that is ported to work with this API can be made to run on ANY libretro frontend – now and forever. You maintain a single codebase that only deals with the main program, and you then target one single API (libretro) in order to port your program over to multiple platforms at once.

Other projects benefit from our ever-expanding libretro core software library by implementing the libretro API inside their own projects. To this end, project such as XBMC have already begun writing a libretro driver based on the RetroArch reference libretro frontend.

RetroArch is the official reference frontend, and it is available on nearly all modern-day platforms. It is meant to be fast, simple, yet powerful.

Other platform-specific frontends are currently in development, including native integration with the popular HTPC platform XBMC.

Who Uses Libretro?

While the most common use case for libretro has been console emulation, it is equally suited as a platform for almost any 2D game. For example, the NX Engine used in the popular freeware game Cave Story has been successfully ported to libretro, open sourced games like Quake and Doom have been ported to libretro, and the new freeware game Dinothawr supports libretro natively.

Libretro GL/Vulkan

Aside from retro-style games and emulators that depend on software rendering and where you’d typically need nothing more than the ability to render to a framebuffer, the Libretro API also allows you to target OpenGL and Vulkan. This allows you to create libretro ports that use OpenGL or Vulkan as part of their internal rendering.

From a portability perspective, we highly recommend that you try to target both so that your libretro GL port will work on both mobile and desktop computers.

Why Should Developers Target Libretro?

Software that targets the libretro API instantly gains access to all of the platforms that have libretro frontends available. That means your game is immediately available to those platforms’ users without worrying about input/audio/video drivers, compatibility issues or the myriad quirks of the underlying host system(s). Likewise, there’s no need to write specialized GUI code for each platform or to use esoteric–and often buggy–cross-platform toolkits, like Qt and GTK+.

Furthermore, once your game supports libretro, all of the libretro frontends’ other features come along for free, such as RetroArch’s real-time rewind, lag-concealing netplay, lossless video recording/streaming and cutting-edge post-processing shader support.

Perhaps best of all: libretro is an open specification that is 100% free to implement, with no licensing fees or hidden strings attached.

If you’d like to learn more about libretro, leave us a comment or chat with us on IRC at #retroarch on Freenode.

Libretro’s design goals

Libretro is the library programming interface. Programs get ported to this library and can then be run with any libretro-compatible frontend.

Our reference frontend is RetroArch. The two projects are not the same, and this is reflected in the licensing as well. RetroArch sticks to GPL version 3 whereas the libretro API is a MIT-licensed API.

Some of the design goals for libretro:

• Allow a non-kitchensink approach to crossplatform portability.
• Allow a non-dependency heavy approach to crossplatform portability. Stick to just one header containing definitions for the necessary audio/video/input callbacks.
• Care about being backwards compatible. Libretro’s ABI( Application Binary Interface) has never been broken in years, and old libretro frontends from years ago in most cases can still use libretro cores being created today.
• By its very design enables programs to be ported to singular dynamic libraries which can then be loaded in and out of frontend applications thanks to the libretro API.
• Forces you by its design to rethink what code belongs to ‘core land’ and what should belong to ‘frontend land’. Libretro cores ideally should have minimal to no dependencies on any system/OS-specific APIs so that the same libretro cores can work on any libretro-compatible frontend.
• Designed with games, emulators and multimedia in mind. Libretro core ports resemble ports being done to standalone game consoles or mobile where the primary input device is not a keyboard and mouse (although libretro supports those as well).
• Does not concern itself with external WIMP GUIs (since they are not portable), or anything that would tie itself to mainly desktop PC-usage. Libretro cores ideally have to work seamlessly on mobile, desktop PC and game consoles.
• Requires you to link your libretro-ported program to a libretro frontend, leaves the libretro frontend creation part up to you or lets you select one of the mature libretro frontends already available.