Mercurial > hg > sonic-visualiser
changeset 127:fbd09fcda469
* doc updates
| author | Chris Cannam |
|---|---|
| date | Fri, 30 Mar 2007 17:16:48 +0000 |
| parents | 8d31c8e9c820 |
| children | 6caf27d1e5e8 |
| files | audioio/AudioCallbackPlaySource.cpp audioio/AudioCallbackPlaySource.h document/Document.h document/SVFileReader.cpp document/SVFileReader.h main/MainWindow.cpp main/main.cpp |
| diffstat | 7 files changed, 247 insertions(+), 122 deletions(-) [+] |
line wrap: on
line diff
--- 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);
--- 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;
--- 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. *
--- 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) :
--- 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:
--- 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 © Erik de Castro Lopo"); #endif #endif -#ifdef HAVE_FFTW3 +#ifdef HAVE_FFTW3F #ifdef FFTW3_VERSION aboutText += tr("<br>With FFTW3 (v%1) © Matteo Frigo and MIT").arg(FFTW3_VERSION); #else
--- 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