path: root/TODO

Here is a list of things we plan to do in the future. Note that we
don't promise to do any of these, nor when we will do them. It's just a
list of what we hope to be able to do one day.

If you want to dig in, this is the stuff where you might make the most
useful contribution. Note that this list is never complete, and may be
partially outdated, so just because you don't see something here doesn't
mean it is not important.

Before you start work on something, you should first talk to the team!
Ideally ask on scummvm-devel, our mailing list. This will help us to
prevent double work, i.e. several people working on the same stuff at
once without knowing about each other. Furthermore, sometimes entries
on our list are actually obsolete (because the feature has been
implemented, or because for some reason we no longer think it to be
desirable). Special caution should be taken for TODO entries that say
"we may want to" or similar things; that usually means that we aren't
sure whether we really want to implement that feature.

So, to repeat it: Always talk to the team before implementing a change
on this list, or else risk having your patch rejected :-/.

Finally, always make sure to check out our bug tracker and our feature
request tracker for things that need work.


#######################################################################
# Docs, Web site
#######################################################################

General
========
* Add port specific user documentation (dreamcast/palm especially). That
  would include things like:
  - How to use ScummVM on system XYZ
  - Which Palm / WinCE devices will run ScummVM, which definitely will not
    run it (or with which limitations)?
* Update/enhance man page
* Write a high level overview of how ScummVM and its engines work?

README / Manual
===============
* Ender is working on a new multi-format manual/readme.
  Since so far we haven't seen anything of that, Fingolfin has started a
  DocBook based manual (and FAQ, and Developer's Guide). You can find it in
  the CVS module "docs".
  Finally, there is a LaTeX based version of the README in the "doc" subdir
  of the "scummvm" CVS module, but it tends to slip out of sync with the
  plain text README, and it's not really a manual, it's just the README
  in a different file format.
* Everybody is welcome to start helping out with the public manual project
  in the "docs" CVS module. You can either reuse content from the README,
  or replace it with new, better written stuff. Contact Fingolfin or our
  mailing list, scummvm-devel, if you are interested in helping out.
* It would be greate to have a "Developer's Guide to ScummVM" which explains
  the ScummVM framework, and also the engines, i.e.
  - stuff in common/, like the config manager etc.
  - the backend API, and how to create new backends
  - the sound system
  - how to create a new engine
  - a chapter for each engine, with as many/little details as the resp.
    engine teams deem appropriate...
  - ...

LaTeX docs
==========
* These are constantly out of sync with the README :-/
* The files are currently named in a very dumb fashion -- using their section
  IDs, which of course constantly change. Better would be to give them names
  based on their content instead. E.g. create a subdir for each chapter,
  move the (sub)section files into that directory and rename them to match 
  their content, instead of their section number (which changes all the time).
  -> Fingolfin would do it, but wants to wait until the SVN switch.


Code
====
* Add more Doxygen comments. However, quality is preferable over quantity
* Document the OSystem overlay API, it badly needs it...

Web site
========
* Add the "Manual" / README to the site

#######################################################################
# Common code, infrastructure
#######################################################################

General
=======
* Revise the way "quit" is handled. Maybe add a global variable "g_quit" which
  we set when the application should be quit (e.g. when an EVENT_QUIT is
  received). This is useful if multiple levels of event loops have to be ended
* Fix the Map<> template, make it more robust; maybe use a red-black tree?
* Make some generic "EventLoop" API/class which all backends and the GUI
  use. Initially this would just call the backend poll_event() etc. methods.
  But eventually the EventLoop object(s) could be made by the backend.
  This may allow for more efficient CPU usage etc.
  The current event handling model essentially is polling: the engines run
  some kind of main loop, which, besides many other things, also polls and
  dispatches events. The idea is to turn this around: the event loop
  frequently gives the engine time to do these "other things".
* Make the autosave interval configurable (via GUI, command line, config file).
* Maybe add ways to modify the game configs via the command line. E.g. allow
    ./scummvm --add new_target --path=/foo monkey2
    ./scummvm --remove new_target
* Maybe allow launching games even if no target is specified? I.e. the user
  only has to specify a path (or run ScummVM from the right directory), and
  ScummVM auto-detects the game in that location
    ./scummvm --auto-detect
  Of course, if we do it, it has to be done so that the launcher is still
  reachable :-)
* Some source files should be moved. But that's a pain with CVS, so let's
  wait until we switch to something better, like Subversion. In particular:
  - consider moving the MIDI stuff from sound/ to sound/midi/ 
  - move fmopl code to softsynth dir
  - maybe common/system.h / system.cpp should go to backends/, too ?
* The following things should be put into namespaces:
  - AudioStream and subclasses into Audio
  - MIDI related classes either to Audio, or a new "MIDI" namespace
  - backend specific stuff into ??? (maybe new namespace "Backends" ?)
    not sure about this one.


Build System
============
* Add test(s) for backend usability in the configure script.
* Enhance the Makefile-based build system to support VPATH and stuff, so that
  one can compile scummvm in a directory tree separate from the source tree.
  That would make it possible to build ScummVM with different build options,
  e.g. have one debug build and one optimized build.
  Fingolfin implemented most of this; the only thing missing is that configure
  should detect when it is run in a directory outside the source tree, and in
  that case generate a custom Makefile, with content like this:
	srcdir = /path/to/source/dir
	vpath %.cpp $(srcdir)
	vpath %.h $(srcdir)
	include $(srcdir)/Makefile
* Allow automatic re-runs of configure (this would have to 'save' the values of
  env vars like CXXFLAGS and also command line params)
* Add an install target to the Makefile - Copy binary, install manpage, add
  menu items, install README. See also patch #891909 (Gnome/KDE .desktop file)

Audio
=====
* Get the high quality resample code to work
   [Fingolfin has started work on this]
* Consider changing the mixer volume to use range 0-255, for sake of
  consistency (but at a slight loss of efficiency). Note that this requires
  changes in at least rate.cpp and mixer.cpp.
* MIDI: Add API to OSystem which allows client code to query for "native"
  MIDI drivers (like Windows, ALSA, Zodiac, CoreAudio). Then change the
  MIDI interfacing code (GUI, command line, config file, etc.) and also
  MidiDriver::createMidi() to use both that list and the list of
  'emulated' MIDI devices (Adlib, MT-32, PC Speaker, etc.) in an appropriate
  way.
* The Audio CD Manager, and especially the DigitalTrackInfo class could
  stand an overhaul. The system currently is not as easy to extend as one would
  wish. In particular, it would be nice if arbitrary AudioStream classes could
  be used here (this then would reduce code duplication and make it instantly
  possible to use WAV/VOC encoded audio tracks, should we desire to support
  those).
* Modify our audio stream classes (for MP3/Vorbis/FLAC/... playback) to use
  SeekableReadStream instead of Files -> allow from-memory-playback.
  And could take advantage of a new hypothetical "Sub(Seekable)Stream" class.
  (See below for more info on that).

Config Manager
==============
* Add a 'notification' system. E.g. the SoundMixer could request to be notified
  whenever the value of the "volume" config option changes. In other words,
  instead of a "pull" approach (where each subsystem has to check whether any
  config option relevant to it has been changed) we use a "push" approach.
  Of course the current approach is "push", too: whenever e.g. the volume
  setting is changed, the code doing so has to updated the SoundMixer etc.
  That's cumbersome, and error prone. Would be much nicer if updating the
  volume config value automatically notifies the SoundMixer, iMuse etc.
* Modify the ConfigManager to make use of the ConfigFile class.
* Maybe even follow the pentagram (http://pentragram.sf.net) approach and have
  three classes:
  - SettingsManager (like our current ConfigManager)
  - ConfigFileManager (manages a set of config files, possibly merging the data
    from multiple config files)
  - ConfigFile (a simple .ini file accessor).
  This makes it easy to add additional config sources (e.g. XMLConfigFile);
  makes it possible to treat the command line data like another config file
  (CommandLineConfig); and simply follows the good old MVC approach, which
  is always a good idea.

Files
=====
* Add a FilesystemManager or FileManager or so which should unify and/or
  replace the current File/FilesystemNode classes (and maybe SaveFileManager).
  The goal is to make these things as portable as possible while keeping it
  easy to use for the coder. Some new functionality we need:
  - check for existence of file/directory
  - check whether given directory is readable/writeable
  - convert FSNode into a string representation (for prefs file)
  - convert said string representation back to FSNode
  Of course that can be added w/o a FileManager class, too - but it might be
  nice to have all of these integrated.
* Get rid of the incRef/decRef API of class File. Instead, add a clone() method
  which generates a new (independant) File object for the same file (only would
  work for files in read mode, obviously). Convert the audio code to use this
  instead of the ref counting.
  Reason: Using a shared file object can lead to race conditions if multiple
  threads try to use it at the same time; on some systems (Symbian) it is 
  apparently not even possible to do it; iahd t can also cause problems even in
  non-threaded code, when we seek in one block of code, and then try to access it
  from another block, w/o reseeking first.

GUI
===
* Remove hard coded 320x200 assumptions, use game screen size. In particular,
  all the dialogs should be rewritten to allow for that. At this point, most
  (all?) dialogs are able to scale themselves, but the way they do so is
  sometimes a bit hackish, the layout could be improved, and there are glitches
  with the small version of the GUI.
* EditableWidget: Make it possible to specify a min/max length for the text
* EditableWidget: Let setEditString filter the string it gets
* EditableWidget: Right now, custom filtering requires the user to subclass;
  it would be nice if there was simply a "validator hook" or so.
  Maybe take some inspiration from Java's Swing in this matter.
* Improve EditTextWidget::drawCaret and ListWidget::drawCaret support for
  alternate fonts (the current code overdraws chars partly, and relies on the
  fact that our default built-in font has a separation pixel column on the
  *left* side; most other bitmap fonts have it on the right, though). To this
  end, we maybe should backup the background before drawing the caret, and
  restore it when erasing the caret.
* PopUpDialog: Must be able to handle longer lists (by adding scrolling?). The
  language popup currently doesn't fit in the small version of the GUI.
* Add a new "options" dialog which is used by all frontends: for this, we'd
  agree on a hotkey used in all engines to invoke that dialog; it would sport
  settings for the volume, graphics, paths, etc.; it would co-exist with the
  engines "native" option dialogs.
  The about dialog would be reachable from here, too, as well as a quit button.
  Justification: This ensures that all settings are really reachable from
  all of the engines, which is not the case currently.
  Problem: It's not fully clear to me how to "best" deal with global vs. local
  settings here...
* Maybe add the ScummVM logo (+typeface?) to the about dialog
* There is currently no way to unset the SoundFont from the GUI, if any was
  set. Maybe add a 'clear' button for it? The same holds for other path
  settings.
* ScrollBarWidget: Add auto-repeat: if user clicks & holds on one of the
  arrows, then after a brief delay, it should start to contiously scroll.
* AboutDialog: Add a "fade" effect for the top/bottom text lines
* AboutDialog: Maybe prerender all of the text into another surface, and then
  simply compose that over the screen surface in the right way.


Graphics
========
* Add some more fonts/font variants? Maybe a tool like ttf2bdf could be used
  to convert on (free!) TTF font to both a small and a big font for the GUI,
  maybe including bold/italic variants
* Allow loading external fonts (BDF format?). Useful for GUI customization.
* Use 'complete' fonts, encoding wise. In particular, we should probably pick
  one encoding (e.g. ISO Latin 1) and standardize on it. Oh yeah, a map from
  the SCUMM  encoding to that encoding would be useful.
  That way, we can at least all systems/languages which use that encoding.
  Of course, kyrillic and asian users, amongst others, wouldn't be helped
  by this, but there is nothing we can do for them anyway, short of
  implementing an UTF8 based font rendering engine. (And no, there is no way
  we are going to do such an absurd thing. Better to implement native GUIs
  than to write our own OS :-).
* Consider implementing a new internal font format which
  - takes up less space in the executable (ascii vs. binary encoding)
  - allows for multi-color/anti-aliased fonts

Launcher
========
* Add more options to global options dialog
* Add more options to game target options dialog 

Plugins
=======
* Add a plugin API that allows querying a plugin for the savegames associated
  with a given game; that is, you pass the name of a target from the config
  to the plugin, and it returns a list of savegames. How that list would look
  like exactly is debatable; but it should be possible to extract a user
  friendly name; a slot ID corresponding to the "-x" command line param;
  and possibly a filename.
  Justification: This API would make it possible to directly load savegames
  from the launcher.
* This savegame API could return additional (optional) information for each
  savegame entry: name; creation date; thumbnail screenshot
* When building with the fake static plugins: instead of hardcoding the list
  of plugins, plugins should automatically be "hooked in". This can be achieved
  by modifying REGISTER_PLUGIN to insert special code into the plugins.
  UPDATE: I tried this, but it doesn't really work due to constraints
  imposed by the way most C++ compilers/linkers out there realize global
  constructors.
* On OSX: Support a plugin build in the bundle target: *.plugin files should
  be put into ScummVM.app/Contents/PlugIns/; this also means that the loader
  needs to search in the plugin dir of the active bundle. So use the 
  CF bundle API, inside a #ifdef MACOSX block.
* When creating an engine instance, there is currently no way for the plugin
  to indicate an error, except for returning a NULL value. It would be nice
  if the engine could specify why creating the engine instance failed (e.g.
  due to lack of memory, because a file couldn't be found, because the game
  was not recognized, etc.).
* Currently, there is only a single list of game IDs return by each engine.
  That list is both used to detect which engine handles a given user target,
  and to display a list of supported game IDs. This leads to "-z" displaying
  e.g. the obsolete "zakTowns" target. So we should separate the two. There
  are multiple ways to do that, of course.
* Split base/plugins.h into the part needed to implement a plugin, and the part
  needed by client code. Maybe also move DetectedGame and GameSettings to a new
  file base/game.h
* Replace DetectedGame by a 'map' containing essentially the same data that the
  config file would contain -- i.e. gameid, description, language, platform;
  but also any further data, like e.g. basename, target_md5, or *anything*
  the engine deems important.
   -> far more flexible, and helps to simplify the launcher code, too.


OSystem
=======
* Right now gBitFormat is part of common/scaler.cpp; we might want to move it
  to common/system.cpp, or replace it with something better.
  No hasty changes here, please, make sure you understand how it is used right
  now before messing with it ;-)
* Document key codes to be used for special keys, like F1-F15 etc.

Streams
=======
* Add a Sub(Seekable)Stream wrapper class: You pass a (Seekable)Stream,
  an offset and a size to it. It will pass all calls on to the wrapped
  stream, but will restrict access to the specified byte range.
  This then can be used in various places, e.g. in many of the AudioStream
  classes, to simplify code.
* Add a "clone" method that makes a copy of the (seekable/readable) stream.
  In the case of files, this would create a new file descriptor.
  Purpose: Replace the Symbian hack in MP3InputStream and other places;
  in particular, often we need two parts of code to access the same file
  but in separate positions...

#######################################################################
# Engines / frontends
#######################################################################

General
=======
* Fix engines so they clean up after themselves, to allow proper re-entry
  to the launcher. See "FIXME: LAUNCHERHACK" in base/main.cpp
* Get rid of GF_DEFAULT_TO_1X_SCALER and the 'defaultTo1XScaler' parameter of
  Engine::initCommonGFX. They form a crude hack to better support 640x480 games
  and are meant to prevent those games from being accidentally scaled to a size
  that won't fit on the screen. However, the proper fix would be to modify the
  backends so that they simply fall back to a smaller scaler when a combination
  is requested that can't be satisfied.

SCUMM
=====
* Make it possible to restart games properly
* Add method of setting initial debug channels from command-line
* Possibly implement a new resource manager, which then also could be shared
  by ScummEX. [Jamieson has some ideas about this].
* Figure out how to extract resources from Apple II versions
* Figure out how to extract resources from Turbografx/PC Engine version of Loom
* Loom EGA: Add support for music and sound effects in Macintosh version
* Add support for handling Kanji in FM-Towns games (foreground is rendered on a
  second plane at 640x480), text uses Shift_JIS encoding
  [implementation now that currently depends on font rom, not needing the rom
   would be preferable]
* Add support for TFMX music format in Amiga version of Monkey Island 1
  Check http://darkstar.tabu.uni-bonn.de/~neo/audio.html for music format
  details
* When SMUSH movies end, their music track sometimes should last a bit longer;
  currently, we stop the audio together with the animation, leading to cut off
  music.
* Clean up class Gdi. This class right now mostly is about decoding various
  graphic formats. However some other functionality has crept into it, too.
  It would be nice if class Gdi would only contain the GFX decoding code, and
  nothing else (assuming that is feasible w/o too much trouble).
  OTOH, the code which is responsible for managing virtual screens, rendering
  virtual screens to the real display etc. could be grouped into a new class
  (e.g. VSManager or so).

Broken Sword 2
==============
* Enforce ScummVM code formatting guidelines. (Mostly done?)
* Encapsulate the code into sensible objects. (Partly done.)
* Enable the CD swapping code. (Partly done.)
* Fix the credits so they look more like the original. (Did we ever get the
  source code for that?)
* Maybe work around script bug which causes the mop to disappear briefly when
  trying to pick it up from the top of the boat at the London docks. (The event
  to hide the mop is sent too early.) See bug #1214168.
* Unify some of the code with Broken Sword 1 (e.g. in router.cpp).

#######################################################################
# Backends
#######################################################################

General
=======
* Several of the backend factory functions take config parameters. It should
  be possible to get rid of those once the config system rewrite (see above)
  has been done. In that case, the backends simply can query the config
  manager for these parameters (or any others they might like :-).
* Change backends to directly access the config manager
* Add API to query backend for a list of available music engines
  Useful for Options dialog
* MS DOS port using Allegro <http://www.talula.demon.co.uk/allegro/> and
  DJGPP <http://www.delorie.com/djgpp/> ?
* Intent <http://withintent.biz/> port (already done by David Given, merge?)
* Digita OS port? (play games on a select few digital cameras...)
  <http://digita.mame.net/reviews.htm>

X11 backend
===========
* Add frills used by SDL backend like graphic filters usage and CD audio

SDL backend
===========
* Right now, the WinCE backend subclasses the regular SDL backend. The
  Symbian backend will do that, too (it is not yet in CVS, though).
  They both overload a lot of methods (mostly the graphics stuff). Since
  graphics.cpp uses the scalers (e.g. hq3x), these derived backends
  carry that baggage around, too, even though they don't need that code.
  Idea: split the SDL backend into two classes, one base class which only
  has the code which is used by all subclasses; and a "desktop" subclass,
  which implements the rest. Then WinCE/Symbian would only subclass the
  "base" SDL class.
* We implemented GFX transactions & commits some time ago -- but they are only
  half the story. We are still missing a rollback system -- that is, check
  whether the requested video mode works, if it doesn't, revert to the current
  settings -- at least "if it makes sense". That is, if the transaction
  only modified the scaler or aspect ratio, we can safely revert. Of course
  if the screen size changed (e.g. from 320x200 -> 640x480) we can't just
  revert to the old screen size -- unless we augment the API accordingly,
  and update all engines to deal with this possibility.

#######################################################################
# Tools
#######################################################################

General
=======
* Try to unify the usage of the compression tools, where possible /
  necessary.
* Make compress_san use the common encoder "API" in compress.c
* Make compress_queen use the common encoder "API" in compress.c
* Add FLAC support to compress_sword1 (and the sword1 engine)
* Consider using library APIs to encode data, instead of invoking the
  lame/oggenc/flac binaries.
  Pro: Tighter integration, no need to create temporary files.
  Con: Requires the resp. libs/headers to be compiled in, and the resulting
       binary would only run if all needed shared libs are present 
       (unless we static link), whereas the current binary will work even
       if lame/oggenc/flac are missing

Descumm
=======
* Turn it into a library, to be used by a command line frontend (like now),
  ScummVM debugger, and ScummEX. Basically, the API could consist of a single
  function, which takes a pointer to a memory buffer, its length, the Scumm
  version and optionally a game id. Also, it would get a pointer to a print
  function (in the case of the CLI tool, print to stdout; for ScummVM, print
  to our GUI console; for ScummEX, append to some window/widget)
* Rewrite code to use 2 passes; first pass builds an intermediate graph, the
  second pass then tries to detect loops, break/continue statements etc.
* Proper implementation of o6_startObjectQuick decompilation (see comment in
  descumm6.c). May requre rewrite of core program logic