Updated some code comments and the documentation.

git-svn-id: svn://svn.code.sf.net/p/stella/code/trunk@2280 8b62c5a3-ac7e-4cc8-8f21-d9a121418aba

Changes.txt

@@ -12,7 +12,34 @@
                                Release History
 ===========================================================================
 
-3.4.1 to 4.x: (XXXX xx, 2011)
+3.4.1 to 3.5: (December xx, 2011)
+
+  * Replaced NTSC TV filtering with Blargg NTSC filters.  These filters
+    work in OpenGL mode only, but in contrast to the old filters, they
+    now work with OpenGL 1.x / OpenGL ES.
+
+  * Huge restructuring of the OpenGL code, making it compatible with 
+    OpenGL 2.x+ features (such as vertex buffer objects), while at the
+    same time keeping compatibility with OpenGL 1.5 / OpenGL ES.
+
+  * Added logging facility, whereby the output of the application is
+    available within Stella itself.  This can still be printed to the
+    console, or also saved to a file.  Add the 'loglevel' and
+    'logtoconsole' commandline arguments which control these settings,
+    and removed the 'showinfo' argument as it's now redundant.
+
+  * Updated DPC+ bankswitching scheme to latest code provided by
+    SpiceWare.
+
+  * Added MAMCR handling to the Thumb ARM emulation code.  Note that
+    MAMCR isn't actually emulated, it is just ignored for now.  This
+    fixes a bug whereby accessing MAMCR would crash the ARM emulation.
+
+  * Added 'thumb.trapfatal' commandline argument, which causes the
+    Thumb ARM emulation to either trap on a fatal error (throw an
+    exception to the debugger and exit emulation) or simply log the
+    error and continue.  This should normally always be enabled, but
+    can be disabled by developers for testing reasons.
 
   * The debugger 'print' command now indicates "special" addresses if they
     are read-only (R), write-only (W) or read-write (R/W).
@@ -20,6 +47,12 @@
   * Fixed a bug in scrolling the mouse-wheel in certain debugger UI items
     would cause the program to crash; scrolling now works as expected.
 
+  * Fixed compile issues in the latest versions of Ubuntu and Debian, and
+    fixed UNIX desktop file so that Stella will launch with a ROM when
+    selected from its icon.  Thanks go to Stephen Kitt for this code.
+
+  * Updated include PNG library to latest stable version.
+
 -Have fun!
 
 

docs/index.html

@@ -10,7 +10,7 @@
   <br><br>
   <center><h2><b>A multi-platform Atari 2600 VCS emulator</b></h2></center>
 
-  <center><h4><b>Release 3.4.1</b></h4></center>
+  <center><h4><b>Release 3.5</b></h4></center>
   <br><br>
 
   <center><h2><b>User's Guide</b></h2></center>
@@ -52,7 +52,7 @@
 
   <br><br><br>
 
-  <center><b>February 1999 - June 2011</b></center>
+  <center><b>February 1999 - December 2011</b></center>
     <center><b>The Stella Team</b></center>
   <center><b><a href="http://stella.sourceforge.net">Stella Homepage</a></b></center>
 
@@ -266,6 +266,7 @@
     <li>Supports EEPROM emulation for <a href="http://www.richard.hutchinson.dsl.pipex.com/new_page_5.htm">
       AtariVox</a> and <a href="http://www.vectrex.biz/MemCard.htm">SaveKey</a> controllers</li>
     <li>Supports all known bankswitching schemes (let us know if there's one we missed)</li>
+    <li>Supports DPC+ bankswitching scheme from the Harmony cart, including emulation of the ARM processor</li>
     <li>Supports cartridge autodetection for almost all bankswitching schemes</li>
     <li>Supports Supercharger single-load and multi-load games</li>
     <li>Supports ROMs stored in ZIP and GZIP format, as well as the usual A26/BIN/ROM formats</li>
@@ -277,7 +278,7 @@
     <li>TIA emulation supports full collision checking, with ability to disable
       both TIA sprites and collisions for each object separately</li>
     <li>Built-in extensive debugger, including the Distella disassembler</li>
-    <li>Emulation of CRT TV systems with OpenGL shaders, including texturing,
+    <li>FIXME - change to Blargg - Emulation of CRT TV systems with OpenGL shaders, including texturing,
       colour bleed, RF noise, and phosphor burn-off</li>
     <li>Built-in ROM database with information compiled by RomHunter</li>
   </ul>
@@ -1977,6 +1978,15 @@
       can be created, allowing to simulate testing on 'smaller' systems.</td>
     </tr>
 
+    <tr>
+      <td><pre>-thumb.trapfatal &lt;true|false&gt;</pre></td>
+      <td>Useful for developers, the default of true allows the Thumb ARM emulation to
+      throw an exception and enter the debugger on fatal errors.  When disabled, such
+      fatal errors are simply logged, and emulation continues.  Do not use this
+      unless you know exactly what you're doing, as it changes the behaviour as compared
+      to real hardware.</td>
+    </tr>
+
     <tr>
       <td><pre>-help</pre></td>
       <td>Prints a help message describing these options, and then

src/emucore/EventHandler.cxx

@@ -1876,10 +1876,8 @@ inline bool EventHandler::eventIsAnalog(Event::Type event) const
 }
 
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-StringList EventHandler::getActionList(EventMode mode) const
+void EventHandler::getActionList(EventMode mode, StringList& l) const
 {
-  StringList l;
-
   switch(mode)
   {
     case kEmulationMode:
@@ -1893,16 +1891,13 @@ StringList EventHandler::getActionList(EventMode mode) const
     default:
       break;
   }
-
-  return l;
 }
 
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-StringMap EventHandler::getComboList(EventMode) const
+void EventHandler::getComboList(EventMode, StringMap& l) const
 {
   // For now, this only works in emulation mode
 
-  StringMap l;
   ostringstream buf;
 
   l.push_back("None", "-1");
@@ -1913,14 +1908,11 @@ StringMap EventHandler::getComboList(EventMode) const
       l.push_back(EventHandler::ourEmulActionList[i].action, buf.str());
       buf.str("");
     }
-
-  return l;
 }
 
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-StringList EventHandler::getComboListForEvent(Event::Type event) const
+void EventHandler::getComboListForEvent(Event::Type event, StringList& l) const
 {
-  StringList l;
   ostringstream buf;
   if(event >= Event::Combo1 && event <= Event::Combo16)
   {
@@ -1943,7 +1935,6 @@ StringList EventHandler::getComboListForEvent(Event::Type event) const
         l.push_back("-1");
     }
   }
-  return l;
 }
 
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

src/emucore/EventHandler.hxx

@@ -239,11 +239,11 @@ class EventHandler
 
     SDL_Joystick* getJoystick(int i) const { return ourJoysticks[i].stick; }
 
-    StringList getActionList(EventMode mode) const;
+    void getActionList(EventMode mode, StringList& list) const;
-    StringMap getComboList(EventMode mode) const;
+    void getComboList(EventMode mode, StringMap& map) const;
 
     /** Used to access the list of events assigned to a specific combo event. */
-    StringList getComboListForEvent(Event::Type event) const;
+    void getComboListForEvent(Event::Type event, StringList& list) const;
     void setComboListForEvent(Event::Type event, const StringList& events);
 
     Event::Type eventForKey(int key, EventMode mode) const

src/emucore/Settings.cxx

@@ -574,7 +574,8 @@ void Settings::setString(const string& key, const string& value)
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 void Settings::getSize(const string& key, int& x, int& y) const
 {
-  char c;
+  char c = '\0';
+  x = y = -1;
   string size = getString(key);
   istringstream buf(size);
   buf >> x >> c >> y;

src/emucore/TIA.cxx

@@ -1361,6 +1361,8 @@ bool TIA::poke(uInt16 addr, uInt8 value)
 
     case NUSIZ0:  // Number-size of player-missle 0
     {
+      // TODO - 08-11-2009: determine correct delay instead of always
+      //                    using '8' in TIATables::PokeDelay
       myNUSIZ0 = value;
       mySuppressP0 = 0;
       break;
@@ -1368,6 +1370,8 @@ bool TIA::poke(uInt16 addr, uInt8 value)
 
     case NUSIZ1:  // Number-size of player-missle 1
     {
+      // TODO - 08-11-2009: determine correct delay instead of always
+      //                    using '8' in TIATables::PokeDelay
       myNUSIZ1 = value;
       mySuppressP1 = 0;
       break;

src/gui/ComboDialog.cxx

@@ -111,8 +111,8 @@ void ComboDialog::show(Event::Type event, const string& name)
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 void ComboDialog::loadConfig()
 {
-  const StringList& events =
+  StringList events;
-    instance().eventHandler().getComboListForEvent(myComboEvent);
+  instance().eventHandler().getComboListForEvent(myComboEvent, events);
 
   int size = BSPF_min(events.size(), 8u);
   for(int i = 0; i < size; ++i)

src/gui/EventMappingWidget.cxx

@@ -98,8 +98,9 @@ EventMappingWidget::EventMappingWidget(GuiObject* boss, const GUI::Font& font,
     myComboButton->setTarget(this);
     addFocusWidget(myComboButton);
 
-    myComboDialog = new ComboDialog(boss, font,
+    StringMap combolist;
-      instance().eventHandler().getComboList(mode));
+    instance().eventHandler().getComboList(mode, combolist);
+    myComboDialog = new ComboDialog(boss, font, combolist);
   }
   else
     myComboButton = NULL;

src/gui/InputDialog.cxx

@@ -46,6 +46,7 @@ InputDialog::InputDialog(OSystem* osystem, DialogContainer* parent,
   const int vBorder = 4;
   int xpos, ypos, tabID;
   WidgetArray wid;
+  StringList actions;
 
   // Set real dimensions
   _w = BSPF_min(50 * fontWidth + 10, max_w);
@@ -60,21 +61,22 @@ InputDialog::InputDialog(OSystem* osystem, DialogContainer* parent,
 
   // 1) Event mapper for emulation actions
   tabID = myTab->addTab("Emul. Events");
-  const StringList& eactions = instance().eventHandler().getActionList(kEmulationMode);
+  instance().eventHandler().getActionList(kEmulationMode, actions);
   myEmulEventMapper = new EventMappingWidget(myTab, font, 2, 2,
                                              myTab->getWidth(),
                                              myTab->getHeight() - ypos,
-                                             eactions, kEmulationMode);
+                                             actions, kEmulationMode);
   myTab->setParentWidget(tabID, myEmulEventMapper);
   addToFocusList(myEmulEventMapper->getFocusList(), tabID);
 
   // 2) Event mapper for UI actions
   tabID = myTab->addTab("UI Events");
-  const StringList& mactions = instance().eventHandler().getActionList(kMenuMode);
+  actions.clear();
+  instance().eventHandler().getActionList(kMenuMode, actions);
   myMenuEventMapper = new EventMappingWidget(myTab, font, 2, 2,
                                              myTab->getWidth(),
                                              myTab->getHeight() - ypos,
-                                             mactions, kMenuMode);
+                                             actions, kMenuMode);
   myTab->setParentWidget(tabID, myMenuEventMapper);
   addToFocusList(myMenuEventMapper->getFocusList(), tabID);