[Scummvm-devel] The geometry of ScummVM

[Marcus Comstedt]

Ok, I've noticed that the OSystem API has been extended with
overlayScales and cursorTargetScale.  While trying to figure out how
these are supposed to work, I got a minor headache just from trying to
remember how the various coordinate systems worked before.  So I'm
going to try to formally define how the different display layers
should be composed, and I'll hope somebody corrects me if I make an
incorrect definition.

First of all, we have the "screen", the backmost layer.  This has a
size of W  by H , specified as parameters to the initSize() function.
         s     s
The backend tries to make this screen fit the visible part of the
display, possibly applying "aspect correction", giving each pixel an
          ^    ^                                       _
extent of x by y, and placing the upper left corner at T.  However,
there is also a ShakePos, z.  A pixel (x,y) in the "screen" layer will
therefore appear at position

 _   _     ^           ^
 S = T + x x + (y + z) y .


Now, the overlay.  Previously this was always 320x200, and the same
scale as the "screen", meaning that for larger screen sizes (CoMI) it
would not cover the entire "screen".  (At least this is how I
implemented it in the DC backend, and it seemed to work.)  However,
now there is a scale factor q passed to initSize().  Looking at the
SDL backend, this seems to set the pixel size of the overlay as a
multiple of the pixel size of the "screen", i.e. the overlay will have
the size

  W  = q W ,   H  = q H
   o      s     o      s

If I assume that the intention is for the overlay to occupy exactly
the same space as the "screen", this means that a pixel (u,v) in the
overlay should appear at position

 _   _   1   ^    1        ^
 O = T + - u x + (- v + z) y .
         q        q

Is this correct?  What about the semantics for grabOverlay?  How many,
and which, "screen" pixels should it "grab"?  Should each "screen"
pixel be repeated q² times in the output?  The result might not be
visually identical to how the "screen" looks if e.g. bilinear
interpolation is activated.

Next the mouse pointer layer.  Here we have a new scale factor p, but
the interpretation is less obvious.  Does it mean that each pixel in
the mouse plane should occupy the same area as p² pixels in the
"screen" plane?  Or is it the other way around?

The mouse has a pair of hotspot coordinates (i,j) set by
setMouseCursor(), and a logical position (k,l) set by
setMousePos()/warpMouse().  Assuming that (i,j) are in the coordinate
system of the cursor, and (k,l) in the coordinate system of the
"screen", a pixel (m,n) in the cursor should appear at position

 _   _                  ^                      ^
 M = T + (k + p(m - i)) x + (l + p(n - j) + z) y

Or should that be 1/p?


  // Marcus