213
edits
(Mention that backends must implement main) |
Ccawley2011 (talk | contribs) |
||
(23 intermediate revisions by 10 users not shown) | |||
Line 4: | Line 4: | ||
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 :-). | 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 | I will assume that you are at least roughly familiar with ScummVM, and have a fresh checkout of our source code repository. Note that it's strongly advised 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 === | === 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 | 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 [https://doxygen.scummvm.org/d2/d38/class_o_system.html OSystem class]. | ||
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). | 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 === | === Step by step === | ||
In the following I assume your port is named "foobar" (very clever, isn't it? :-). | In the following I assume your port is named "foobar" (very clever, isn't it? :-)). | ||
# Create a new backends/ subdirectory matching your | # Create a new <code>backends/platform</code> subdirectory matching your port name, i.e. <tt>backends/platform/foobar/</tt>. | ||
# Populate the new directory as you need to. If you want to use our regular build system, you will want to provide <tt>backends/foobar/module.mk</tt> file. Take a look at < | # Populate the new directory as you need to. If you want to use our regular build system, you will want to provide a <tt>backends/platform/foobar/module.mk</tt> file. Take a look at <code>backends/platform/sdl/module.mk</code> for an example. | ||
# Subclass OSystem. You could copy the content of <tt>backends/null/null.cpp</tt> to <tt>backends/foobar/foobar.cpp</tt> to get a skeleton. As you progress, it might be helpful to look at other backends to learn how they do things. | # Subclass OSystem. You could copy the content of <tt>backends/platform/null/null.cpp</tt> to <tt>backends/platform/foobar/foobar.cpp</tt> 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 <tt>main</tt> function in your backend (the actual main function of ScummVM is <tt>scummvm_main</tt>, which your backend must invoke at some point). | # Make sure to provide the <tt>main</tt> function in your backend (the actual main function of ScummVM is <tt>scummvm_main</tt>, which your backend must invoke at some point). | ||
# Instantiate the OSystem class and assign it to <tt>g_system</tt>, do that before calling <tt>scumm_main</tt>. | |||
# Deinit properly after calling <tt>scumm_main</tt>, particularly call <tt>g_system->destroy()</tt>. | |||
# If appropriate, edit <tt>configure</tt> to add your backend (this is only necessary if you are going to use the "./configure && make" build system). | # If appropriate, edit <tt>configure</tt> to add your backend (this is only necessary if you are going to use the "./configure && make" build system). | ||
==== Example of minimal main() ==== | |||
<syntaxhighlight lang="cpp">int main(int argc, char *argv[]) { | |||
// Create our OSystem instance | |||
g_system = new OSystem_Foobar(); | |||
assert(g_system); | |||
// Invoke the actual ScummVM main entry point: | |||
int res = scummvm_main(argc, argv); | |||
// Free OSystem | |||
g_system->destroy(); | |||
return res; | |||
}</syntaxhighlight> | |||
That's it. The difficult part is of course writing the OSystem subclass. More on that in the next section! | 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 [https://doxygen.scummvm.org/d2/d38/class_o_system.html OSystem class] 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 <tt>common/system.h</tt> 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 Channel|IRC]] or via [[Mailing lists|email]] :-). | |||
=== | === Implementing subsystems === | ||
* [[HOWTO-Backends/File system]] | |||
* [[HOWTO-Backends/Mutexes and Timers]] | |||
* [[HOWTO-Backends/Graphics]] | |||
* [[HOWTO-Backends/Events]] | |||
* [[HOWTO-Backends/Audio]] | |||
* [[HOWTO-Backends/Plugins]] | |||
* [[HOWTO-Backends/Miscellaneous]] | |||
==== Testing your backend ==== | |||
We have a special game engine, called 'testbed'. Its only purpose is to perform series of tests which help backend authors to see correctness of their implementation. | |||
To run the game, point ScummVM to directory <tt><scummvm sources root>/dists/engine-data/testbed-audiocd-files/</tt> and then run. Follow the on-screen instructions. | |||
=== Misc notes === | === 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! | There is a [[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! |
edits