[Scummvm-devel] Bitdepth/pixel format API concerns

[Johannes Schickel]

J Northup wrote:
>
>
> On Thu, Jun 11, 2009 at 7:08 AM, Max Horn <max at quendi.de 
> <mailto:max at quendi.de>> wrote:
>
>
>     So far, I see no actual cons to using Graphics::PixelFormat -- I
>     think LordHoto refuted all claims otherwise so far. Maybe we miss
>     something, though -- then I'd like to hear concrete arguments,
>     though ;).
>
>
>     Bye,
>     Max
>
>
>
> Sigh, I should have made a posting to the list right after the 
> conversation LordHoto and I had on IRC wednesday night.
> The cons to using Graphics::PixelFormat are
> 1) It is overkill -- it easily allows engines to specify a format that 
> is completely impossible, by mistake

And the engine author would easily notice it, because his screen would 
look strange. So? It's like that they have a typo in the enum...

> 2) It requires the engine to specify color order, meaning that a minor 
> oversight on the part of the engine developer could result in it being 
> unusable on all backends with a different color order.

Why? Your idea was anyway to let the backend worry about such 
conversions, thus it would work just fine. Maybe explain this to me again.

> 3) Additionally, the wide range of color orders that the engine could 
> potentially request necessitate a great deal of sanity checking on the 
> part of engines that only support one.

I still don't get this one, sorry.

> 4) Setting up a Graphics::PixelFormat structure takes a minimum of 8 
> lines of code per structure. Engines like gob and groovie which 
> convert from YUV have to set up a list of several, and the difference 
> in coding required adds up over the course of three current and an 
> unknown number of future supported engines.

GOB and Groovie won't have to setup any PixelFormat struct. They'll just 
use the backend function to query all native pixel formats, you didn't 
implement that yet though :-).

With the SDL backend this isn't really possible, since you can first be 
sure to see the mode it chooses, when you setup a real video mode. So we 
might need to think about that. Maybe we'll just return that no pixel 
format can be used natively. Thus the engine just uses the best mode it 
supports and let the SDL backend worry about conversions. This might 
need some more thought!

> The compromise that LordHoto and I came to on IRC is thus:
> Engines use the colormode enum type, and pass a list of supported 
> colormodes to initGraphics.

Yes.

> initGraphics gets the color order (RGBA, ABGR) from the backend, and 
> converts the colormode enums.

No the color order has to be fixed, if the engine requests RGB555, it 
has to be R, G, B order. An engine not doing any conversions can't 
easily switch between RGBA and ABGR, the screen would look wrong.

> into Graphics::PixelFormat structures using a generic function 
> provided for this purpose.
> initGraphics queries the backend regarding format compatibility, and 
> passes the first compatible format to the backend for initialization 
> during the gfx transaction.

Yes. (for cases, there's no natively supported format, check the next 
answer).

> initGraphics errors out if endGfxTransaction returns an error in 
> setting up the screen with requested pixel format
> engines query backend to determine the accepted pixel format

No, if there's no native supported format, the backend should do 
conversions. I thought we did agree on that.

> When loading graphical resources, engines call a generic color-order 
> swapping function as necessary.

Kirben told me that those conversions would make the SCUMM code much 
more complex, but I'm not exactly sure. Kirben, maybe you can comment on 
this again? Anyway since the backend is forced to do conversion, this 
isn't exactly needed, it might be used by engine authors when they 
expire performance problems on certain backends. (See the mail from Max 
on 9th of July 10:54 AM).

> This way, engines get the simplicity of the enum type, but backends do 
> not have to worry about dealing with any format but Graphics::PixelFormat.
> I am working on the proof of concept for this, but if there are any 
> complaints about this remaining, I will go ahead with one that uses 
> Graphics::PixelFormat exclusively.

Just for completeness, here's how I think it should work:

The backend is required to implement the following functionality:

"initFormat", used for initializing a specific format. This takes a 
PixelFormat.
"queryNativeFormats", this returns a list of PixelFormat structs 
supported without conversion by the backend.
"getScreenFormat", used to return the currently setup PixelFormat.

Now there are different possibilites:

1) The engine can work with any mode out there:

In this case the engine should just use "queryNativeFormats" and select 
the one it thinks would be best. If there's no natively supported 
format, let it setup *any* format and let the backend worry how to deal 
with it.

ALTERNATIVE proposal: let OSystem::initFormat take a pointer to a 
PixelFormat, if that one is zero, let the backend choose the mode it 
thinks is best for it. The engines will then just use the format 
returned by "getScreenFormat".

That alternative proposal might be best for the SDL backend, since it'll 
first know the native mode when it has the video mode setup via 
SDL_SetVideoMode.

2) The engine has a limited set of formats (at least 2):

Let the engine pass a list of the enums to "initGraphics", as you 
proposed. "initGraphics" is now supposed to use the first format 
supported natively by the backend. If not it errors out. (One could 
think of some default graphics mode parameter, which will be used then 
no format has native supported, so the backend does conversion).

All this is implemented by comparing requested formats to the return 
value of "OSystem::queryNativeFormats".

3) The engine can only work with a single format:

Pass that mode directly to initFormat and let the backend worry about 
conversions to it's native mode.

// Johannes