Logo Search packages:      
Sourcecode: scummvm version File versions  Download package

OSystem Class Reference

#include <system.h>

Inheritance diagram for OSystem:


List of all members.

Detailed Description

Interface for ScummVM backends. If you want to port ScummVM to a system which is not currently covered by any of our backends, this is the place to start. ScummVM will create an instance of a subclass of this interface and use it to interact with the system.

In particular, a backend provides a video surface for ScummVM to draw in; methods to create timers, to handle user input events, control audio CD playback, and sound output.

Definition at line 66 of file system.h.

Feature flags

enum  Feature {
  kFeatureFullscreenMode, kFeatureAspectRatioCorrection, kFeatureVirtualKeyboard, kFeatureAutoComputeDirtyRects,
  kFeatureCursorHasPalette, kFeatureOverlaySupportsAlpha, kFeatureIconifyWindow, kFeatureDisableKeyFiltering
virtual bool getFeatureState (Feature f)
virtual bool hasFeature (Feature f)
virtual void setFeatureState (Feature f, bool enable)

Mutex handling

Historically, the OSystem API used to have a method which allowed creating threads. Hence mutex support was needed for thread syncing. To ease portability, though, we decided to remove the threading API. Instead, we now use timers (see setTimerCallback() and Common::Timer). But since those may be implemented using threads (and in fact, that's how our primary backend, the SDL one, does it on many systems), we still have to do mutex syncing in our timer callbacks. In addition, the sound mixer uses a mutex in case the backend runs it from a dedicated thread (as e.g. the SDL backend does).

Hence backends which do not use threads to implement the timers simply can use dummy implementations for these methods.

typedef struct OpaqueMutex * MutexRef
virtual MutexRef createMutex ()=0
virtual void deleteMutex (MutexRef mutex)=0
virtual void lockMutex (MutexRef mutex)=0
virtual void unlockMutex (MutexRef mutex)=0


The way graphics work in the class OSystem are meant to make it possible for game frontends to implement all 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 in three layers: the game graphics, the overlay graphics, and the mouse.

First, there are the game graphics. They are always 8bpp, and 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 8bpp data 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, the may be scaled to better fit on 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. We define p_w and p_h to be the width resp. height of a game pixel on the screen.

In addition, there is a vertical "shake offset" (as defined by setShakePos) which 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. We denote the shake offset 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. By default, it has exactly the same size and resolution as the game graphics. However, client code can specify an overlay scale (as an additional parameter to initSize()). This is meant to increase the resolution of the overlay while keeping its size the same as that of the game graphics. For example, if the overlay scale is 2, and the game graphics have a resolution of 320x200; then the overlay shall have a resolution of 640x400, but it still has the same physical size as the game graphics. The overlay usually uses 16bpp, but on some ports, only 8bpp are availble, so that is supported, too, via a compile time switch (see also the OverlayColor typedef in scummsys.h).

Finally, there is the mouse layer. This layer doesn't have to actually exist within the backend -- it all depends on how a backend chooses to implement mouse cursors, but in the default SDL backend, it really is a separate layer. The mouse is always in 8bpp but can have a palette of its own, if the backend supports it. The scale of the mouse cursor is called 'cursorTargetScale'. This is meant as a hint to the backend. For example, let us assume the overlay is not visible, and the game graphics are displayed using a 2x scaler. If a mouse cursor with a cursorTargetScale of 1 is set, then it should be scaled by factor 2x, too, just like the game graphics. But if it has a cursorTargetScale of 2, then it shouldn't be scaled again by the game graphics scaler.

enum  TransactionError {
  kTransactionSuccess = 0, kTransactionAspectRatioFailed = (1 << 0), kTransactionFullscreenFailed = (1 << 1), kTransactionModeSwitchFailed = (1 << 2),
  kTransactionSizeChangeFailed = (1 << 3)
virtual void beginGFXTransaction ()
virtual void clearFocusRectangle ()
virtual void copyRectToScreen (const byte *buf, int pitch, int x, int y, int w, int h)=0
virtual TransactionError endGFXTransaction ()
virtual void fillScreen (uint32 col)=0
virtual int getDefaultGraphicsMode () const =0
virtual int getGraphicsMode () const =0
virtual int16 getHeight ()=0
virtual int getScreenChangeID () const
virtual const GraphicsModegetSupportedGraphicsModes () const =0
virtual int16 getWidth ()=0
virtual void grabPalette (byte *colors, uint start, uint num)=0
virtual void initSize (uint width, uint height)=0
virtual Graphics::SurfacelockScreen ()=0
virtual void setFocusRectangle (const Common::Rect &rect)
bool setGraphicsMode (const char *name)
virtual bool setGraphicsMode (int mode)=0
virtual void setPalette (const byte *colors, uint start, uint num)=0
virtual void setShakePos (int shakeOffset)=0
virtual void unlockScreen ()=0
virtual void updateScreen ()=0

Public Member Functions

virtual void engineDone ()
virtual void engineInit ()
virtual void initBackend ()

virtual void addSysArchivesToSearchSet (Common::SearchSet &s, int priority=0)
createConfigReadStream ()=0
virtual Common::WriteStreamcreateConfigWriteStream ()=0
virtual void displayMessageOnOSD (const char *msg)=0
virtual FilesystemFactorygetFilesystemFactory ()=0
virtual Common::SaveFileManagergetSavefileManager ()=0
virtual void quit ()=0
virtual void setWindowCaption (const char *caption)
In order to be able to display dialogs atop the game graphics, backends must provide an overlay mode.

While the game graphics are always 8 bpp, the overlay can be 8 or 16 bpp. Depending on which it is, OverlayColor is 8 or 16 bit.

For 'coolness' we usually want to have an overlay which is blended over the game graphics. On backends which support alpha blending, this is no issue; but on other systems (in particular those which only support 8bpp), this needs some trickery.

Essentially, we fake (alpha) blending on these systems by copying the current game graphics into the overlay buffer when activating the overlay, then manually compose whatever graphics we want to show in the overlay. This works because we assume the game to be "paused" whenever an overlay is active.

virtual void clearOverlay ()=0
virtual void copyRectToOverlay (const OverlayColor *buf, int pitch, int x, int y, int w, int h)=0
virtual Graphics::PixelFormat getOverlayFormat () const =0
virtual int16 getOverlayHeight ()=0
virtual int16 getOverlayWidth ()=0
virtual void grabOverlay (OverlayColor *buf, int pitch)=0
virtual void hideOverlay ()=0
virtual void showOverlay ()=0
Events and Time

virtual void delayMillis (uint msecs)=0
virtual Common::EventManagergetEventManager ()=0
virtual Common::HardwareKeySet * getHardwareKeySet ()
virtual uint32 getMillis ()=0
virtual void getTimeAndDate (struct tm &t) const =0
virtual Common::TimerManager * getTimerManager ()=0
This is the lower level implementation as provided by the backends. The engines should use the Graphics::CursorManager class instead of using it directly.

virtual void disableCursorPalette (bool disable)
virtual void setCursorPalette (const byte *colors, uint start, uint num)
virtual void setMouseCursor (const byte *buf, uint w, uint h, int hotspotX, int hotspotY, byte keycolor=255, int cursorTargetScale=1)=0
virtual bool showMouse (bool visible)=0
virtual void warpMouse (int x, int y)=0

virtual Audio::MixergetMixer ()=0
Audio CD
The methods in this group deal with Audio CD playback. The default implementation simply does nothing. This is the lower level implementation as provided by the backends. The engines should use the Audio::AudioCDManager class instead of using it directly.

virtual bool openCD (int drive)
virtual void playCD (int track, int num_loops, int start_frame, int duration)
virtual bool pollCD ()
virtual void stopCD ()
virtual void updateCD ()


struct  GraphicsMode

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index