[Scummvm-devel] PORTERS/ENGINES: Graphics transaction extension
lordhoto at gmail.com
Fri Nov 14 23:48:07 CET 2008
I guess most of you have seen my previous mail "PORTERS/ENGINES: Backend
graphics handling improvements". I finnished my graphics transaction
rollback patch now and committed it to trunk with r35062. Check the commit
logs for the in detail changes.
Both porters and engine authors are affected by this change. I'll start with
the changes for the engine authors since it's less.
Basically now we extended the (still optional) backend graphics transaction
to return error values rather than quitting inside the backend on invalid
graphics mode/resolution change. To achieve this OSystem::endGFXTransaction
returns ORed error flag values, for precise errors check the documentation
in common/system.h. You, the engine authors, have now two ways of updating
your engine for it:
- Use ::initGraphics as defined in engines/engine.h (I did that for all
engines currently in trunk btw.), that's the easiest solution if you don't
want/need to care about resolution change failures etc. It will
automatically display a warning and/or an error to the user if something
fails in the graphics transactions. It'll also quit ScummVM on failure.
If you're fine with this you might just skip the rest of the mail, still
please check if I didn't accidently made any mistake while this update.
- Use the OSystem graphics transaction API, thus
OSystem::beginGFXTransaction, OSystem::endGFXTransaction, directly.
When doing so you have to be aware that, when the backend returns the flag
OSystem::kTransactionSizeChangeFailed it will not have updated to the new
values you passed to OSystem::initSize in the transaction. Basically the
backend can be in two states now:
-> It switched back to the old resolution, means the size set up before
(i.e. in the launcher when the game was launched from there)
-> It has no screen setup, thus all graphics operations will fail or might
OSystem::kTransactionSizeChangeFailed is the only critical error currently,
so it is propbably the only one you really need to care about. For the
others check common/system.h
Another important thing is that you now can only enable aspect ratio
correctio, fullscreen and graphics mode changes in a graphics transaction
I checked which backends use graphics transactions and which not:
Backends using transactions: SDL, GP2x, WinCE, Symbian, MAEMO
All the other backends seem not to use graphics transactions.
For those porters not implementing graphics transactions nothing changed.
The default OSystem::endGFXTransaction implementation will return no error,
so you have to handle all problems backend internally and thus you might
have to quit ScummVM on critiacal failure like OSystem::initSize failure.
If you're one of the porters for those devices you can simply skip the rest
of the mail.
If you're a porter for a backend supporting backend transactions, which are
basically all SDL backend subclasses and GP2X, please read on.
It seems to me that GP2X is rather a rip off of the SDL backend instead of a
subclass, thus I think it should be rather easy to support backend
transactions with looking at the SDL changes in r35062 and the following
information. Of course things like mode changes (which basically is only
important for user graphics modes/'scalers') can probably be left out. If
you have any questions about this feel free to ask me, I'll help as much as
I can with a smooth update.
A summarized list of our changes:
- behavior of various backend functions changed:
-> loadGFXMode is only called from endGFXTransaction and hotswapGFXMode
now. Both now return a boolean for success indication.
-> setFullscreenMode and setAspectRatioCorrection changed to only update
-> setGraphicsMode now only updates transaction details, for enabling the
scaler the newly introduced setGraphicsModeIntern has to be used
-> loadGFXMode now returns a bool to indicate success or failure
-> on failure endGFXTransaction will fall back to the old mode
- the following member variables have been removed/been replaced:
-> _screenWidth -> _videoMode.screenWidth
-> _screenHeight -> _videoMode.screenHeight
-> _overlayWidth -> _videoMode.overlayWidth
-> _overlayHeight -> _videoMode.overlayHeight
-> _adjustAspectRatio -> _videoMode.aspectRatio
-> _scaleFactor -> _videoMode.scaleFactor
-> _mode -> _videoMode.mode
-> _fullscreen -> _videoMode.fullscreen
- Also the 'TransactionDetails' struct has been significantly stripped
- A definition of the old video mode '_oldVideoMode' for transaction
implementation has been added, helpful if you want to overwrite
OSystem_SDL::endGFXTransaction for your backend.
JFYI OSystem_SDL::endGFXTransaction is currently non-virtual, so you would
have to change that, if you feel there's need for overwriting it in your
backend(s). This structure will be automatically be set up by
For in detail changes please check the commit log. Again if you have any
questions about the changes feel free to drop me a mail.
More information about the Scummvm-devel