736
edits
Difference between revisions of "HOWTO-Backends"
m
fix typos, wording, wikify, the usual
(→updateScreen() method: added note about possible screen update skipping) |
m (fix typos, wording, wikify, the usual) |
||
| Line 8: | Line 8: | ||
=== 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 [http://doxygen.scummvm.org/d9/df4/classOSystem.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? :-)) ("snafu" would have been better :-P). | ||
# Create a new <code>backends/platform</code> subdirectory matching your port name, i.e. <tt>backends/platform/foobar/</tt> | # 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/platform/foobar/module.mk</tt> file. Take a look at <code>backends/platform/sdl/module.mk</code> for an example. | # 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/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. | # 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 OSystem class and assign it to <tt>g_system</tt>, do that before calling <tt>scumm_main</tt> | # 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->quit()</tt> | # Deinit properly after calling <tt>scumm_main</tt>, particularly call <tt>g_system->quit()</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). | ||
| Line 37: | Line 37: | ||
=== Subclassing OSystem === | === 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://doxygen.scummvm.org/d9/df4/classOSystem.html 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 | 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://doxygen.scummvm.org/d9/df4/classOSystem.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]] :-). | ||
=== 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! | ||
==== updateScreen() method ==== | ==== 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 | The 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 a restriction on how many times per second screen blitting takes place. For example, some NTSC version can not physically update more often than 60 Hz, and attempts to make it more often will result in the machine to hang. | ||
If you | If you are writing a backend for such a system, you may use code like this: | ||
<syntax type="C++">void updateScreen() { | <syntax type="C++">void updateScreen() { | ||
| Line 57: | Line 57: | ||
}</syntax> | }</syntax> | ||
That should do the trick for you. This code has the slight disadvantage that | That should do the trick for you. This code has the slight disadvantage that it skips some screen updates though. This means there is a possibility that it skips an important screen update, which is not followed by any other screen update for some time, leading to some graphics glitch. | ||