1 /* ScummVM - Graphic Adventure Engine 2 * 3 * ScummVM is the legal property of its developers, whose names 4 * are too numerous to list here. Please refer to the COPYRIGHT 5 * file distributed with this source distribution. 6 * 7 * This program is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU General Public License 9 * as published by the Free Software Foundation; either version 2 10 * of the License, or (at your option) any later version. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 20 * 21 */ 22 23 #ifndef COMMON_SYSTEM_H 24 #define COMMON_SYSTEM_H 25 26 #include "common/scummsys.h" 27 #include "common/noncopyable.h" 28 #include "common/array.h" // For OSystem::getGlobalKeymaps() 29 #include "common/list.h" // For OSystem::getSupportedFormats() 30 #include "common/ustr.h" 31 #include "graphics/pixelformat.h" 32 #include "graphics/pixelbuffer.h" 33 #include "graphics/mode.h" 34 35 namespace Audio { 36 class Mixer; 37 } 38 39 namespace Graphics { 40 struct Surface; 41 } 42 43 namespace GUI { 44 class GuiObject; 45 class OptionsContainerWidget; 46 } 47 48 namespace Common { 49 class EventManager; 50 struct Rect; 51 class SaveFileManager; 52 class SearchSet; 53 class String; 54 #if defined(USE_TASKBAR) 55 class TaskbarManager; 56 #endif 57 #if defined(USE_UPDATES) 58 class UpdateManager; 59 #endif 60 class TextToSpeechManager; 61 #if defined(USE_SYSDIALOGS) 62 class DialogManager; 63 #endif 64 class TimerManager; 65 class SeekableReadStream; 66 class WriteStream; 67 class HardwareInputSet; 68 class Keymap; 69 class KeymapperDefaultBindings; 70 71 typedef Array<Keymap *> KeymapArray; 72 } 73 74 /** 75 * @defgroup common_system OSystem 76 * @ingroup common 77 * 78 * @brief API related to OSystem - the main interface for ScummVM backends. 79 * 80 * @{ 81 */ 82 83 class AudioCDManager; 84 class FilesystemFactory; 85 class PaletteManager; 86 87 /** 88 * Structure describing time and date. 89 * 90 * This is a clone of struct @c tm from time.h. 91 * We implement our own since not all systems provide time.h. 92 * This is not a one-to-one replacement of the @c tm struct, 93 * as only the fields that we need were added. 94 * 95 * @note For now, the members are named exactly as in struct @c tm to ease 96 * the transition. 97 */ 98 struct TimeDate { 99 int tm_sec; /**< Seconds (0 - 60). */ 100 int tm_min; /**< Minutes (0 - 59). */ 101 int tm_hour; /**< Hours (0 - 23). */ 102 int tm_mday; /**< Day of month (1 - 31). */ 103 int tm_mon; /**< Month of year (0 - 11). */ 104 int tm_year; /**< Year - 1900. */ 105 int tm_wday; /**< Days since Sunday (0 - 6). */ 106 }; 107 108 namespace LogMessageType { 109 /** 110 * Enumeration for log message types. 111 * @ingroup common_system 112 * 113 */ 114 enum Type { 115 kInfo, /**< Info logs. */ 116 kError, /**< Error logs. */ 117 kWarning, /**< Warning logs. */ 118 kDebug /**< Debug logs. */ 119 }; 120 121 } // End of namespace LogMessageType 122 123 /** 124 * Interface for ScummVM backends. 125 * 126 * If you want to port ScummVM to a system that is not currently 127 * covered by any of our backends, this is the place to start. 128 * ScummVM will create an instance of a subclass of this interface 129 * and use it to interact with the system. 130 * 131 * In particular, a backend provides: 132 * 133 * - A video surface for ScummVM to draw in 134 * - Methods to create timers 135 * - Methods to handle user input events 136 * - Control audio CD playback 137 * - Sound output 138 */ 139 class OSystem : Common::NonCopyable { 140 protected: 141 OSystem(); 142 virtual ~OSystem(); 143 144 protected: 145 /** 146 * @defgroup common_system_module Subsystem modules 147 * @ingroup common_system 148 * @{ 149 * 150 * For backend authors only, the following pointers (= "slots") to various 151 * subsystem managers / factories / etc. can and should be set to 152 * a suitable instance of the respective type. 153 * 154 * For some of the slots, a default instance is set if your backend 155 * does not do so. For details, refer to the documentation of 156 * each slot. 157 * 158 * A backend may set up slot values in its initBackend() method, 159 * its constructor, or somewhere in between. But it must set a slot's value 160 * no later than in its initBackend() implementation, because 161 * OSystem::initBackend() will create any default instances if 162 * none have been set yet (and for other slots, will verify that 163 * one has been set; if not, an error may be generated). 164 */ 165 166 /** 167 * No default value is provided for _audiocdManager by OSystem. 168 * However, BaseBackend::initBackend() does set a default value 169 * if none has been set before. 170 * 171 * @note _audiocdManager is deleted by the OSystem destructor. 172 */ 173 AudioCDManager *_audiocdManager; 174 175 /** 176 * No default value is provided for _eventManager by OSystem. 177 * However, EventsBaseBackend::initBackend() does set a default value 178 * if none has been set before. 179 * 180 * @note _eventManager is deleted by the OSystem destructor. 181 */ 182 Common::EventManager *_eventManager; 183 184 /** 185 * No default value is provided for _timerManager by OSystem. 186 * 187 * @note _timerManager is deleted by the OSystem destructor. 188 */ 189 Common::TimerManager *_timerManager; 190 191 /** 192 * No default value is provided for _savefileManager by OSystem. 193 * 194 * @note _savefileManager is deleted by the OSystem destructor. 195 */ 196 Common::SaveFileManager *_savefileManager; 197 198 #if defined(USE_TASKBAR) 199 /** 200 * No default value is provided for _taskbarManager by OSystem. 201 * 202 * @note _taskbarManager is deleted by the OSystem destructor. 203 */ 204 Common::TaskbarManager *_taskbarManager; 205 #endif 206 207 #if defined(USE_UPDATES) 208 /** 209 * No default value is provided for _updateManager by OSystem. 210 * 211 * @note _updateManager is deleted by the OSystem destructor. 212 */ 213 Common::UpdateManager *_updateManager; 214 #endif 215 216 /** 217 * No default value is provided for _textToSpeechManager by OSystem. 218 * 219 * @note _textToSpeechManager is deleted by the OSystem destructor. 220 */ 221 Common::TextToSpeechManager *_textToSpeechManager; 222 223 #if defined(USE_SYSDIALOGS) 224 /** 225 * No default value is provided for _dialogManager by OSystem. 226 * 227 * @note _dialogManager is deleted by the OSystem destructor. 228 */ 229 Common::DialogManager *_dialogManager; 230 #endif 231 232 /** 233 * No default value is provided for _fsFactory by OSystem. 234 * 235 * Note that _fsFactory is typically required very early on, 236 * so it usually should be set in the backends constructor or shortly 237 * thereafter, and before initBackend() is called. 238 * 239 * @note _fsFactory is deleted by the OSystem destructor. 240 */ 241 FilesystemFactory *_fsFactory; 242 243 /** 244 * Used by the default clipboard implementation, for backends that don't 245 * implement clipboard support. 246 */ 247 Common::U32String _clipboard; 248 249 /** Workaround for a bug in the osx_intel toolchain introduced by 250 * 014bef9eab9fb409cfb3ec66830e033e4aaa29a9. Adding this variable fixes it. 251 */ 252 bool _dummyUnused; 253 /** @} */ 254 private: 255 /** 256 * Indicate if initBackend() has been called. 257 */ 258 bool _backendInitialized; 259 260 //@} 261 262 public: 263 264 /** 265 * Destoy this OSystem instance. 266 */ 267 void destroy(); 268 269 /** 270 * Call this method once, after g_system is created. 271 */ init()272 virtual void init() {} 273 274 /** 275 * The following method is called once, from main.cpp, after all 276 * config data (including command line params etc.) is fully loaded. 277 * 278 * @note Subclasses should always invoke the implementation of their 279 * parent class. They should do so near the end of their own 280 * implementation. 281 */ 282 virtual void initBackend(); 283 284 /** 285 * Return false if initBackend() has not yet been called and true otherwise. 286 * 287 * Some functionalities such as mutexes cannot be used until the backend 288 * is initialized. 289 */ backendInitialized()290 bool backendInitialized() const { return _backendInitialized; } 291 292 /** 293 * Allow the backend to perform engine-specific initialization. 294 * 295 * Called just before the engine is run. 296 */ engineInit()297 virtual void engineInit() { } 298 299 /** 300 * Allow the backend to perform engine-specific deinitialization. 301 * 302 * Called after the engine finishes. 303 */ engineDone()304 virtual void engineDone() { } 305 306 /** 307 * @defgroup common_system_flags Feature flags 308 * @ingroup common_system 309 * @{ 310 */ 311 312 /** 313 * A feature in this context means an ability of the backend which can be 314 * either on or off. 315 * 316 * Examples include: 317 * - Fullscreen mode 318 * - Aspect ration correction 319 * - Virtual keyboard for text entry (on PDAs) 320 * 321 * There is a difference between the *availability* of a feature 322 * that can be checked using hasFeature(), and its *state*. 323 * For example, the SDL backend *has* the kFeatureFullscreenMode, 324 * so hasFeature returns true for it. On the other hand, 325 * fullscreen mode may be active or not. This can be determined 326 * by checking the state using getFeatureState(). Finally, to 327 * switch between fullscreen and windowed mode, use setFeatureState(). 328 * 329 * Some features, for example kFeatureClipboardSupport and kFeatureOpenUrl 330 * have no state and can only be used to check if the corresponding feature 331 * is available or not. Calling getFeatureState() or setFeatureState() 332 * for them is pointless. 333 */ 334 enum Feature { 335 /** 336 * If supported, this feature flag can be used to switch between 337 * windowed and fullscreen mode. 338 */ 339 kFeatureFullscreenMode, 340 341 /** 342 * Control aspect ratio correction. 343 * 344 * Aspect ratio correction is used for correcting games running at 320x200 345 * (i.e with an aspect ratio of 8:5), but which on their original hardware 346 * were displayed with the standard 4:3 ratio 347 * (which means that the original graphics used non-square pixels). 348 * When the backend supports this, then games running at 349 * 320x200 pixels should be scaled up to 320x240 pixels. 350 * For all other resolutions, ignore this feature flag. 351 * 352 * @note Backend implementors can find utility functions in common/scaler.h. 353 * These functions can be used to implement aspect ratio correction. 354 * You can use stretch200To240() can stretch a rect, including (very fast) 355 * particular, interpolation, and works in-place. 356 */ 357 kFeatureAspectRatioCorrection, 358 359 /** 360 * If supported, this flag can be used to switch between unfiltered and 361 * filtered graphics modes. 362 */ 363 kFeatureFilteringMode, 364 365 /** 366 * Indicate if stretch modes are supported by the backend. 367 */ 368 kFeatureStretchMode, 369 370 /** 371 * Determine whether a virtual keyboard is to be shown or not. 372 * This would mostly be implemented by backends for handheld devices, 373 * like PocketPC, Palms, Symbian phones like the P800, Zaurus, etc. 374 */ 375 kFeatureVirtualKeyboard, 376 377 /** 378 * Backends supporting this feature allow specifying a custom palette 379 * for the cursor. The custom palette is used if the feature state 380 * is set to true by the client code using setFeatureState(). 381 * 382 * It is currently used only by some Macintosh versions of Humongous 383 * Entertainment games. If the backend doesn't implement this feature 384 * then the engine switches to b/w versions of cursors. 385 * The GUI also relies on this feature for mouse cursors. 386 */ 387 kFeatureCursorPalette, 388 389 /** 390 * A backend has this feature if its overlay pixel format has an alpha 391 * channel which offers at least 3-4 bits of accuracy (as opposed to 392 * just a single alpha bit). 393 * 394 * This feature has no associated state. 395 */ 396 kFeatureOverlaySupportsAlpha, 397 398 /** 399 * Client code can set the state of this feature to true in order to 400 * iconify the application window. 401 */ 402 kFeatureIconifyWindow, 403 404 /** 405 * This feature flag can be used to check if hardware-accelerated 406 * OpenGL is supported and can be used for 3D game rendering. 407 */ 408 kFeatureOpenGLForGame, 409 410 /** 411 * If supported, this feature flag can be used to check if 412 * waiting for vertical sync before refreshing the screen to reduce 413 * tearing is enabled. 414 */ 415 kFeatureVSync, 416 417 /** 418 * When a backend supports this feature, it guarantees the graphics 419 * context is not destroyed when switching to and from fullscreen. 420 * 421 * For OpenGL, that means the context is kept with all of its content: 422 * texture, programs, etc. 423 * 424 * For TinyGL, that means the backbuffer surface is kept. 425 */ 426 kFeatureFullscreenToggleKeepsContext, 427 428 /** 429 * The presence of this feature indicates whether the displayLogFile() 430 * call is supported. 431 * 432 * This feature has no associated state. 433 */ 434 kFeatureDisplayLogFile, 435 436 /** 437 * The presence of this feature indicates whether the system clipboard is 438 * available. 439 * 440 * If this feature is not present, the hasTextInClipboard(), 441 * getTextFromClipboard(), and setTextInClipboard() calls can still be used, 442 * however it should not be used in scenarios where the user is expected to 443 * copy data outside of the application. 444 * 445 * This feature has no associated state. 446 */ 447 kFeatureClipboardSupport, 448 449 /** 450 * The presence of this feature indicates whether the openUrl() 451 * call is supported. 452 * 453 * This feature has no associated state. 454 */ 455 kFeatureOpenUrl, 456 457 /** 458 * Show on-screen control. 459 */ 460 kFeatureOnScreenControl, 461 462 /** 463 * Mouse emulation mode. 464 */ 465 kFeatureTouchpadMode, 466 467 /** 468 * Swap menu and back buttons. 469 */ 470 kFeatureSwapMenuAndBackButtons, 471 472 /** 473 * Keyboard mouse and joystick mouse speed. 474 */ 475 kFeatureKbdMouseSpeed, 476 477 /** 478 * Change analog joystick deadzone. 479 */ 480 kFeatureJoystickDeadzone, 481 482 /** 483 * Scalers. 484 */ 485 kFeatureScalers, 486 487 /** 488 * Shaders. 489 */ 490 kFeatureShader, 491 492 /** 493 * Support for using the native system file browser dialog 494 * through the DialogManager. 495 */ 496 kFeatureSystemBrowserDialog, 497 498 /** 499 * For platforms that should not have a Quit button. 500 */ 501 kFeatureNoQuit 502 }; 503 504 /** 505 * Determine whether the backend supports the specified feature. 506 */ hasFeature(Feature f)507 virtual bool hasFeature(Feature f) { return false; } 508 509 /** 510 * Enable or disable the specified feature. 511 * 512 * For example, this may be used to enable fullscreen mode 513 * or to deactivate aspect correction, etc. 514 */ setFeatureState(Feature f,bool enable)515 virtual void setFeatureState(Feature f, bool enable) {} 516 517 /** 518 * Query the state of the specified feature. 519 * 520 * For example, test whether fullscreen mode is active or not. 521 */ getFeatureState(Feature f)522 virtual bool getFeatureState(Feature f) { return false; } 523 524 /** @} */ 525 526 527 528 /** 529 * @defgroup common_system_graphics Graphics 530 * @ingroup common_system 531 * @{ 532 * 533 * The way graphics work in the OSystem class is meant to make 534 * it possible for game frontends to implement everything they need in 535 * an efficient manner. The downside of this is that it may be 536 * rather complicated for backend authors to fully understand and 537 * implement the semantics of the OSystem interface. 538 * 539 * The graphics visible to the user in the end are actually 540 * composed of three layers: the game graphics, the overlay 541 * graphics, and the mouse. 542 * 543 * First, there are the game graphics. The methods in this section 544 * deal with them exclusively. In particular, the size of the game 545 * graphics is defined by a call to initSize(), and 546 * copyRectToScreen() blits the data in the current pixel format 547 * into the game layer. Let W and H denote the width and height of 548 * the game graphics. 549 * 550 * Before the user sees these graphics, the backend may apply some 551 * transformations to it. For example, they may be scaled to better 552 * fit the visible screen or aspect ratio correction may be 553 * performed (see kFeatureAspectRatioCorrection). As a result of 554 * this, a pixel of the game graphics may occupy a region bigger 555 * than a single pixel on the screen. p_w and p_h are defined to be 556 * the width and, respectively, height of a game pixel on the screen. 557 * 558 * In addition, there is a vertical "shake offset" (as defined by 559 * setShakePos) that is used in some games to provide a shaking 560 * effect. Note that shaking is applied to all three layers, i.e. 561 * also to the overlay and the mouse. The shake offset is denoted 562 * by S. 563 * 564 * Putting this together, a pixel (x,y) of the game graphics is 565 * transformed to a rectangle of height p_h and width p_w 566 * appearing at position (p_w * x, p_hw * (y + S)) on the real 567 * screen. In addition, a backend may choose to offset 568 * everything, e.g. to center the graphics on the screen. 569 * 570 * The next layer is the overlay. It is composed over the game 571 * graphics. Historically, the overlay size had always been a 572 * multiple of the game resolution. For example, if the game 573 * resolution was 320x200 and the user selected a 2x scaler and did 574 * not enable aspect ratio correction, it had a size of 640x400. 575 * An exception was the aspect ratio correction, which did allow 576 * for non multiples of the vertical resolution of the game screen. 577 * Currently, the overlay size does not need to have any relation to 578 * the game resolution though, for example the overlay resolution 579 * might be the same as the physical screen resolution. 580 * The overlay is forced to a 16 bpp mode right now. 581 * 582 * Finally, there is the mouse layer. This layer does not have to 583 * actually exist within the backend -- it all depends on how a 584 * backend chooses to implement mouse cursors. However, in the default 585 * SDL backend, it really is a separate layer. The mouse can 586 * have a palette of its own, if the backend supports it. 587 * 588 * Graphics do not need to be thread-safe and in fact most/all backends 589 * using OpenGL are not. So do *not* try to call any of these functions 590 * from a timer and/or audio callback (like readBuffer of AudioStreams). 591 */ 592 593 /** 594 * Description of a graphics mode. 595 */ 596 struct GraphicsMode { 597 /** 598 * The name of the graphics mode. 599 * 600 * This name is matched when selecting a mode using the command line 601 * or using the config file. Examples: "1x", "advmame2x", "hq3x". 602 */ 603 const char *name; 604 /** 605 * Human-readable description of the scaler. 606 * 607 * Examples: "Normal (no scaling)", "AdvMAME2x", "HQ3x". 608 */ 609 const char *description; 610 /** 611 * ID of the graphics mode. 612 * 613 * How to use this is entirely up to the backend. This value is passed 614 * to the setGraphicsMode(int) method by the client code. 615 */ 616 int id; 617 }; 618 619 /** 620 * Retrieve a list of all graphics modes supported by this backend. 621 * 622 * This can be both video modes as well as graphic filters/scalers. 623 * It is completely up to the backend maintainer to decide what is 624 * appropriate here and what not. 625 * The list is terminated by an all-zero entry. 626 * 627 * @return List of supported graphics modes. 628 */ getSupportedGraphicsModes()629 virtual const GraphicsMode *getSupportedGraphicsModes() const { 630 static const GraphicsMode noGraphicsModes[] = {{"NONE", "Normal", 0}, {nullptr, nullptr, 0 }}; 631 return noGraphicsModes; 632 } 633 634 /** 635 * Return the ID of the 'default' graphics mode. What exactly this means 636 * is up to the backend. This mode is set by the client code when no user 637 * overrides are present (i.e. if no custom graphics mode is selected using 638 * the command line or a config file). 639 * 640 * @return ID of the 'default' graphics mode. 641 */ getDefaultGraphicsMode()642 virtual int getDefaultGraphicsMode() const { return 0; } 643 644 enum GfxModeFlags { 645 kGfxModeNoFlags = 0, /**< No flags. */ 646 kGfxModeRender3d = (1 << 0) /**< Indicate 3D hardware-accelerated in-game GFX. */ 647 }; 648 649 /** 650 * Switch to the specified graphics mode. 651 * 652 * If switching to the new mode fails, this method returns false. 653 * 654 * The flag 'kGfxModeRender3d' is optional. It allows to switch to 3D-only rendering mode. 655 * In this mode, the game engine is allowed to use OpenGL(ES) directly. 656 * 657 * @param mode ID of the new graphics mode. 658 * @param flags Flags for the new graphics mode. 659 * 660 * @return True if the switch was successful, false otherwise. 661 */ 662 virtual bool setGraphicsMode(int mode, uint flags = kGfxModeNoFlags) { return (mode == 0); } 663 664 /** 665 * Switch to the graphics mode with the given name. 666 * 667 * If @p name is unknown, or if switching to the new mode fails, this method returns false. 668 * 669 * @param name Name of the new graphics mode. 670 * 671 * @return True if the switch was successful, false otherwise. 672 * 673 * @note This is implemented using the setGraphicsMode(int) method, as well 674 * as getSupportedGraphicsModes() and getDefaultGraphicsMode(). 675 * In particular, backends do not have to overload this! 676 */ 677 bool setGraphicsMode(const char *name); 678 679 /** 680 * Determine which graphics mode is currently active. 681 * 682 * @return ID of the active graphics mode. 683 */ getGraphicsMode()684 virtual int getGraphicsMode() const { return 0; } 685 686 #ifdef USE_RGB_COLOR 687 /** 688 * Determine the pixel format currently in use for screen rendering. 689 * 690 * @return the active screen pixel format. 691 * 692 * @see Graphics::PixelFormat 693 */ 694 virtual Graphics::PixelFormat getScreenFormat() const = 0; 695 696 /** 697 * Return a list of all pixel formats supported by the backend. 698 * 699 * The first item in the list must be directly supported by hardware 700 * and provide the largest color space of those formats with direct 701 * hardware support. It is also strongly recommended that remaining 702 * formats are placed in the order of descending preference for the 703 * backend to use. 704 * 705 * Example: a backend that supports 32-bit ABGR and 16-bit 555 BGR in hardware 706 * and provides conversion from equivalent RGB(A) modes should order its list 707 * in the following way: 708 * 1) Graphics::PixelFormat(4, 0, 0, 0, 0, 0, 8, 16, 24) 709 * 2) Graphics::PixelFormat(2, 3, 3, 3, 8, 0, 5, 10, 0) 710 * 3) Graphics::PixelFormat(4, 0, 0, 0, 0, 24, 16, 8, 0) 711 * 4) Graphics::PixelFormat(2, 3, 3, 3, 8, 10, 5, 0, 0) 712 * 5) Graphics::PixelFormat::createFormatCLUT8() 713 * 714 * @see Graphics::PixelFormat 715 * 716 * @note Backends supporting RGB color should accept game data in RGB color 717 * order, even if hardware uses BGR or some other color order. 718 */ 719 virtual Common::List<Graphics::PixelFormat> getSupportedFormats() const = 0; 720 #else getScreenFormat()721 inline Graphics::PixelFormat getScreenFormat() const { 722 return Graphics::PixelFormat::createFormatCLUT8(); 723 } 724 getSupportedFormats()725 inline Common::List<Graphics::PixelFormat> getSupportedFormats() const { 726 Common::List<Graphics::PixelFormat> list; 727 list.push_back(Graphics::PixelFormat::createFormatCLUT8()); 728 return list; 729 } 730 #endif 731 732 /** 733 * Retrieve a list of supported levels of anti-aliasing. 734 * 735 * Anti-aliasing only works when using one of the hardware-accelerated 736 * renderers. An empty list means anti-aliasing is not supported. 737 */ getSupportedAntiAliasingLevels()738 virtual Common::Array<uint> getSupportedAntiAliasingLevels() const { 739 return Common::Array<uint>(); 740 } 741 742 /** 743 * Retrieve a list of all hardware shaders supported by this backend. 744 * 745 * This can be only hardware shaders. 746 * It is completely up to the backend maintainer to decide what is 747 * appropriate here and what not. 748 * The list is terminated by an all-zero entry. 749 * 750 * @return List of supported shaders. 751 */ getSupportedShaders()752 virtual const GraphicsMode *getSupportedShaders() const { 753 static const OSystem::GraphicsMode no_shader[2] = {{"NONE", "Normal (no shader)", 0}, {nullptr, nullptr, 0}}; 754 return no_shader; 755 } 756 757 /** 758 * Return the ID of the 'default' shader mode. 759 * 760 * What exactly this means is up to the backend. 761 * This mode is set by the client code when no user overrides 762 * are present (i.e. if no custom shader mode is selected using 763 * the command line or a config file). 764 * 765 * @return ID of the 'default' shader mode. 766 */ getDefaultShader()767 virtual int getDefaultShader() const { return 0; } 768 769 /** 770 * Switch to the specified shader mode. 771 * 772 * If switching to the new mode fails, this method returns false. 773 * 774 * @param id ID of the new shader mode. 775 * 776 * @return True if the switch was successful, false otherwise. 777 */ setShader(int id)778 virtual bool setShader(int id) { return false; } 779 780 /** 781 * Switch to the shader mode with the given name. 782 * 783 * If @p name is unknown, or if switching to the new mode fails, 784 * this method returns false. 785 * 786 * @param name Name of the new shader mode. 787 * 788 * @return True if the switch was successful, false otherwise. 789 * 790 * @note This is implemented using the setShader(int) method, as well 791 * as getSupportedShaders() and getDefaultShader(). 792 * In particular, backends do not have to overload this! 793 */ 794 bool setShader(const char *name); 795 796 /** 797 * Determine which shader is currently active. 798 * 799 * @return ID of the active shader. 800 */ getShader()801 virtual int getShader() const { return 0; } 802 803 /** 804 * Retrieve a list of all stretch modes supported by this backend. 805 * 806 * It is completely up to the backend maintainer to decide what is 807 * appropriate here and what not. 808 * The list is terminated by an all-zero entry. 809 * 810 * @return a list of supported stretch modes 811 */ getSupportedStretchModes()812 virtual const GraphicsMode *getSupportedStretchModes() const { 813 static const GraphicsMode noStretchModes[] = {{"NONE", "Normal", 0}, {nullptr, nullptr, 0 }}; 814 return noStretchModes; 815 } 816 817 /** 818 * Return the ID of the 'default' stretch mode. 819 * 820 * What exactly this means is up to the backend. This mode is set 821 * by the client code when no user overrides are present 822 * (i.e. if no custom stretch mode is selected using the command line or a config file). 823 * 824 * @return ID of the 'default' graphics mode. 825 */ getDefaultStretchMode()826 virtual int getDefaultStretchMode() const { return 0; } 827 828 /** 829 * Switch to the specified stretch mode. 830 * 831 * If switching to the new mode fails, this method returns false. 832 * 833 * @param mode ID of the new graphics mode. 834 * 835 * @return True if the switch was successful, false otherwise. 836 */ setStretchMode(int mode)837 virtual bool setStretchMode(int mode) { return false; } 838 839 /** 840 * Switch to the stretch mode with the given name. 841 * 842 * If @p name is unknown, or if switching to the new mode fails, 843 * this method returns false. 844 * 845 * @param name Name of the new stretch mode. 846 * 847 * @return True if the switch was successful, false otherwise. 848 * 849 * @note This is implemented using the setStretchMode(int) method, as well 850 * as getSupportedStretchModes() and getDefaultStretchMode(). 851 * In particular, backends do not have to overload this! 852 */ 853 bool setStretchMode(const char *name); 854 855 /** 856 * Determine which stretch mode is currently active. 857 * 858 * @return ID of the active stretch mode. 859 */ getStretchMode()860 virtual int getStretchMode() const { return 0; } 861 862 /** 863 * Return the ID of the 'default' scaler. 864 * 865 * This mode is set by the client code when no user overrides 866 * are present (i.e. if no custom scaler is selected using the 867 * command line or a config file). 868 * 869 * @return ID of the 'default' scaler. 870 */ getDefaultScaler()871 virtual uint getDefaultScaler() const { return 0; } 872 873 /** 874 * Return the 'default' scale factor. 875 * 876 * This mode is set by the client code when no user overrides 877 * are present (i.e. if no custom shader mode is selected using 878 * the command line or a config file). 879 * 880 * @return The 'default' scale factor. 881 */ getDefaultScaleFactor()882 virtual uint getDefaultScaleFactor() const { return 1; } 883 884 /** 885 * Switch to the specified scaler. 886 * 887 * If switching to the new mode fails, this method returns false. 888 * 889 * @param mode ID of the new scaler. 890 * @param factor The scale factor to use 891 * 892 * @return True if the switch was successful, false otherwise. 893 */ setScaler(uint mode,int factor)894 virtual bool setScaler(uint mode, int factor) { return false; } 895 896 /** 897 * Switch to the scaler with the given name. 898 * 899 * If @p name is unknown, or if switching to the new mode fails, 900 * this method returns false. 901 * 902 * @param name Name of the new scaler. 903 * @param factor The scale factor to use 904 * 905 * @return True if the switch was successful, false otherwise. 906 */ setScaler(const char * name,int factor)907 virtual bool setScaler(const char *name, int factor) { return false; } 908 909 /** 910 * Determine which scaler is currently active. 911 * 912 * @return ID of the active stretch mode. 913 */ getScaler()914 virtual uint getScaler() const { return 0; } 915 916 /** 917 * Determine which scale factor is currently active. 918 * 919 * @return The active scale factor. 920 */ getScaleFactor()921 virtual uint getScaleFactor() const { return 1; } 922 923 924 /** 925 * Set the size and color format of the virtual screen. 926 * 927 * Typical sizes include: 928 * - 320x200 (e.g. for most SCUMM games, and Simon) 929 * - 320x240 (e.g. for FM-TOWN SCUMM games) 930 * - 640x480 (e.g. for Curse of Monkey Island) 931 * 932 * This is the resolution for which the client code generates data. 933 * This is not necessarily equal to the actual display size. For example, 934 * a backend may magnify the graphics to fit on the screen (see also the 935 * GraphicsMode), stretch the data to perform aspect ratio correction, 936 * or shrink it to fit on small screens (in cell phones). 937 * 938 * Typical formats include: 939 * - CLUT8 (e.g. 256 color, for most games) 940 * - RGB555 (e.g. 16-bit color, for later SCUMM HE games) 941 * - RGB565 (e.g. 16-bit color, for Urban Runner) 942 * 943 * This is the pixel format for which the client code generates data. 944 * It is not necessarily equal to the hardware pixel format. For example, 945 * a backend may perform color lookup of 8-bit graphics before pushing 946 * a screen to hardware, or correct the ARGB color order. 947 * 948 * @param width New virtual screen width. 949 * @param height New virtual screen height. 950 * @param format New virtual screen pixel format. 951 */ 952 virtual void initSize(uint width, uint height, const Graphics::PixelFormat *format = nullptr) = 0; 953 954 /** 955 * Send a list of graphics modes to the backend so it can make a decision 956 * about the best way to set up the display hardware. 957 * 958 * Engines that switch between different virtual screen sizes during a game 959 * should call this function prior to any call to initSize. Engines that use 960 * only a single screen size do not need to call this function. 961 * 962 * @param modes List of graphics modes the engine will probably use. 963 */ initSizeHint(const Graphics::ModeList & modes)964 virtual void initSizeHint(const Graphics::ModeList &modes) {} 965 966 /** 967 * Return an int value that is changed whenever any screen 968 * parameters (like the resolution) change, i.e. whenever 969 * EVENT_SCREEN_CHANGED is sent. 970 * 971 * You can track this value in your code to detect screen changes in case 972 * you do not have full control over the event loop(s) 973 * being used (like the GUI code). 974 * 975 * @return Integer that can be used to track screen changes. 976 * 977 * @note Backends that generate EVENT_SCREEN_CHANGED events must 978 * overload this method appropriately. 979 */ getScreenChangeID()980 virtual int getScreenChangeID() const { return 0; } 981 982 /** 983 * Begin a new GFX transaction, which is a sequence of GFX mode changes. 984 * 985 * The idea behind GFX transactions is to make it possible to activate 986 * several different GFX changes at once as a "batch" operation. For 987 * example, assume we are running in 320x200 with a 2x scaler (thus using 988 * 640x400 pixels in total). Now, we want to switch to 640x400 with the 1x 989 * scaler. Without transactions, we have to choose whether we want to first 990 * switch the scaler mode, or first to 640x400 mode. In either case, 991 * depending on the backend implementation, problems may occur. 992 * For example, the window might briefly switch to 320x200 or 1280x800. 993 * Using transactions, this can be avoided. 994 * 995 * @note Transaction support is optional, and the default implementations 996 * of the relevant methods simply do nothing. 997 * 998 * @see endGFXTransaction 999 */ beginGFXTransaction()1000 virtual void beginGFXTransaction() {} 1001 1002 /** 1003 * This type can save the different errors which can happen while 1004 * changing GFX config values inside GFX transactions. 1005 * 1006 * endGFXTransaction returns an ORed combination of the '*Failed' values 1007 * if any problem occurs. It returns '0' on success. 1008 * 1009 * @see endGFXTransaction 1010 */ 1011 enum TransactionError { 1012 kTransactionSuccess = 0, /**< Everything fine (use EQUAL check for this one!) */ 1013 kTransactionAspectRatioFailed = (1 << 0), /**< Failed switching aspect ratio correction mode */ 1014 kTransactionFullscreenFailed = (1 << 1), /**< Failed switching fullscreen mode */ 1015 kTransactionModeSwitchFailed = (1 << 2), /**< Failed switching the GFX graphics mode (setGraphicsMode) */ 1016 kTransactionSizeChangeFailed = (1 << 3), /**< Failed switching the screen dimensions (initSize) */ 1017 kTransactionFormatNotSupported = (1 << 4), /**< Failed setting the color format */ 1018 kTransactionFilteringFailed = (1 << 5), /**< Failed setting the filtering mode */ 1019 kTransactionStretchModeSwitchFailed = (1 << 6) /**< Failed setting the stretch mode */ 1020 }; 1021 1022 /** 1023 * End (and thereby commit) the current GFX transaction. 1024 * 1025 * @see beginGFXTransaction 1026 * @see kTransactionError 1027 * 1028 * @return ORed combination of TransactionError values or 0 on success. 1029 */ endGFXTransaction()1030 virtual TransactionError endGFXTransaction() { return kTransactionSuccess; } 1031 1032 /** 1033 * Return the currently set virtual screen height. 1034 * 1035 * @see initSize 1036 * 1037 * @return Currently set virtual screen height. 1038 */ 1039 virtual int16 getHeight() = 0; 1040 1041 /** 1042 * Return the currently set virtual screen width. 1043 * 1044 * @see initSize 1045 * 1046 * @return Currently set virtual screen width. 1047 */ 1048 virtual int16 getWidth() = 0; 1049 1050 /** 1051 * Return the palette manager singleton. 1052 * 1053 * For more information, see @ref PaletteManager. 1054 */ 1055 virtual PaletteManager *getPaletteManager() = 0; 1056 1057 /** 1058 * Return the scale factor for HiDPI screens. 1059 * Returns 1 for non-HiDPI screens, or if HiDPI display is not supported by the backend. 1060 */ getHiDPIScreenFactor()1061 virtual float getHiDPIScreenFactor() const { return 1.0f; } 1062 1063 /** 1064 * Blit a bitmap to the virtual screen. 1065 * 1066 * The real screen will not immediately be updated to reflect the changes. 1067 * Client code must call updateScreen to ensure any changes are visible 1068 * to the user. This can be used to optimize drawing and reduce flicker. 1069 * 1070 * If the current pixel format has one byte per pixel, the graphics data 1071 * uses 8 bits per pixel, using the palette specified via setPalette. 1072 * If more than one byte per pixel is in use, the graphics data uses the 1073 * pixel format returned by getScreenFormat. 1074 * 1075 * @param buf Buffer containing the graphics data source. 1076 * @param pitch Pitch of the buffer (number of bytes in a scanline). 1077 * @param x x coordinate of the destination rectangle. 1078 * @param y y coordinate of the destination rectangle. 1079 * @param w Width of the destination rectangle. 1080 * @param h Height of the destination rectangle. 1081 * 1082 * @note The specified destination rectangle must be completly contained 1083 * in the visible screen space, and must be non-empty. If not, a 1084 * backend may or may not perform clipping, trigger an assert, or 1085 * silently corrupt memory. 1086 * 1087 * @see updateScreen 1088 * @see getScreenFormat 1089 */ 1090 virtual void copyRectToScreen(const void *buf, int pitch, int x, int y, int w, int h) = 0; 1091 1092 /** 1093 * Lock the active screen framebuffer and return a Graphics::Surface 1094 * representing it. 1095 * 1096 * The caller can then perform arbitrary graphics transformations 1097 * on the framebuffer (blitting, scrolling, etc.). 1098 * Must be followed by a matching call to unlockScreen(). 1099 * Code that is calling this should make sure to only lock the framebuffer 1100 * for the shortest time possible, as the whole system is potentially stalled 1101 * while the lock is active. 1102 * 1103 * @return 0 if an error occurs. Otherwise, a surface with the pixel 1104 * format described by getScreenFormat is returned. 1105 * 1106 * The returned surface must *not* be deleted by the client code. 1107 * 1108 * @see getScreenFormat 1109 */ 1110 virtual Graphics::Surface *lockScreen() = 0; 1111 1112 /** 1113 * Unlock the screen framebuffer, and mark it as dirty, i.e. during the 1114 * next updateScreen() call, the whole screen will be updated. 1115 */ 1116 virtual void unlockScreen() = 0; 1117 1118 /** 1119 * Fill the screen with the given color value. 1120 */ 1121 virtual void fillScreen(uint32 col) = 0; 1122 1123 /** 1124 * Flush the whole screen, i.e. render the current content of the screen 1125 * framebuffer to the display. 1126 * 1127 * This method may be called very often by engines. Backends are hence 1128 * supposed to only perform any redrawing if it is necessary and otherwise 1129 * return immediately. See 1130 * <https://wiki.scummvm.org/index.php/HOWTO-Backends#updateScreen.28.29_method> 1131 */ 1132 virtual void updateScreen() = 0; 1133 1134 /** 1135 * Set current shake position, a feature needed for some SCUMM screen 1136 * effects. 1137 * 1138 * The effect causes the displayed graphics to be shifted upwards 1139 * by the specified (always positive) offset. The area at the bottom of the 1140 * screen which is moved into view by this is filled with black. This does 1141 * not cause any graphic data to be lost. To restore the original 1142 * view, the game engine only has to call this method again with offset 1143 * equal to zero. No calls to copyRectToScreen are necessary. 1144 * 1145 * @param shakeXOffset Shake x offset. 1146 * @param shakeYOffset Shake y offset. 1147 * 1148 * @note This is currently used in the SCUMM, QUEEN, KYRA, SCI, DREAMWEB, 1149 * SUPERNOVA, TEENAGENT, TOLTECS, ULTIMA, and PETKA engines. 1150 */ 1151 virtual void setShakePos(int shakeXOffset, int shakeYOffset) = 0; 1152 1153 /** 1154 * Set the area of the screen that has the focus. 1155 * 1156 * For example, when a character is speaking, they will have the focus. 1157 * This allows for pan-and-scan style views where the backend 1158 * can follow the speaking character or area of interest on the screen. 1159 * 1160 * The backend is responsible for clipping the rectangle and deciding how best to 1161 * zoom the screen to show any shape and size rectangle the engine provides. 1162 * 1163 * @param rect Rectangle on the screen to be focused on. 1164 * 1165 * @see clearFocusRectangle 1166 */ setFocusRectangle(const Common::Rect & rect)1167 virtual void setFocusRectangle(const Common::Rect& rect) {} 1168 1169 /** 1170 * Clear the focus set by a call to setFocusRectangle(). 1171 * 1172 * This allows the engine to clear the focus when no particular area 1173 * of the screen has the focus. 1174 * 1175 * @see setFocusRectangle 1176 */ clearFocusRectangle()1177 virtual void clearFocusRectangle() {} 1178 1179 /** 1180 * Instruct the backend to capture a screenshot of the current screen. 1181 * 1182 * The backend can persist it the way it considers appropriate. 1183 */ saveScreenshot()1184 virtual void saveScreenshot() {} 1185 1186 /** @} */ 1187 1188 1189 /** 1190 * @defgroup common_system_overlay Overlay 1191 * @ingroup common_system 1192 * @{ 1193 * 1194 * To display dialogs atop the game graphics, backends 1195 * must provide an overlay mode. 1196 * 1197 * The overlay is currently forced at 16 bpp. 1198 * 1199 * For 'coolness' we usually want to have an overlay that is blended over 1200 * the game graphics. On backends that support alpha blending, this is 1201 * no issue but on other systems this needs some trickery. 1202 * 1203 * Essentially, we fake (alpha) blending on these systems by copying the 1204 * current game graphics into the overlay buffer when activating the overlay, 1205 * and then manually compose whatever graphics we want to show in the overlay. 1206 * This works because we assume the game to be "paused" whenever an overlay 1207 * is active. 1208 */ 1209 1210 /** Activate the overlay mode. */ 1211 virtual void showOverlay() = 0; 1212 1213 /** Deactivate the overlay mode. */ 1214 virtual void hideOverlay() = 0; 1215 1216 /** Return true if the overlay mode is activated, false otherwise. */ 1217 virtual bool isOverlayVisible() const = 0; 1218 1219 /** 1220 * Return the pixel format description of the overlay. 1221 * 1222 * @see Graphics::PixelFormat 1223 */ 1224 virtual Graphics::PixelFormat getOverlayFormat() const = 0; 1225 1226 /** 1227 * Reset the overlay. 1228 * 1229 * After calling this method while the overlay mode is active, the user 1230 * should be seeing only the game graphics. How this is achieved depends 1231 * on how the backend implements the overlay. It either sets all pixels of 1232 * the overlay to be transparent (when alpha blending is used) or, 1233 * in case of fake alpha blending, it might just put a copy of the 1234 * current game graphics screen into the overlay. 1235 */ 1236 virtual void clearOverlay() = 0; 1237 1238 /** 1239 * Copy the content of the overlay into a surface provided by the 1240 * caller. 1241 * 1242 * This is only used to implement fake alpha blending. 1243 */ 1244 virtual void grabOverlay(Graphics::Surface &surface) = 0; 1245 1246 /** 1247 * Blit a graphics buffer to the overlay. 1248 * 1249 * In a sense, this is the reverse of grabOverlay. 1250 * 1251 * @param buf Buffer containing the graphics data source. 1252 * @param pitch Pitch of the buffer (number of bytes in a scanline). 1253 * @param x x coordinate of the destination rectangle. 1254 * @param y y coordinate of the destination rectangle. 1255 * @param w Width of the destination rectangle. 1256 * @param h Height of the destination rectangle. 1257 * 1258 * @see copyRectToScreen 1259 * @see grabOverlay 1260 */ 1261 virtual void copyRectToOverlay(const void *buf, int pitch, int x, int y, int w, int h) = 0; 1262 1263 /** 1264 * Return the height of the overlay. 1265 * 1266 * @see getHeight 1267 */ 1268 virtual int16 getOverlayHeight() = 0; 1269 1270 /** 1271 * Return the width of the overlay. 1272 * 1273 * @see getWidth 1274 */ 1275 virtual int16 getOverlayWidth() = 0; 1276 1277 /** @} */ 1278 1279 1280 1281 /** @defgroup common_system_mouse Mouse 1282 * @ingroup common_system 1283 * @{ 1284 * 1285 * This is the lower level implementation as provided by the 1286 * backends. The engines should use the Graphics::CursorManager 1287 * class instead of using this directly. 1288 */ 1289 1290 1291 /** 1292 * Show or hide the mouse cursor. 1293 * 1294 * Currently, the backend is not required to immediately draw the 1295 * mouse cursor on showMouse(true). 1296 * 1297 * @todo We might want to reconsider this fact, 1298 * check Graphics::CursorManager::showMouse for some details about 1299 * this. 1300 * 1301 * @see Graphics::CursorManager::showMouse 1302 */ 1303 virtual bool showMouse(bool visible) = 0; 1304 1305 /** 1306 * Lock or unlock the mouse cursor within the window. 1307 * 1308 */ lockMouse(bool lock)1309 virtual bool lockMouse(bool lock) { return false; } 1310 1311 /** 1312 * Move ("warp") the mouse cursor to the specified position in virtual 1313 * screen coordinates. 1314 * 1315 * @param x New x position of the mouse. 1316 * @param y New y position of the mouse. 1317 */ 1318 virtual void warpMouse(int x, int y) = 0; 1319 1320 /** 1321 * Set the bitmap used for drawing the cursor. 1322 * 1323 * @param buf Pixmap data to be used. 1324 * @param w Width of the mouse cursor. 1325 * @param h Height of the mouse cursor. 1326 * @param hotspotX Horizontal offset from the left side to the hotspot. 1327 * @param hotspotY Vertical offset from the top side to the hotspot. 1328 * @param keycolor Transparency color value. This should not exceed the maximum color value of the specified format. 1329 * In case it does, the behavior is undefined. The backend might just error out or simply ignore the 1330 * value. (The SDL backend will just assert to prevent abuse of this). 1331 * @param dontScale Whether the cursor should never be scaled. An exception is high ppi displays, where the cursor 1332 * might be too small to notice otherwise, these are allowed to scale the cursor anyway. 1333 * @param format Pointer to the pixel format that the cursor graphic uses (0 means CLUT8). 1334 */ 1335 virtual void setMouseCursor(const void *buf, uint w, uint h, int hotspotX, int hotspotY, uint32 keycolor, bool dontScale = false, const Graphics::PixelFormat *format = nullptr) = 0; 1336 1337 /** 1338 * Replace the specified range of cursor palette with new colors. 1339 * 1340 * The palette entries from 'start' till (start+num-1) will be replaced - so 1341 * a full palette update is accomplished via start=0, num=256. 1342 * 1343 * Backends which implement this should have the kFeatureCursorPalette flag set. 1344 * 1345 * @see setPalette 1346 * @see kFeatureCursorPalette 1347 */ setCursorPalette(const byte * colors,uint start,uint num)1348 virtual void setCursorPalette(const byte *colors, uint start, uint num) {} 1349 1350 /** @} */ 1351 1352 1353 1354 /** @defgroup common_system_event_time Events and Time 1355 * @ingroup common_system 1356 * @{ 1357 */ 1358 1359 /** Get the number of milliseconds since the program was started. 1360 * 1361 * @param skipRecord Skip recording of this value by the event recorder. 1362 * This might be needed particularly when we are in 1363 * an on-screen GUI loop where the player can pause 1364 * the recording. 1365 */ 1366 virtual uint32 getMillis(bool skipRecord = false) = 0; 1367 1368 /** Delay/sleep for the specified amount of milliseconds. */ 1369 virtual void delayMillis(uint msecs) = 0; 1370 1371 /** 1372 * Get the current time and date, in the local timezone. 1373 * 1374 * On many systems, this corresponds to the combination of time() 1375 * and localtime(). 1376 */ 1377 virtual void getTimeAndDate(TimeDate &td, bool skipRecord = false) const = 0; 1378 1379 /** 1380 * Return the timer manager singleton. 1381 * 1382 * For more information, see @ref TimerManager. 1383 */ 1384 virtual Common::TimerManager *getTimerManager(); 1385 1386 /** 1387 * Return the event manager singleton. 1388 * 1389 * For more information, see @ref EventManager. 1390 */ getEventManager()1391 inline Common::EventManager *getEventManager() { 1392 return _eventManager; 1393 } 1394 1395 /** 1396 * Register hardware inputs with keymapper. 1397 * 1398 * @return HardwareInputSet with all keys and recommended mappings. 1399 * 1400 * For more information, see @ref keymapper. 1401 */ getHardwareInputSet()1402 virtual Common::HardwareInputSet *getHardwareInputSet() { return nullptr; } 1403 1404 /** 1405 * Return a platform-specific global keymap. 1406 * 1407 * @return Keymap with actions appropriate for the platform. 1408 * 1409 * The caller will use and delete the return object. 1410 * 1411 * For more information, see @ref keymapper. 1412 */ getGlobalKeymaps()1413 virtual Common::KeymapArray getGlobalKeymaps() { return Common::KeymapArray(); } 1414 1415 /** 1416 * Return platform-specific default keybindings. 1417 * 1418 * @return KeymapperDefaultBindings populated with keybindings. 1419 * 1420 * For more information, see @ref keymapper. 1421 */ getKeymapperDefaultBindings()1422 virtual Common::KeymapperDefaultBindings *getKeymapperDefaultBindings() { return nullptr; } 1423 1424 /** @} */ 1425 1426 1427 /** 1428 * @defgroup common_system_mutex Mutex handling 1429 * @ingroup common_system 1430 * @{ 1431 * 1432 * Historically, the OSystem API used to have a method that allowed 1433 * creating threads. Hence, mutex support was needed for thread syncing. 1434 * To ease portability, we decided to remove the threading API. 1435 * Instead, we now use timers (see setTimerCallback() and Common::Timer). 1436 * But since those can be implemented using threads (and in fact, that is 1437 * how our primary backend, the SDL one, does it on many systems), we 1438 * still must do mutex syncing in our timer callbacks. 1439 * In addition, the sound mixer uses a mutex in case the backend runs it 1440 * from a dedicated thread (as the SDL backend does). 1441 * 1442 * Hence, backends that do not use threads to implement the timers can simply 1443 * use dummy implementations for these methods. 1444 */ 1445 1446 typedef struct OpaqueMutex *MutexRef; 1447 1448 /** 1449 * Create a new mutex. 1450 * 1451 * @return The newly created mutex, or 0 if an error occurred. 1452 */ 1453 virtual MutexRef createMutex() = 0; 1454 1455 /** 1456 * Lock the given mutex. 1457 * 1458 * @note ScummVM code assumes that the mutex implementation supports 1459 * recursive locking. That is, a thread can lock a mutex twice without 1460 * deadlocking. In case of a multilock, the mutex must be unlocked 1461 * as many times as it was locked befored it really becomes unlocked. 1462 * 1463 * @param mutex The mutex to lock. 1464 */ 1465 virtual void lockMutex(MutexRef mutex) = 0; 1466 1467 /** 1468 * Unlock the given mutex. 1469 * 1470 * @param mutex The mutex to unlock. 1471 */ 1472 virtual void unlockMutex(MutexRef mutex) = 0; 1473 1474 /** 1475 * Delete the given mutex. 1476 * 1477 * Make sure the mutex is unlocked before you delete it. 1478 * If you delete a locked mutex, the behavior is undefined. 1479 * In particular, your program may crash. 1480 * 1481 * @param mutex The mutex to delete. 1482 */ 1483 virtual void deleteMutex(MutexRef mutex) = 0; 1484 1485 /** @} */ 1486 1487 1488 1489 /** @defgroup common_system_sound Sound 1490 * @ingroup common_system 1491 * @{ 1492 */ 1493 1494 /** 1495 * Return the audio mixer. 1496 * 1497 * For more information, see @ref Audio::Mixer. 1498 */ 1499 virtual Audio::Mixer *getMixer() = 0; 1500 1501 /** @} */ 1502 1503 1504 1505 /** @defgroup common_system_audio Audio CD 1506 * @ingroup common_system 1507 * @{ 1508 */ 1509 1510 /** 1511 * Return the audio CD manager. 1512 * 1513 * For more information, see @ref AudioCDManager. 1514 */ getAudioCDManager()1515 inline AudioCDManager *getAudioCDManager() { 1516 return _audiocdManager; 1517 } 1518 1519 /** @} */ 1520 1521 1522 1523 /** @defgroup common_system_misc Miscellaneous 1524 * @ingroup common_system 1525 * @{ 1526 */ 1527 1528 /** Quit (exit) the application. */ 1529 virtual void quit() = 0; 1530 1531 /** 1532 * Signal that a fatal error inside the client code has occurred. 1533 * 1534 * This should quit the application. 1535 */ 1536 virtual void fatalError(); 1537 1538 /** 1539 * Set a window caption or any other comparable status display to the 1540 * given value. 1541 * 1542 * @param caption The window caption to use. 1543 */ setWindowCaption(const Common::U32String & caption)1544 virtual void setWindowCaption(const Common::U32String &caption) {} 1545 1546 /** 1547 * Display a message in an 'on-screen display'. 1548 * 1549 * Displays a message in such a way that it is visible on or near the screen, 1550 * for example in a transparent rectangle over the regular screen content, 1551 * or in a message box beneath it. 1552 * 1553 * The message is expected to be provided in the current TranslationManager 1554 * charset. 1555 * 1556 * @note There is a default implementation in BaseBackend that uses a 1557 * TimedMessageDialog to display the message. Hence, implementing 1558 * this is optional. 1559 * 1560 * @param msg The message to display on the screen. 1561 */ 1562 virtual void displayMessageOnOSD(const Common::U32String &msg) = 0; 1563 1564 /** 1565 * Display an icon that indicates background activity. 1566 * 1567 * The icon is displayed in an 'on-screen display'. It is visible above 1568 * the regular screen content or near it. 1569 * 1570 * The caller keeps ownership of the icon. It is acceptable to free 1571 * the surface just after the call. 1572 * 1573 * There is no preferred pixel format for the icon. The backend should 1574 * convert its copy of the icon to an appropriate format. 1575 * 1576 * The caller must call this method again with a null pointer 1577 * as a parameter to indicate the icon should no longer be displayed. 1578 * 1579 * @param icon The icon to display on the screen. 1580 */ 1581 virtual void displayActivityIconOnOSD(const Graphics::Surface *icon) = 0; 1582 /** @} */ 1583 1584 /** 1585 * @addtogroup common_system_module 1586 * @{ 1587 */ 1588 1589 /** 1590 * Return the SaveFileManager, which is used to store and load savestates 1591 * and other modifiable persistent game data. 1592 * 1593 * For more information, see @ref SaveFileManager. 1594 */ 1595 virtual Common::SaveFileManager *getSavefileManager(); 1596 1597 #if defined(USE_TASKBAR) 1598 /** 1599 * Return the TaskbarManager, which is used to handle progress bars, 1600 * icon overlay, tasks, and recent items list on the taskbar. 1601 * 1602 * @return The TaskbarManager for the current architecture. 1603 */ getTaskbarManager()1604 virtual Common::TaskbarManager *getTaskbarManager() { 1605 return _taskbarManager; 1606 } 1607 #endif 1608 1609 #if defined(USE_UPDATES) 1610 /** 1611 * Return the UpdateManager, which is used to handle auto-updating 1612 * and updating of ScummVM in general. 1613 * 1614 * @return The UpdateManager for the current architecture. 1615 */ getUpdateManager()1616 virtual Common::UpdateManager *getUpdateManager() { 1617 return _updateManager; 1618 } 1619 #endif 1620 1621 /** 1622 * Return the TextToSpeechManager, used to handle text-to-speech features. 1623 * 1624 * @return The TextToSpeechManager for the current architecture. 1625 */ getTextToSpeechManager()1626 virtual Common::TextToSpeechManager *getTextToSpeechManager() { 1627 return _textToSpeechManager; 1628 } 1629 1630 #if defined(USE_SYSDIALOGS) 1631 /** 1632 * Return the DialogManager, which is used to handle system dialogs. 1633 * 1634 * @return The DialogManager for the current architecture. 1635 */ getDialogManager()1636 virtual Common::DialogManager *getDialogManager() { 1637 return _dialogManager; 1638 } 1639 #endif 1640 1641 /** 1642 * Return the FilesystemFactory object, depending on the current architecture. 1643 * 1644 * @return The FSNode factory for the current architecture. 1645 */ 1646 virtual FilesystemFactory *getFilesystemFactory(); 1647 /** @} */ 1648 1649 /** 1650 * @addtogroup common_system_misc 1651 * @{ 1652 */ 1653 1654 /** Add system-specific Common::Archive objects to the given SearchSet. 1655 * For example, on Unix, the directory corresponding to DATA_PATH (if set), or, on 1656 * Mac OS X, the 'Resource' dir in the app bundle. 1657 * 1658 * @todo Come up with a better name. 1659 * 1660 * @param s SearchSet to which the system-specific dirs, if any, are added. 1661 * @param priority Priority with which those dirs are added. 1662 */ 1663 virtual void addSysArchivesToSearchSet(Common::SearchSet &s, int priority = 0) {} 1664 1665 /** 1666 * Open the default config file for reading by returning a suitable 1667 * ReadStream instance. 1668 * 1669 * It is the caller's responsiblity to delete the stream after use. 1670 */ 1671 virtual Common::SeekableReadStream *createConfigReadStream(); 1672 1673 /** 1674 * Open the default config file for writing by returning a suitable 1675 * WriteStream instance. 1676 * 1677 * It is the callers responsiblity to delete the stream after use. 1678 * 1679 * May return 0 to indicate that writing to the config file is not possible. 1680 */ 1681 virtual Common::WriteStream *createConfigWriteStream(); 1682 1683 /** 1684 * Get the default file name (or even path) where the user configuration 1685 * of ScummVM will be saved. 1686 * 1687 * Note that not all ports can use this. 1688 */ 1689 virtual Common::String getDefaultConfigFileName(); 1690 1691 /** 1692 * Register the default values for the settings the backend uses into the 1693 * configuration manager. 1694 * 1695 * @param target name of a config manager target 1696 */ registerDefaultSettings(const Common::String & target)1697 virtual void registerDefaultSettings(const Common::String &target) const {} 1698 1699 /** 1700 * Return a GUI widget container for configuring the specified target options. 1701 * 1702 * The returned widget is shown in the Backend tab in the options dialog. 1703 * Backends can build custom options dialogs. 1704 * 1705 * Backends that don't want to have a Backend tab in the options dialog 1706 * can return nullptr. 1707 * 1708 * @param boss the widget / dialog the returned widget is a child of 1709 * @param name the name the returned widget must use 1710 * @param target name of a config manager target 1711 */ buildBackendOptionsWidget(GUI::GuiObject * boss,const Common::String & name,const Common::String & target)1712 virtual GUI::OptionsContainerWidget *buildBackendOptionsWidget(GUI::GuiObject *boss, const Common::String &name, const Common::String &target) const { return nullptr; } 1713 1714 /** 1715 * Notify the backend that the settings editable from the game tab in the 1716 * options dialog may have changed and that they need to be applied if 1717 * necessary. 1718 */ applyBackendSettings()1719 virtual void applyBackendSettings() {} 1720 1721 /** 1722 * Log the given message. 1723 * 1724 * It is up to the backend where to log the different messages. 1725 * The backend should aim at using a non-buffered output for it, 1726 * so that no log data is lost in case of a crash. 1727 * 1728 * The default implementation outputs them on stdout/stderr. 1729 * 1730 * @param type Type of the message. 1731 * @param message The message itself. 1732 */ 1733 virtual void logMessage(LogMessageType::Type type, const char *message) = 0; 1734 1735 /** 1736 * Display a dialog box containing the given message. 1737 * 1738 * @param type Type of the message. 1739 * @param message The message itself. 1740 */ messageBox(LogMessageType::Type type,const char * message)1741 virtual void messageBox(LogMessageType::Type type, const char *message) {} 1742 1743 /** 1744 * Open the log file in a way that allows the user to review it, 1745 * and possibly email it (or parts of it) to the ScummVM team, 1746 * for example as part of a bug report. 1747 * 1748 * On a desktop operating system, this would typically launch 1749 * some kind of an (external) text editor / viewer. 1750 * On a phone, it can also cause a context switch to another 1751 * application. Finally, on some ports, it might not be supported 1752 * at all, and do nothing. 1753 * 1754 * The kFeatureDisplayLogFile feature flag can be used to 1755 * test whether this call has been implemented by the active 1756 * backend. 1757 * 1758 * @return True on success, false if an error occurred. 1759 * 1760 * @note An error might mean that the log file did not exist, 1761 * or that the editor could not launch. However, a return value of true does 1762 * not guarantee that the user will actually see the log file. 1763 * 1764 * @note It is up to the backend to ensure that the system is in a state 1765 * that allows the user to actually see the displayed log files. This 1766 * might for example require leaving fullscreen mode. 1767 */ displayLogFile()1768 virtual bool displayLogFile() { return false; } 1769 1770 /** 1771 * Check whether there is text available in the clipboard. 1772 * 1773 * The kFeatureClipboardSupport feature flag can be used to 1774 * test whether this call has been implemented by the active 1775 * backend. 1776 * 1777 * @return True if there is text in the clipboard, false otherwise. 1778 */ hasTextInClipboard()1779 virtual bool hasTextInClipboard() { return !_clipboard.empty(); } 1780 1781 /** 1782 * Return clipboard contents as a string. 1783 * 1784 * The kFeatureClipboardSupport feature flag can be used to 1785 * test whether this call has been implemented by the active 1786 * backend. 1787 * 1788 * @return clipboard contents ("" if hasTextInClipboard() == false). 1789 */ getTextFromClipboard()1790 virtual Common::U32String getTextFromClipboard() { return _clipboard; } 1791 1792 /** 1793 * Set the content of the clipboard to the given string. 1794 * 1795 * The kFeatureClipboardSupport feature flag can be used to 1796 * test whether this call has been implemented by the active 1797 * backend. 1798 * 1799 * @return True if the text has been properly set in the clipboard, false otherwise. 1800 */ setTextInClipboard(const Common::U32String & text)1801 virtual bool setTextInClipboard(const Common::U32String &text) { _clipboard = text; return true; } 1802 1803 /** 1804 * Open the given URL in the default browser (if available on the target 1805 * system). 1806 * 1807 * @return True on success, false otherwise. 1808 * 1809 * @note It is up to the backend to ensure that the system is in a state 1810 * that allows the user to actually see the web page. This might for 1811 * example require leaving fullscreen mode. 1812 * 1813 * @param url The URL to open. 1814 */ openUrl(const Common::String & url)1815 virtual bool openUrl(const Common::String &url) {return false; } 1816 1817 /** 1818 * Return the language of the system. 1819 * 1820 * This returns the currently set language of the system on which 1821 * ScummVM is run. 1822 * 1823 * The format is an ISO 639 language code, optionally followed by an ISO 3166-1 country code 1824 * in the form language_country. 1825 * 1826 * For information about POSIX locales, see the following link: 1827 * https://en.wikipedia.org/wiki/ISO_639 1828 * https://en.wikipedia.org/wiki/ISO_3166-1 1829 * 1830 * The default implementation returns "en_US". 1831 * 1832 * @return Locale of the system. 1833 */ 1834 virtual Common::String getSystemLanguage() const; 1835 1836 /** 1837 * Return whether the connection is limited (if available on the target system). 1838 * 1839 * @return True if the connection is limited. 1840 */ 1841 virtual bool isConnectionLimited(); 1842 1843 //@} 1844 }; 1845 1846 1847 /** The global OSystem instance. Initialized in main(). */ 1848 extern OSystem *g_system; 1849 1850 /** @} */ 1851 1852 #endif 1853