Attn porters: GraphicsManager updates may need your attention!

Hi porters,

GraphicsManager code has been refactored for the next ScummVM release in
order to harmonise some code across the SDL Surface and OpenGL backends,
and to remove unnecessary recalculations of coordinates, etc. that made
the old code difficult to maintain.

The newly updated code introduces a new WindowedGraphicsManager
superclass, which now sits in between the existing GraphicsManager class
and the SurfaceSdlGraphicsManager and OpenGlGraphicsManager classes.
This class maintains information about the dimensions of the window in
which ScummVM is rendered and the display area for the ScummVM content
within the bounds of that window. It converts mouse coordinates between
the window’s coordinate system and the game’s coordinate system in a
generic way that does not require special handling by ports.

As a result, ports should be easier to write and should need to do much
less work than before in order to provide a good user experience!

Here’s a brief Q&A about how to do things with the new
WindowedGraphicsManager:

Q. How do I render the game within a window/screen of a specific dimension?
A. Call `handleResize` with the width and height of the entire screen
area. The new code handles dimensions scaling, image centring, and AR
correction automatically, so you do not need to do anything special.

Q. I have an custom renderer. How do I decide where to draw?
A. `_activeArea.drawRect` is the calculated rectangle where content
should be rendered. This rectangle is already aspect ratio corrected, so
the port should render to exactly the given dimensions, stretching the
backbuffer if necessary. `_activeArea` will automatically update to the
correct size when switching between the game and the overlay (launcher).

Q. My port’s display hardware has non-square pixels. What should I do?
A. Override `recalculateDisplayAreas` and calculate the draw rect by
applying the correct PAR.

Q. My port’s display has a non-integral scaling ratio and can only use
point sampling. What should I do so things don’t look awful?
A. Please submit a patch to add an integer scaling option to the default
`WindowedGraphicsManager::recalculateDisplayAreas` implementation and
then proceed as normal, or just proceed as normal and wait for this
feature to be implemented in a future update.

Q. How do I translate mouse coordinates to/from the game?
A. You don’t need to do this any more (i.e. you do not need any
`translateMouseCoordinates`). WindowedGraphicsManager handles the
translation.

Q. What do I do about aspect ratio correction?
A. `_activeArea.drawRect` has any AR correction already applied, so you
just need to draw to that rect. For SurfaceSdlGraphicsManager
subclasses, continue to set `_videoMode.aspectRatioCorrection` for the
moment; otherwise, override `gameNeedsAspectRatioCorrection` to tell
WindowedGraphicsManager when to apply 8:5 PAR correction when
calculating the draw rect.

Q. I am implementing a backend where the window size may change. What do
I do?
A. Implement `handleResizeImpl` if the default SDL implementation
doesn’t work for you, and call `handleResize` whenever the window size
changes from an external source.

Q. My port has a hardware cursor. How do I handle mouse warps and
showing/hiding the mouse?
A. If the default SDL implementations work for you, you don’t have to do
anything. Otherwise, implement `setSystemMousePosition` for mouse warps.
The coordinates received will be already translated to the system’s
coordinates, relative to the window. Override `showMouse` for
showing/hiding the mouse.

Q. My port’s host environment only has relative mouse control (gamepad,
etc.). What do I do?
A. Make sure to call to grab the mouse immediately on startup.
Otherwise, the virtual mouse will feel “stuck” at the edges when the
game’s aspect ratio does not match the device’s aspect ratio.

Q. I don’t know how to do something. Should I cut and paste code out of
the official ports’ GraphicsManager code and then tweak it slightly and
then submit that as my port code?
A. Please don’t :). If you can’t find an appropriate extension point for
your port’s functionality, talk to myself or another ScummVM team member
about finding or making one.

Here are the specific known-breaking API changes to
SurfaceSdlGraphicsManager:

* `translateMouseCoordinates` -> removed. Make sure the
(already-existing)
`getWidth`/`getHeight`/`getOverlayWidth`/`getOverlayHeight` return
correct values. If you need to translate a coordinate for some reason
(this should probably never happen, so say something if you feel the
need to do this!), use `convertVirtualToWindow`/`convertWindowToVirtual`.
* `effectiveScreenHeight` -> removed. Set the
`_videoMode.hardwareHeight` by calculating using the value returned by
`getDesiredGameAspectRatio`. Note that there is still some old
AR-correcting code in the GraphicsManager implementations, which is due
to be replaced in a future update, so please do not use this older code
as a guide for best practices when writing your port.
* `_hwscreen` -> renamed to _hwScreen to match OpenGL
* `_forceFull` -> renamed to _forceRedraw to match OpenGL
* `_mouseVisible` -> renamed to _cursorVisible to match OpenGL
* `_mouseNeedsRedraw` -> renamed to _cursorNeedsRedraw to match OpenGL
* `_mouseCurState.x/y` -> replaced with `_cursorX/Y` to match OpenGL.
These values are now stored in host system coordinates, not game
coordinates.

Thank you for your hard work bringing ScummVM to more devices.

Best,

-- 
Colin Snover
https://zetafleet.com


_______________________________________________
Scummvm-devel mailing list
[email protected]
http://lists.scummvm.org/listinfo/scummvm-devel