[Scummvm-devel] PORTERS/ENGINES: Graphics transaction extension

[Johannes Schickel]

Hi,

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.

ENGINES:

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 
even segfault!

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 
block.

PORTERS:

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 
transaction details
  -> 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 
OSystem_SDL::beginGFXTransaction.

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.

// Johannes