include/core/dispatch.hpp

   1 #ifndef _dispatch__hpp__included__
   2 #define _dispatch__hpp__included__
   3
   4 #include "render.hpp"
   5 #include "keymapper.hpp"
   6
   7 #include <cstdint>
   8 #include <string>
   9 #include <stdexcept>
  10 #include <set>
  11 #include <map>
  12
  13 /**
  14  * Video data region is NTSC.
  15  */
  16 #define VIDEO_REGION_NTSC 0
  17 /**
  18  * Video data region is PAL.
  19  */
  20 #define VIDEO_REGION_PAL 1
  21
  22 /**
  23  * Information about run.
  24  */
  25 struct gameinfo_struct
  26 {
  27 public:
  28 /**
  29  * Construct game info.
  30  */
  31         gameinfo_struct() throw(std::bad_alloc);
  32 /**
  33  * Game name.
  34  */
  35         std::string gamename;
  36 /**
  37  * Run length in seconds.
  38  */
  39         double length;
  40 /**
  41  * Rerecord count (base 10 ASCII)
  42  */
  43         std::string rerecords;
  44 /**
  45  * Authors. The first components are real names, the second components are nicknames. Either (but not both) may be
  46  * blank.
  47  */
  48         std::vector<std::pair<std::string, std::string>> authors;
  49 /**
  50  * Format human-redable representation of the length.
  51  *
  52  * Parameter digits: Number of sub-second digits to use.
  53  * Returns: The time formated.
  54  * Throws std::bad_alloc: Not enough memory.
  55  */
  56         std::string get_readable_time(unsigned digits) const throw(std::bad_alloc);
  57 /**
  58  * Get number of authors.
  59  *
  60  * Returns: Number of authors.
  61  */
  62         size_t get_author_count() const throw();
  63 /**
  64  * Get short name of author (nickname if present, otherwise full name).
  65  *
  66  * Parameter idx: Index of author (0-based).
  67  * Returns: The short name.
  68  * Throws std::bad_alloc: Not enough memory.
  69  */
  70         std::string get_author_short(size_t idx) const throw(std::bad_alloc);
  71 /**
  72  * Get rerecord count as a number. If rerecord count is too high, returns the maximum representatible count.
  73  *
  74  * Returns: The rerecord count.
  75  */
  76         uint64_t get_rerecords() const throw();
  77 };
  78
  79
  80 /**
  81  * Information dispatch.
  82  *
  83  * This class handles dispatching information between the components of the emulator.
  84  *
  85  * Each kind of information has virtual method on_foo() which can be overridden to handle events of that type, and
  86  * static method do_foo(), which calls on_foo on all known objects.
  87  *
  88  * The information is delivered to each instance of this class.
  89  */
  90 class information_dispatch
  91 {
  92 public:
  93 /**
  94  * Create new object to receive information dispatch events.
  95  *
  96  * Parameter name: The name for the object.
  97  * Throws std::bad_alloc: Not enough memory.
  98  */
  99         information_dispatch(const std::string& name) throw(std::bad_alloc);
 100 /**
 101  * Destroy object.
 102  */
 103         ~information_dispatch() throw();
 104 /**
 105  * Window close event received (this is not emulator close!)
 106  *
 107  * The default handler does nothing.
 108  */
 109         virtual void on_close();
 110 /**
 111  * Call all on_close() handlers.
 112  */
 113         static void do_close() throw();
 114 /**
 115  * Sound mute/unmute status might have been changed.
 116  *
 117  * The default handler does nothing.
 118  *
 119  * Parameter unmuted: If true, the sound is now enabled. If false, the sound is now disabled.
 120  */
 121         virtual void on_sound_unmute(bool unmuted);
 122 /**
 123  * Call all on_sound_unmute() handlers.
 124  */
 125         static void do_sound_unmute(bool unmuted) throw();
 126 /**
 127  * Sound device might have been changed.
 128  *
 129  * The default handler does nothing.
 130  *
 131  * Parameter dev: The device name sound is now playing (if enabled) from.
 132  */
 133         virtual void on_sound_change(const std::string& dev);
 134 /**
 135  * Call all on_sound_change() handlers.
 136  */
 137         static void do_sound_change(const std::string& dev) throw();
 138 /**
 139  * Emulator mode might have been changed.
 140  *
 141  * The default handler does nothing.
 142  *
 143  * Parameter readonly: True if readonly mode is now active, false if now in readwrite mode.
 144  */
 145         virtual void on_mode_change(bool readonly);
 146 /**
 147  * Call all on_mode_change() handlers.
 148  */
 149         static void do_mode_change(bool readonly) throw();
 150 /**
 151  * Autohold on button might have been changed.
 152  *
 153  * The default handler does nothing.
 154  *
 155  * Parameter pid: The physical ID of controller (0-7).
 156  * Parameter ctrlnum: Physical control number (0-15).
 157  * Parameter newstate: True if autohold is now active, false if autohold is now inactive.
 158  */
 159         virtual void on_autohold_update(unsigned pid, unsigned ctrlnum, bool newstate);
 160 /**
 161  * Call all on_autohold_update() handlers.
 162  */
 163         static void do_autohold_update(unsigned pid, unsigned ctrlnum, bool newstate) throw();
 164 /**
 165  * Controller configuration may have been changed.
 166  *
 167  * The default handler does nothing.
 168  */
 169         virtual void on_autohold_reconfigure();
 170 /**
 171  * Call all on_autohold_reconfigure() handlers.
 172  */
 173         static void do_autohold_reconfigure() throw();
 174 /**
 175  * A setting may have changed.
 176  *
 177  * The default handler does nothing.
 178  *
 179  * Parameter setting: The setting that has possibly changed.
 180  * Parameter value: The new value for the setting.
 181  */
 182         virtual void on_setting_change(const std::string& setting, const std::string& value);
 183 /**
 184  * Call all on_setting_change() handlers.
 185  */
 186         static void do_setting_change(const std::string& setting, const std::string& value) throw();
 187 /**
 188  * A setting has been cleared (but it might have been cleared already).
 189  *
 190  * The default handler does nothing.
 191  *
 192  * Parameter setting: The setting that is now clear.
 193  */
 194         virtual void on_setting_clear(const std::string& setting);
 195 /**
 196  * Call all on_setting_clear() handlers
 197  */
 198         static void do_setting_clear(const std::string& setting) throw();
 199 /**
 200  * A raw frame has been received.
 201  *
 202  * The default handler does nothing.
 203  *
 204  * Parameter raw: The raw frame data. 512*512 element array.
 205  * Parameter hires: True if in hires mode (512 wide), false if not (256-wide).
 206  * Parameter interlaced: True if in interlaced mode (448/478 high), false if not (224/239 high).
 207  * Parameter overscan: True if overscan is active, false if not.
 208  * Parameter region: One of VIDEO_REGION_* contstants, giving the region this frame is from.
 209  */
 210         virtual void on_raw_frame(const uint32_t* raw, bool hires, bool interlaced, bool overscan, unsigned region);
 211 /**
 212  * Call all on_raw_frame() handlers.
 213  *
 214  * Calls on_new_dumper() on dumpers that had that not yet called.
 215  */
 216         static void do_raw_frame(const uint32_t* raw, bool hires, bool interlaced, bool overscan, unsigned region)
 217                 throw();
 218 /**
 219  * A frame has been received.
 220  *
 221  * The default handler does nothing.
 222  *
 223  * Parameter _frame: The frame object.
 224  * Parameter fps_n: Numerator of current video fps.
 225  * Parameter fps_d: Denominator of current video fps.
 226  */
 227         virtual void on_frame(struct lcscreen& _frame, uint32_t fps_n, uint32_t fps_d);
 228 /**
 229  * Call all on_frame() handlers.
 230  *
 231  * Calls on_new_dumper() on dumpers that had that not yet called.
 232  */
 233         static void do_frame(struct lcscreen& _frame, uint32_t fps_n, uint32_t fps_d) throw();
 234 /**
 235  * A sample has been received.
 236  *
 237  * The default handler does nothing.
 238  *
 239  * Parameter l: The left channel sample (16 bit signed).
 240  * Parameter r: The right channel sample (16 bit signed).
 241  */
 242         virtual void on_sample(short l, short r);
 243 /**
 244  * Call all on_sample() handlers.
 245  *
 246  * Calls on_new_dumper() on dumpers that had that not yet called.
 247  */
 248         static void do_sample(short l, short r) throw();
 249 /**
 250  * Dump is ending.
 251  *
 252  * Calls on_new_dumper() on dumpers that had that not yet called.
 253  *
 254  * The default handler does nothing.
 255  */
 256         virtual void on_dump_end();
 257 /**
 258  * Call all on_dump_end() handlers.
 259  */
 260         static void do_dump_end() throw();
 261 /**
 262  * Sound sampling rate is changing
 263  *
 264  * The default handler prints warning if dumper flag is set.
 265  *
 266  * Parameter rate_n: Numerator of the new sampling rate in Hz.
 267  * Parameter rate_d: Denominator of the new sampling rate in Hz.
 268  */
 269         virtual void on_sound_rate(uint32_t rate_n, uint32_t rate_d);
 270 /**
 271  * Call all on_sound_rate() methods and save the parameters.
 272  *
 273  * Calls on_new_dumper() on dumpers that had that not yet called.
 274  */
 275         static void do_sound_rate(uint32_t rate_n, uint32_t rate_d) throw();
 276 /**
 277  * Get the sound rate most recently set by on_sound_rate().
 278  *
 279  * Returns: The first component is the numerator, the second is the denominator.
 280  */
 281         static std::pair<uint32_t, uint32_t> get_sound_rate() throw();
 282 /**
 283  * Game information is changing.
 284  *
 285  * The default handler does nothing.
 286  *
 287  * Parameter gi: The new game info.
 288  */
 289         virtual void on_gameinfo(const struct gameinfo_struct& gi);
 290 /**
 291  * Call all on_gameinfo() handlers and save the gameinfo.
 292  */
 293         static void do_gameinfo(const struct gameinfo_struct& gi) throw();
 294 /**
 295  * Get the gameinfo most recently set by do_gameinfo().
 296  *
 297  * Returns: The gameinfo.
 298  */
 299         static const struct gameinfo_struct& get_gameinfo() throw();
 300 /**
 301  * Return the dumper flag for this dispatch target.
 302  *
 303  * The default implementation returns false.
 304  *
 305  * If dumper flag is set:
 306  *      - on_sound_rate() default handler prints a warning.
 307  *      - All dumping related do_* functions triggers calls to to on_new_dumper() on all handlers the next time they
 308  *        are called.
 309  *      - Destroying the handler triggers calls to on_destroy_dumper() on all handlers (if on_new_dumper() has been
 310  *        called).
 311  */
 312         virtual bool get_dumper_flag() throw();
 313 /**
 314  * Notify that a new dumper is joining.
 315  *
 316  * Parameter dumper: The name of the dumper object.
 317  */
 318         virtual void on_new_dumper(const std::string& dumper);
 319 /**
 320  * Notify that a dumper is leaving.
 321  *
 322  * Parameter dumper: The name of the dumper object.
 323  */
 324         virtual void on_destroy_dumper(const std::string& dumper);
 325 /**
 326  * Get number of active dumpers.
 327  *
 328  * Calls on_new_dumper() on dumpers that had that not yet called.
 329  *
 330  * Returns: The dumper count.
 331  */
 332         static unsigned get_dumper_count() throw();
 333 /**
 334  * Get set of active dumpers.
 335  *
 336  * Calls on_new_dumper() on dumpers that had that not yet called.
 337  *
 338  * Returns: The set of dumper names.
 339  * Throws std::bad_alloc: Not enough memory.
 340  */
 341         static std::set<std::string> get_dumpers() throw(std::bad_alloc);
 342 /**
 343  * (Pseudo-)key has been pressed or released.
 344  *
 345  * Parameter modifiers: The modifier set currently active.
 346  * Parameter keygroup: The key group the (pseudo-)key is from.
 347  * Parameter subkey: Subkey index within the key group.
 348  * Parameter polarity: True if key is being pressed, false if being released.
 349  * Parameter name: Name of the key being pressed/released.
 350  */
 351         virtual void on_key_event(const modifier_set& modifiers, keygroup& keygroup, unsigned subkey,
 352                 bool polarity, const std::string& name);
 353 /**
 354  * Call on_key_event() for all event handlers (or just one if keys are being grabbed).
 355  */
 356         static void do_key_event(const modifier_set& modifiers, keygroup& keygroup, unsigned subkey,
 357                 bool polarity, const std::string& name) throw();
 358 /**
 359  * Grab all key events.
 360  *
 361  * While key events are grabbed, do_key_event() only calls on_key_event() for the grabbing object.
 362  */
 363         void grab_keys() throw();
 364 /**
 365  * Ungrab all key events.
 366  *
 367  * While key events are grabbed, do_key_event() only calls on_key_event() for the grabbing object.
 368  */
 369         void ungrab_keys() throw();
 370 /**
 371  * Get name of target.
 372  */
 373         const std::string& get_name() throw();
 374 /**
 375  * Render buffer needs to be (possibly) resized, so that graphics plugin can update the mappings.
 376  *
 377  * Default implementation does nothing.
 378  *
 379  * parameter scr: The render buffer object.
 380  */
 381         virtual void on_set_screen(screen<false>& scr);
 382 /**
 383  * Call on_set_screen on all objects.
 384  */
 385         static void do_set_screen(screen<false>& scr) throw();
 386 /**
 387  * Notify that new frame is available.
 388  *
 389  * Default implementation does nothing.
 390  */
 391         virtual void on_screen_update();
 392 /**
 393  * Call on_screen_update() in all objects.
 394  */
 395         static void do_screen_update() throw();
 396 /**
 397  * Notify that status buffer has been updated.
 398  *
 399  * Default implementation does nothing.
 400  */
 401         virtual void on_status_update();
 402 /**
 403  * Call on_status_update() in all objects.
 404  */
 405         static void do_status_update() throw();
 406 /**
 407  * Notify that some dumper has attached, deattached, popped into existence or disappeared.
 408  *
 409  * Default implementation does nothing.
 410  */
 411         virtual void on_dumper_update();
 412 /**
 413  * Call on_dumper_update on on all objects.
 414  */
 415         static void do_dumper_update() throw();
 416 protected:
 417 /**
 418  * Call to indicate this target is interested in sound sample data.
 419  */
 420         void enable_send_sound() throw(std::bad_alloc);
 421 private:
 422         static void update_dumpers(bool nocalls = false) throw();
 423         bool known_if_dumper;
 424         bool marked_as_dumper;
 425         std::string target_name;
 426         bool notified_as_dumper;
 427         bool grabbing_keys;
 428 };
 429
 430 #endif