The way graphics work in the OSystem class is meant to make it possible for game frontends to implement everything they need in an efficient manner. The downside of this is that it may be rather complicated for backend authors to fully understand and implement the semantics of the OSystem interface.
The graphics visible to the user in the end are actually composed of three layers: the game graphics, the overlay graphics, and the mouse.
First, there are the game graphics. The methods in this section deal with them exclusively. In particular, the size of the game graphics is defined by a call to initSize(), and copyRectToScreen() blits the data in the current pixel format into the game layer. Let W and H denote the width and height of the game graphics.
Before the user sees these graphics, the backend may apply some transformations to it. For example, they may be scaled to better fit the visible screen or aspect ratio correction may be performed (see kFeatureAspectRatioCorrection). As a result of this, a pixel of the game graphics may occupy a region bigger than a single pixel on the screen. p_w and p_h are defined to be the width and, respectively, height of a game pixel on the screen.
In addition, there is a vertical "shake offset" (as defined by setShakePos) that is used in some games to provide a shaking effect. Note that shaking is applied to all three layers, i.e. also to the overlay and the mouse. The shake offset is denoted by S.
Putting this together, a pixel (x,y) of the game graphics is transformed to a rectangle of height p_h and width p_w appearing at position (p_w * x, p_hw * (y + S)) on the real screen. In addition, a backend may choose to offset everything, e.g. to center the graphics on the screen.
The next layer is the overlay. It is composed over the game graphics. Historically, the overlay size had always been a multiple of the game resolution. For example, if the game resolution was 320x200 and the user selected a 2x scaler and did not enable aspect ratio correction, it had a size of 640x400. An exception was the aspect ratio correction, which did allow for non multiples of the vertical resolution of the game screen. Currently, the overlay size does not need to have any relation to the game resolution though, for example the overlay resolution might be the same as the physical screen resolution. The overlay is forced to a 16 bpp mode right now.
Finally, there is the mouse layer. This layer does not have to actually exist within the backend – it all depends on how a backend chooses to implement mouse cursors. However, in the default SDL backend, it really is a separate layer. The mouse can have a palette of its own, if the backend supports it.
Graphics do not need to be thread-safe and in fact most/all backends using OpenGL are not. So do not try to call any of these functions from a timer and/or audio callback (like readBuffer of AudioStreams).
Classes | |
struct | OSystem::GraphicsMode |
Enumerations | |
enum | OSystem::GfxModeFlags { OSystem::kGfxModeNoFlags = 0, OSystem::kGfxModeRender3d = (1 << 0) } |
enum | OSystem::TransactionError { OSystem::kTransactionSuccess = 0, OSystem::kTransactionAspectRatioFailed = (1 << 0), OSystem::kTransactionFullscreenFailed = (1 << 1), OSystem::kTransactionModeSwitchFailed = (1 << 2), OSystem::kTransactionSizeChangeFailed = (1 << 3), OSystem::kTransactionFormatNotSupported = (1 << 4), OSystem::kTransactionFilteringFailed = (1 << 5), OSystem::kTransactionStretchModeSwitchFailed = (1 << 6) } |
Functions | |
virtual const GraphicsMode * | OSystem::getSupportedGraphicsModes () const |
virtual int | OSystem::getDefaultGraphicsMode () const |
virtual bool | OSystem::setGraphicsMode (int mode, uint flags=kGfxModeNoFlags) |
bool | OSystem::setGraphicsMode (const char *name) |
virtual int | OSystem::getGraphicsMode () const |
virtual void | OSystem::resetGraphicsScale () |
Graphics::PixelFormat | OSystem::getScreenFormat () const |
Common::List< Graphics::PixelFormat > | OSystem::getSupportedFormats () const |
virtual Common::Array< uint > | OSystem::getSupportedAntiAliasingLevels () const |
virtual const GraphicsMode * | OSystem::getSupportedShaders () const |
virtual int | OSystem::getDefaultShader () const |
virtual bool | OSystem::setShader (int id) |
bool | OSystem::setShader (const char *name) |
virtual int | OSystem::getShader () const |
virtual const GraphicsMode * | OSystem::getSupportedStretchModes () const |
virtual int | OSystem::getDefaultStretchMode () const |
virtual bool | OSystem::setStretchMode (int mode) |
bool | OSystem::setStretchMode (const char *name) |
virtual int | OSystem::getStretchMode () const |
virtual void | OSystem::initSize (uint width, uint height, const Graphics::PixelFormat *format=nullptr)=0 |
virtual void | OSystem::initSizeHint (const Graphics::ModeList &modes) |
virtual int | OSystem::getScreenChangeID () const |
virtual void | OSystem::beginGFXTransaction () |
virtual TransactionError | OSystem::endGFXTransaction () |
virtual int16 | OSystem::getHeight ()=0 |
virtual int16 | OSystem::getWidth ()=0 |
virtual PaletteManager * | OSystem::getPaletteManager ()=0 |
virtual void | OSystem::copyRectToScreen (const void *buf, int pitch, int x, int y, int w, int h)=0 |
virtual Graphics::Surface * | OSystem::lockScreen ()=0 |
virtual void | OSystem::unlockScreen ()=0 |
virtual void | OSystem::fillScreen (uint32 col)=0 |
virtual void | OSystem::updateScreen ()=0 |
virtual void | OSystem::setShakePos (int shakeXOffset, int shakeYOffset)=0 |
virtual void | OSystem::setFocusRectangle (const Common::Rect &rect) |
virtual void | OSystem::clearFocusRectangle () |
virtual void | OSystem::saveScreenshot () |
This type can save the different errors which can happen while changing GFX config values inside GFX transactions.
endGFXTransaction returns an ORed combination of the '*Failed' values if any problem occurs. It returns '0' on success.
|
inlinevirtual |
Retrieve a list of all graphics modes supported by this backend.
This can be both video modes as well as graphic filters/scalers. It is completely up to the backend maintainer to decide what is appropriate here and what not. The list is terminated by an all-zero entry.
|
inlinevirtual |
Return the ID of the 'default' graphics mode. What exactly this means is up to the backend. This mode is set by the client code when no user overrides are present (i.e. if no custom graphics mode is selected using the command line or a config file).
|
inlinevirtual |
Switch to the specified graphics mode.
If switching to the new mode fails, this method returns false.
The flag 'kGfxModeRender3d' is optional. It allows to switch to 3D-only rendering mode. In this mode, the game engine is allowed to use OpenGL(ES) directly.
mode | ID of the new graphics mode. |
flags | Flags for the new graphics mode. |
bool OSystem::setGraphicsMode | ( | const char * | name | ) |
Switch to the graphics mode with the given name.
If name
is unknown, or if switching to the new mode fails, this method returns false.
name | Name of the new graphics mode. |
|
inlinevirtual |
Determine which graphics mode is currently active.
|
inlinevirtual |
Set the graphics scale factor to x1.
Games with large screen sizes reset the scale to x1 so that the screen is not too big when starting the game.
|
inlinevirtual |
Retrieve a list of supported levels of anti-aliasing.
Anti-aliasing only works when using one of the hardware-accelerated renderers. An empty list means anti-aliasing is not supported.
|
inlinevirtual |
Retrieve a list of all hardware shaders supported by this backend.
This can be only hardware shaders. It is completely up to the backend maintainer to decide what is appropriate here and what not. The list is terminated by an all-zero entry.
|
inlinevirtual |
Return the ID of the 'default' shader mode.
What exactly this means is up to the backend. This mode is set by the client code when no user overrides are present (i.e. if no custom shader mode is selected using the command line or a config file).
|
inlinevirtual |
Switch to the specified shader mode.
If switching to the new mode fails, this method returns false.
id | ID of the new shader mode. |
bool OSystem::setShader | ( | const char * | name | ) |
Switch to the shader mode with the given name.
If name
is unknown, or if switching to the new mode fails, this method returns false.
name | Name of the new shader mode. |
|
inlinevirtual |
Determine which shader is currently active.
|
inlinevirtual |
Retrieve a list of all stretch modes supported by this backend.
It is completely up to the backend maintainer to decide what is appropriate here and what not. The list is terminated by an all-zero entry.
|
inlinevirtual |
Return the ID of the 'default' stretch mode.
What exactly this means is up to the backend. This mode is set by the client code when no user overrides are present (i.e. if no custom stretch mode is selected using the command line or a config file).
|
inlinevirtual |
Switch to the specified stretch mode.
If switching to the new mode fails, this method returns false.
mode | ID of the new graphics mode. |
bool OSystem::setStretchMode | ( | const char * | name | ) |
Switch to the stretch mode with the given name.
If name
is unknown, or if switching to the new mode fails, this method returns false.
name | Name of the new stretch mode. |
|
inlinevirtual |
Determine which stretch mode is currently active.
|
pure virtual |
Set the size and color format of the virtual screen.
Typical sizes include:
This is the resolution for which the client code generates data. This is not necessarily equal to the actual display size. For example, a backend may magnify the graphics to fit on the screen (see also the GraphicsMode), stretch the data to perform aspect ratio correction, or shrink it to fit on small screens (in cell phones).
Typical formats include:
This is the pixel format for which the client code generates data. It is not necessarily equal to the hardware pixel format. For example, a backend may perform color lookup of 8-bit graphics before pushing a screen to hardware, or correct the ARGB color order.
width | New virtual screen width. |
height | New virtual screen height. |
format | New virtual screen pixel format. |
|
inlinevirtual |
Send a list of graphics modes to the backend so it can make a decision about the best way to set up the display hardware.
Engines that switch between different virtual screen sizes during a game should call this function prior to any call to initSize. Engines that use only a single screen size do not need to call this function.
modes | List of graphics modes the engine will probably use. |
|
inlinevirtual |
Return an int value that is changed whenever any screen parameters (like the resolution) change, i.e. whenever EVENT_SCREEN_CHANGED is sent.
You can track this value in your code to detect screen changes in case you do not have full control over the event loop(s) being used (like the GUI code).
|
inlinevirtual |
Begin a new GFX transaction, which is a sequence of GFX mode changes.
The idea behind GFX transactions is to make it possible to activate several different GFX changes at once as a "batch" operation. For example, assume we are running in 320x200 with a 2x scaler (thus using 640x400 pixels in total). Now, we want to switch to 640x400 with the 1x scaler. Without transactions, we have to choose whether we want to first switch the scaler mode, or first to 640x400 mode. In either case, depending on the backend implementation, problems may occur. For example, the window might briefly switch to 320x200 or 1280x800. Using transactions, this can be avoided.
|
inlinevirtual |
End (and thereby commit) the current GFX transaction.
|
pure virtual |
Return the currently set virtual screen height.
|
pure virtual |
Return the currently set virtual screen width.
|
pure virtual |
Return the palette manager singleton.
For more information, see PaletteManager.
|
pure virtual |
Blit a bitmap to the virtual screen.
The real screen will not immediately be updated to reflect the changes. Client code must call updateScreen to ensure any changes are visible to the user. This can be used to optimize drawing and reduce flicker.
If the current pixel format has one byte per pixel, the graphics data uses 8 bits per pixel, using the palette specified via setPalette. If more than one byte per pixel is in use, the graphics data uses the pixel format returned by getScreenFormat.
buf | Buffer containing the graphics data source. |
pitch | Pitch of the buffer (number of bytes in a scanline). |
x | x coordinate of the destination rectangle. |
y | y coordinate of the destination rectangle. |
w | Width of the destination rectangle. |
h | Height of the destination rectangle. |
|
pure virtual |
Lock the active screen framebuffer and return a Graphics::Surface representing it.
The caller can then perform arbitrary graphics transformations on the framebuffer (blitting, scrolling, etc.). Must be followed by a matching call to unlockScreen(). Code that is calling this should make sure to only lock the framebuffer for the shortest time possible, as the whole system is potentially stalled while the lock is active.
The returned surface must not be deleted by the client code.
|
pure virtual |
Unlock the screen framebuffer, and mark it as dirty, i.e. during the next updateScreen() call, the whole screen will be updated.
|
pure virtual |
Fill the screen with the given color value.
|
pure virtual |
Flush the whole screen, i.e. render the current content of the screen framebuffer to the display.
This method may be called very often by engines. Backends are hence supposed to only perform any redrawing if it is necessary and otherwise return immediately. See https://wiki.scummvm.org/index.php/HOWTO-Backends#updateScreen.28.29_method
|
pure virtual |
Set current shake position, a feature needed for some SCUMM screen effects.
The effect causes the displayed graphics to be shifted upwards by the specified (always positive) offset. The area at the bottom of the screen which is moved into view by this is filled with black. This does not cause any graphic data to be lost. To restore the original view, the game engine only has to call this method again with offset equal to zero. No calls to copyRectToScreen are necessary.
shakeXOffset | Shake x offset. |
shakeYOffset | Shake y offset. |
|
inlinevirtual |
Set the area of the screen that has the focus.
For example, when a character is speaking, they will have the focus. This allows for pan-and-scan style views where the backend can follow the speaking character or area of interest on the screen.
The backend is responsible for clipping the rectangle and deciding how best to zoom the screen to show any shape and size rectangle the engine provides.
rect | Rectangle on the screen to be focused on. |
|
inlinevirtual |
Clear the focus set by a call to setFocusRectangle().
This allows the engine to clear the focus when no particular area of the screen has the focus.
|
inlinevirtual |
Instruct the backend to capture a screenshot of the current screen.
The backend can persist it the way it considers appropriate.