# HG changeset patch
# User Chris Cannam
# Date 1175275008 0
# Node ID fbd09fcda4695f31b3ccce3efaca951737bb4d88
# Parent  8d31c8e9c820b519b5e164fd5979b98c8385ebe1
* doc updates

diff -r 8d31c8e9c820 -r fbd09fcda469 audioio/AudioCallbackPlaySource.cpp
--- a/audioio/AudioCallbackPlaySource.cpp	Thu Mar 15 16:13:59 2007 +0000
+++ b/audioio/AudioCallbackPlaySource.cpp	Fri Mar 30 17:16:48 2007 +0000
@@ -195,7 +195,7 @@
     m_audioGenerator->setTargetChannelCount(getTargetChannelCount());
 
     if (!m_fillThread) {
-	m_fillThread = new AudioCallbackPlaySourceFillThread(*this);
+	m_fillThread = new FillThread(*this);
 	m_fillThread->start();
     }
 
@@ -1382,7 +1382,7 @@
 }
 
 void
-AudioCallbackPlaySource::AudioCallbackPlaySourceFillThread::run()
+AudioCallbackPlaySource::FillThread::run()
 {
     AudioCallbackPlaySource &s(m_source);
     
diff -r 8d31c8e9c820 -r fbd09fcda469 audioio/AudioCallbackPlaySource.h
--- a/audioio/AudioCallbackPlaySource.h	Thu Mar 15 16:13:59 2007 +0000
+++ b/audioio/AudioCallbackPlaySource.h	Fri Mar 30 17:16:48 2007 +0000
@@ -305,10 +305,10 @@
     // Called from getSourceSamples.
     void applyAuditioningEffect(size_t count, float **buffers);
 
-    class AudioCallbackPlaySourceFillThread : public Thread
+    class FillThread : public Thread
     {
     public:
-	AudioCallbackPlaySourceFillThread(AudioCallbackPlaySource &source) :
+	FillThread(AudioCallbackPlaySource &source) :
             Thread(Thread::NonRTThread),
 	    m_source(source) { }
 
@@ -320,7 +320,7 @@
 
     QMutex m_mutex;
     QWaitCondition m_condition;
-    AudioCallbackPlaySourceFillThread *m_fillThread;
+    FillThread *m_fillThread;
     SRC_STATE *m_converter;
     SRC_STATE *m_crapConverter; // for use when playing very fast
     int m_resampleQuality;
diff -r 8d31c8e9c820 -r fbd09fcda469 document/Document.h
--- a/document/Document.h	Thu Mar 15 16:13:59 2007 +0000
+++ b/document/Document.h	Fri Mar 30 17:16:48 2007 +0000
@@ -37,20 +37,21 @@
  * 
  * The document manages:
  * 
- * -- A main data model, which provides the underlying sample rate and
- * such like.  This must be a wave file model.
+ *  - A main data Model, which provides the underlying sample rate and
+ * such like.  This must be a WaveFileModel.
  * 
- * -- Any number of imported models, which contain data without any
+ *  - Any number of imported Model objects, which contain data without any
  * requirement to remember where the data came from or how to
  * regenerate it.
  * 
- * -- Any number of models generated by transforms such as feature
- * extraction plugins.  For these, we also record the source model and
- * the name of the transform used to generate the model so that we can
- * regenerate it (potentially from a different source) on demand.
+ *  - Any number of Model objects that were generated by a Transform
+ * such as FeatureExtractionPluginTransform.  For these, we also
+ * record the source model and the name of the transform used to
+ * generate the model so that we can regenerate it (potentially
+ * from a different source) on demand.
  *
- * -- A flat list of layers.  Elsewhere, the GUI may distribute these
- * across any number of view widgets.  A layer may be viewable on more
+ *  - A flat list of Layer objects.  Elsewhere, the GUI may distribute these
+ * across any number of View widgets.  A layer may be viewable on more
  * than one view at once, in principle.  A layer refers to one model,
  * but the same model can be in use in more than one layer.
  *
diff -r 8d31c8e9c820 -r fbd09fcda469 document/SVFileReader.cpp
--- a/document/SVFileReader.cpp	Thu Mar 15 16:13:59 2007 +0000
+++ b/document/SVFileReader.cpp	Fri Mar 30 17:16:48 2007 +0000
@@ -41,113 +41,6 @@
 
 #include <iostream>
 
-/*
-    Some notes about the SV XML format.  We're very lazy with our XML:
-    there's no schema or DTD, and we depend heavily on elements being
-    in a particular order.
- 
-    <sv>
-
-    <data>
-
-      <!-- The data section contains definitions of both models and
-           visual layers.  Layers are considered data in the document;
-           the structure of views that displays the layers is not. -->
-
-      <!-- id numbers are unique within the data type (i.e. no two
-           models can have the same id, but a model can have the same
-           id as a layer, etc).  SV generates its id numbers just for
-           the purpose of cross-referencing within the current file;
-           they don't necessarily have any meaning once the file has
-           been loaded. -->
-
-      <model id="0" name="..." type="..." ... />
-      <model id="1" name="..." type="..." ... />
-
-      <!-- Models that have data associated with them store it
-           in a neighbouring dataset element.  The dataset must follow
-           the model and precede any derivation or layer elements that
-           refer to the model. -->
-
-      <model id="2" name="..." type="..." dataset="0" ... />
-
-      <dataset id="0" type="..."> 
-        <point frame="..." value="..." ... />
-      </dataset>
-
-      <!-- Where one model is derived from another via a transform,
-           it has an associated derivation element.  This must follow
-           both the source and target model elements.  The source and
-           model attributes give the source model id and target model
-           id respectively.  A model can have both dataset and
-           derivation elements; if it does, dataset must appear first. 
-           If the model's data are not stored, but instead the model
-           is to be regenerated completely from the transform when 
-           the session is reloaded, then the model should have _only_
-           a derivation element, and no model element should appear
-           for it at all. -->
-
-      <derivation source="0" model="2" transform="..." ...>
-        <plugin id="..." ... />
-      </derivation>
-
-      <!-- The playparameters element lists playback settings for
-           a model. -->
-
-      <playparameters mute="false" pan="0" gain="1" model="1" ... />
-
-      <!-- Layer elements.  The models must have already been defined.
-           The same model may appear in more than one layer (of more
-           than one type). -->
-
-      <layer id="1" type="..." name="..." model="0" ... />
-      <layer id="2" type="..." name="..." model="1" ... />
-
-    </data>
-
-
-    <display>
-
-      <!-- The display element contains visual structure for the
-           layers.  It's simpler than the data section. -->
-
-      <!-- Overall preferred window size for this session. -->
-
-      <window width="..." height="..."/>
-
-      <!-- List of view elements to stack up.  Each one contains
-           a list of layers in stacking order, back to front. -->
-
-      <view type="pane" ...>
-        <layer id="1"/>
-        <layer id="2"/>
-      </view>
-
-      <!-- The layer elements just refer to layers defined in the
-           data section, so they don't have to have any attributes
-           other than the id.  For sort-of-historical reasons SV
-           actually does repeat the other attributes here, but
-           it doesn't need to. -->
-
-      <view type="pane" ...>
-        <layer id="2"/>
-      <view>
-
-    </display>
-
-
-    <!-- List of selected regions by audio frame extents. -->
-
-    <selections>
-      <selection start="..." end="..."/>
-    </selections>
-
-
-    </sv>
- 
- */
-
-
 SVFileReader::SVFileReader(Document *document,
 			   SVFileReaderPaneCallback &callback,
                            QString location) :
diff -r 8d31c8e9c820 -r fbd09fcda469 document/SVFileReader.h
--- a/document/SVFileReader.h	Thu Mar 15 16:13:59 2007 +0000
+++ b/document/SVFileReader.h	Fri Mar 30 17:16:48 2007 +0000
@@ -37,6 +37,119 @@
     virtual void addSelection(int start, int end) = 0;
 };
 
+/**
+    SVFileReader loads Sonic Visualiser XML files.  (The SV file
+    format is bzipped XML.)
+
+    Some notes about the SV XML format follow.  We're very lazy with
+    our XML: there's no schema or DTD, and we depend heavily on
+    elements being in a particular order.
+ 
+\verbatim
+
+    <sv>
+
+    <data>
+
+      <!-- The data section contains definitions of both models and
+           visual layers.  Layers are considered data in the document;
+           the structure of views that displays the layers is not. -->
+
+      <!-- id numbers are unique within the data type (i.e. no two
+           models can have the same id, but a model can have the same
+           id as a layer, etc).  SV generates its id numbers just for
+           the purpose of cross-referencing within the current file;
+           they don't necessarily have any meaning once the file has
+           been loaded. -->
+
+      <model id="0" name="..." type="..." ... />
+      <model id="1" name="..." type="..." ... />
+
+      <!-- Models that have data associated with them store it
+           in a neighbouring dataset element.  The dataset must follow
+           the model and precede any derivation or layer elements that
+           refer to the model. -->
+
+      <model id="2" name="..." type="..." dataset="0" ... />
+
+      <dataset id="0" type="..."> 
+        <point frame="..." value="..." ... />
+      </dataset>
+
+      <!-- Where one model is derived from another via a transform,
+           it has an associated derivation element.  This must follow
+           both the source and target model elements.  The source and
+           model attributes give the source model id and target model
+           id respectively.  A model can have both dataset and
+           derivation elements; if it does, dataset must appear first. 
+           If the model's data are not stored, but instead the model
+           is to be regenerated completely from the transform when 
+           the session is reloaded, then the model should have _only_
+           a derivation element, and no model element should appear
+           for it at all. -->
+
+      <derivation source="0" model="2" transform="..." ...>
+        <plugin id="..." ... />
+      </derivation>
+
+      <!-- The playparameters element lists playback settings for
+           a model. -->
+
+      <playparameters mute="false" pan="0" gain="1" model="1" ... />
+
+      <!-- Layer elements.  The models must have already been defined.
+           The same model may appear in more than one layer (of more
+           than one type). -->
+
+      <layer id="1" type="..." name="..." model="0" ... />
+      <layer id="2" type="..." name="..." model="1" ... />
+
+    </data>
+
+
+    <display>
+
+      <!-- The display element contains visual structure for the
+           layers.  It's simpler than the data section. -->
+
+      <!-- Overall preferred window size for this session. -->
+
+      <window width="..." height="..."/>
+
+      <!-- List of view elements to stack up.  Each one contains
+           a list of layers in stacking order, back to front. -->
+
+      <view type="pane" ...>
+        <layer id="1"/>
+        <layer id="2"/>
+      </view>
+
+      <!-- The layer elements just refer to layers defined in the
+           data section, so they don't have to have any attributes
+           other than the id.  For sort-of-historical reasons SV
+           actually does repeat the other attributes here, but
+           it doesn't need to. -->
+
+      <view type="pane" ...>
+        <layer id="2"/>
+      <view>
+
+    </display>
+
+
+    <!-- List of selected regions by audio frame extents. -->
+
+    <selections>
+      <selection start="..." end="..."/>
+    </selections>
+
+
+    </sv>
+ 
+\endverbatim
+ */
+
+
 class SVFileReader : public QXmlDefaultHandler
 {
 public:
diff -r 8d31c8e9c820 -r fbd09fcda469 main/MainWindow.cpp
--- a/main/MainWindow.cpp	Thu Mar 15 16:13:59 2007 +0000
+++ b/main/MainWindow.cpp	Fri Mar 30 17:16:48 2007 +0000
@@ -4711,7 +4711,7 @@
     aboutText += tr("<br>With libsndfile &copy; Erik de Castro Lopo");
 #endif
 #endif
-#ifdef HAVE_FFTW3
+#ifdef HAVE_FFTW3F
 #ifdef FFTW3_VERSION
     aboutText += tr("<br>With FFTW3 (v%1) &copy; Matteo Frigo and MIT").arg(FFTW3_VERSION);
 #else
diff -r 8d31c8e9c820 -r fbd09fcda469 main/main.cpp
--- a/main/main.cpp	Thu Mar 15 16:13:59 2007 +0000
+++ b/main/main.cpp	Fri Mar 30 17:16:48 2007 +0000
@@ -35,6 +35,124 @@
 #include <iostream>
 #include <signal.h>
 
+/*! \mainpage Sonic Visualiser
+
+\section interesting Summary of interesting classes
+
+ - Data models: Model and subclasses, e.g. WaveFileModel
+
+ - Graphical layers: Layer and subclasses, displayed on View and its
+ subclass widgets.
+
+ - Main window class, document class, and file parser: MainWindow,
+ Document, SVFileReader
+
+ - Turning one model (e.g. audio) into another (e.g. more audio, or a
+ curve extracted from it): Transform and subclasses
+
+ - Creating the plugins used by transforms: RealTimePluginFactory,
+ FeatureExtractionPluginFactory
+
+ - File reading and writing code: AudioFileReader and subclasses,
+ WavFileWriter, DataFileReader, SVFileReader
+
+ - FFT calculation and cacheing: FFTModel, FFTDataServer
+
+ - Widgets that show groups of editable properties: PropertyBox for
+ layer properties (contained in a PropertyStack), PluginParameterBox
+ for plugins (contained in a PluginParameterDialog)
+
+ - Audio playback: AudioCallbackPlaySource and subclasses,
+ AudioCallbackPlayTarget and subclasses, AudioGenerator
+
+\section model Data sources: the Model hierarchy
+
+   A Model is something containing, or knowing how to obtain, data.
+
+   For example, WaveFileModel is a model that knows how to get data
+   from an audio file; SparseTimeValueModel is a model containing
+   editable "curve" data.
+
+   Models typically subclass one of a number of abstract subclasses of
+   Model.  For example, WaveFileModel subclasses DenseTimeValueModel,
+   which describes an interface for models that have a value at each
+   time point for a given sampling resolution.  (Note that
+   WaveFileModel does not actually read the files itself: it uses
+   AudioFileReader classes for that.  It just makes data from the
+   files available in a Model.)  SparseTimeValueModel uses the
+   SparseModel template class, which provides most of the
+   implementation for models that contain a series of points of some
+   sort -- also used by NoteModel, TextModel, and
+   SparseOneDimensionalModel.
+
+   Everything that goes on the screen originates from a model, via a
+   layer (see below).  The models are contained in a Document object.
+   There is no containment hierarchy or ordering of models in the
+   document.  One model is the main model, which defines the sample
+   rate for playback.
+
+   A model may also be marked as a "derived" model, which means it was
+   generated from another model using some transform (feature
+   extraction or effect plugin, etc) -- the idea being that they can
+   be re-generated using the same transform if a new source model is
+   loaded.
+
+\section layer Things that can display data: the Layer hierarchy
+
+   A Layer is something that knows how to draw parts of a model onto a
+   timeline.
+
+   For example, WaveformLayer is a layer which draws waveforms, based
+   on WaveFileModel; TimeValueLayer draws curves, based on
+   SparseTimeValueModel; SpectrogramLayer draws spectrograms, based on
+   WaveFileModel (via FFTModel).
+
+   The most basic functions of a layer are: to draw itself onto a
+   Pane, against a timeline on the x axis; and to permit user
+   interaction.  If you were thinking of adding the capability to
+   display a new sort of something, then you would want to add a new
+   layer type.  (You may also need a new model type, depending on
+   whether any existing model can capture the data you need.)
+   Depending on the sort of data in question, there are various
+   existing layers that might be appropriate to start from -- for
+   example, a layer that displays images that the user has imported
+   and associated with particular times might have something in common
+   with the existing TextLayer which displays pieces of text that are
+   associated with particular times.
+
+   Although layers are visual objects, they are contained in the
+   Document in Sonic Visualiser rather than being managed together
+   with display widgets.  The Sonic Visualiser file format has
+   separate data and layout sections, and the layers are defined in
+   the data section and then referred to in the layout section which
+   determines which layers may go on which panes (see Pane below).
+
+   Once a layer class is defined, some basic data about it needs to be
+   set up in the LayerFactory class, and then it will appear in the
+   menus and so on on the main window.
+
+\section view Widgets that are used to show layers: The View hierarchy
+
+   A View is a widget that displays a stack of layers.  The most
+   important subclass is Pane, the widget that is used to show most of
+   the data in the main window of Sonic Visualiser.
+
+   All a pane really does is contain a set of layers and get them to
+   render themselves (one on top of the other, with the topmost layer
+   being the one that is currently interacted with), cache the
+   results, negotiate user interaction with them, and so on.  This is
+   generally fiddly, if not especially interesting.  Panes are
+   strictly layout objects and are not stored in the Document class;
+   instead the MainWindow contains a PaneStack widget (the widget that
+   takes up most of Sonic Visualiser's main window) which contains a
+   set of panes stacked vertically.
+
+   Another View subclass is Overview, which is the widget that
+   contains that green waveform showing the entire file at the bottom
+   of the window.
+
+*/
+
 static QMutex cleanupMutex;
 
 static void