HOWTO-Backends

Introduction

This page is meant as a mini-HOWTO which roughly outlines the steps needed to add a new backend (port) to ScummVM. Before you embark on this quest, however, you should first check if one of the existing backends already suits your needs. In particular the SDL backend already supports many platforms, since SDL itself is quite portable.

But if you have determined that a new backend is what you need, the following should hopefully help you a bit with that. Feedback is welcome :-).

I will assume that you are at least roughly familiar with ScummVM, and have a fresh checkout of our Subversion repository. Note that it's strongly adviced to base your work on the current development version of ScummVM, and not on a release version. This will ease integration of your work.

Overview

Essentially, you will have to implement a subclass of the OSystem class. Our Doxygen documentation is your friend and should hopefully explain enough about this, see here: http://scummvm.org/docs/doxygen/html/classOSystem.php.

You also need to either hook yourself into the regular ScummVM build system, or provide your own. Finally, you need to make ScummVM aware of your new backend by updating a couple source files (see below).

Step by step

In the following I assume your port is named "foobar" (very clever, isn't it? :-).

Create a new backends/ subdirectory matching your engines name, i.e. backends/foobar/
Populate the new directory as you need to. If you want to use our regular build system, you will want to provide backends/foobar/module.mk file. Take a look at backends/sdl/module.mk for an example.
Subclass OSystem. You could copy the content of backends/null/null.cpp to backends/foobar/foobar.cpp to get a skeleton. As you progress, it might be helpful to look at other backends to learn how they do things.
Make sure to provide the main function in your backend (the actual main function of ScummVM is scummvm_main, which your backend must invoke at some point).
Instantiate OSystem class and assign it to g_system, do that before calling scumm_main
Deinit properly after calling scumm_main, particularly call g_system->quit()
If appropriate, edit configure to add your backend (this is only necessary if you are going to use the "./configure && make" build system).
Modify common/system.cpp and backends/intern.h to make it aware of your backend. Mostly, this means telling it about your OSystem factory function (I'll leave the code there to document itself, if you don't understand it, ask us on IRC or on our mailing list).
Modify backends/intern.h if you want to set a custom default sample rate.

Example of minimal main()

 int main(int argc, char *argv[]) {
     g_system = new OSystem_Foobar();
     assert(g_system);
     
     // Invoke the actual ScummVM main entry point:
     int res = scummvm_main(argc, argv);
     g_system->quit();
     return res;
 }

That's it. The difficult part is of course writing the OSystem subclass. More on that in the next section!

Subclassing OSystem

TODO: This section is meant to give some specific hints on creating a useful OSystem subclass. For now I can't really think of anything useful besides the obvious, and besides what we already say in other places... Take a look at http://scummvm.org/docs/doxygen/html/classOSystem.php which contains lots of useful information. Also take a look at null.cpp to see what you have to implement, and peek at the SDL backend (which is our main backend and thus kind of a reference for all the others). And finally, take a look at common/system.h to see which methods are pure abstract, and thus *must* be implemented by you. Oh and of course: You can always talk to us on IRC or via email :-).

Misc notes

There is Small Devices Backend in the works which is planned to be common for all devices with limited resources. If you are working on a backend for such a system, you may want to take a look on that page!

updateScreen() method

updateScreen() method is called by an engine when it finished drawing something on the screen. It may happen quite often, up to several hundred times per second, but some devices have restriction on how many times per second screen bliting takes place. For example, some NTSC version can not physically update more often that 60Hz, and attempts to make it more often will result in the machine hang.

If you're writing a backend for such system, you may use code like this:

 void updateScreen() {
     uint32 newTime = getMillis();
     if (newTime - _oldTime < 1000 / MAX_FPS)
         return;
 
     _oldTime = newTime;
 
      // do actual screen update
 }

That should do the trick for you,