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