Chris@150: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@150: 
Chris@150: /*
Chris@150:     Sonic Visualiser
Chris@150:     An audio file viewer and annotation editor.
Chris@150:     Centre for Digital Music, Queen Mary, University of London.
Chris@150:     This file copyright 2006 Chris Cannam.
Chris@150:     
Chris@150:     This program is free software; you can redistribute it and/or
Chris@150:     modify it under the terms of the GNU General Public License as
Chris@150:     published by the Free Software Foundation; either version 2 of the
Chris@150:     License, or (at your option) any later version.  See the file
Chris@150:     COPYING included with this distribution for more information.
Chris@150: */
Chris@150: 
Chris@1500: #ifndef SV_MODEL_H
Chris@1500: #define SV_MODEL_H
Chris@150: 
Chris@150: #include <vector>
Chris@150: #include <QObject>
Chris@150: 
Chris@150: #include "base/XmlExportable.h"
Chris@391: #include "base/Playable.h"
Chris@1038: #include "base/BaseTypes.h"
Chris@1060: #include "base/DataExportOptions.h"
Chris@150: 
Chris@179: class ZoomConstraint;
Chris@319: class AlignmentModel;
Chris@179: 
Chris@1500: typedef int ModelId;
Chris@1500: 
Chris@150: /** 
Chris@150:  * Model is the base class for all data models that represent any sort
Chris@150:  * of data on a time scale based on an audio frame rate.
Chris@150:  */
Chris@150: 
Chris@179: class Model : public QObject,
Chris@1429:               public XmlExportable,
Chris@391:               public Playable
Chris@150: {
Chris@150:     Q_OBJECT
Chris@150: 
Chris@150: public:
Chris@150:     virtual ~Model();
Chris@150: 
Chris@150:     /**
Chris@150:      * Return true if the model was constructed successfully.  Classes
Chris@150:      * that refer to the model should always test this before use.
Chris@150:      */
Chris@150:     virtual bool isOK() const = 0;
Chris@150: 
Chris@150:     /**
Chris@150:      * Return the first audio frame spanned by the model.
Chris@150:      */
Chris@1038:     virtual sv_frame_t getStartFrame() const = 0;
Chris@150: 
Chris@150:     /**
Chris@1451:      * Return the audio frame at the end of the model, i.e. 1 more
Chris@1451:      * than the final frame contained within the model. The end frame
Chris@1451:      * minus the start frame should yield the total duration in frames
Chris@1451:      * spanned by the model. This is consistent with the definition of
Chris@1451:      * the end frame of a Selection object.
Chris@150:      */
Chris@1038:     virtual sv_frame_t getEndFrame() const = 0;
Chris@150: 
Chris@150:     /**
Chris@150:      * Return the frame rate in frames per second.
Chris@150:      */
Chris@1040:     virtual sv_samplerate_t getSampleRate() const = 0;
Chris@150: 
Chris@150:     /**
Chris@297:      * Return the frame rate of the underlying material, if the model
Chris@297:      * itself has already been resampled.
Chris@297:      */
Chris@1040:     virtual sv_samplerate_t getNativeRate() const { return getSampleRate(); }
Chris@297: 
Chris@297:     /**
Chris@333:      * Return the "work title" of the model, if known.
Chris@333:      */
Chris@333:     virtual QString getTitle() const;
Chris@333: 
Chris@333:     /**
Chris@333:      * Return the "artist" or "maker" of the model, if known.
Chris@333:      */
Chris@333:     virtual QString getMaker() const;
Chris@333: 
Chris@333:     /**
Chris@345:      * Return the location of the data in this model (e.g. source
Chris@345:      * URL).  This should not normally be returned for editable models
Chris@345:      * that have been edited.
Chris@345:      */
Chris@345:     virtual QString getLocation() const;
Chris@345: 
Chris@345:     /**
Chris@345:      * Return the type of the model.  For display purposes only.
Chris@345:      */
Chris@345:     virtual QString getTypeName() const = 0;
Chris@345: 
Chris@345:     /**
cannam@1452:      * Return true if this is a sparse model.
cannam@1452:      */
cannam@1452:     virtual bool isSparse() const { return false; }
Chris@1500: 
Chris@1500:     /**
Chris@1500:      * Return an id for this model. The id is guaranteed to be a
Chris@1500:      * unique identifier for this model among all models that may ever
Chris@1500:      * exist within this single run of the application.
Chris@1500:      */
Chris@1500:     ModelId getId() const { return m_id; }
cannam@1452:     
cannam@1452:     /**
Chris@923:      * Mark the model as abandoning. This means that the application
Chris@923:      * no longer needs it, so it can stop doing any background
Chris@923:      * calculations it may be involved in. Note that as far as the
Chris@923:      * model API is concerned, this does nothing more than tell the
Chris@923:      * model to return true from isAbandoning().  The actual response
Chris@923:      * to this will depend on the model's context -- it's possible
Chris@923:      * nothing at all will change.
Chris@923:      */
Chris@923:     virtual void abandon() {
Chris@923:         m_abandoning = true;
Chris@923:     }
Chris@923: 
Chris@923:     /**
Chris@923:      * Query whether the model has been marked as abandoning.
Chris@923:      */
Chris@923:     virtual bool isAbandoning() const { 
Chris@923:         return m_abandoning;
Chris@923:     }
Chris@923: 
Chris@150:     /**
Chris@150:      * Return true if the model has finished loading or calculating
Chris@150:      * all its data, for a model that is capable of calculating in a
Chris@150:      * background thread.  The default implementation is appropriate
Chris@150:      * for a thread that does not background any work but carries out
Chris@150:      * all its calculation from the constructor or accessors.
Chris@150:      *
Chris@150:      * If "completion" is non-NULL, this function should return
Chris@150:      * through it an estimated percentage value showing how far
Chris@150:      * through the background operation it thinks it is (for progress
Chris@150:      * reporting).  If it has no way to calculate progress, it may
Chris@1133:      * return the special value COMPLETION_UNKNOWN.  See also
Chris@1133:      * getCompletion().
Chris@150:      */
Chris@150:     virtual bool isReady(int *completion = 0) const {
Chris@1429:         bool ok = isOK();
Chris@1429:         if (completion) *completion = (ok ? 100 : 0);
Chris@1429:         return ok;
Chris@150:     }
Chris@150:     static const int COMPLETION_UNKNOWN;
Chris@150: 
Chris@179:     /**
Chris@179:      * If this model imposes a zoom constraint, i.e. some limit to the
Chris@179:      * set of resolutions at which its data can meaningfully be
Chris@179:      * displayed, then return it.
Chris@179:      */
Chris@179:     virtual const ZoomConstraint *getZoomConstraint() const {
Chris@179:         return 0;
Chris@179:     }
Chris@179: 
Chris@297:     /**
Chris@297:      * If this model was derived from another, return the model it was
Chris@297:      * derived from.  The assumption is that the source model's
Chris@297:      * alignment will also apply to this model, unless some other
Chris@319:      * property (such as a specific alignment model set on this model)
Chris@319:      * indicates otherwise.
Chris@297:      */
Chris@297:     virtual Model *getSourceModel() const {
Chris@297:         return m_sourceModel;
Chris@297:     }
Chris@297: 
Chris@297:     /**
Chris@297:      * Set the source model for this model.
Chris@297:      */
Chris@319:     virtual void setSourceModel(Model *model);
Chris@319: 
Chris@319:     /**
Chris@319:      * Specify an aligment between this model's timeline and that of a
Chris@319:      * reference model.  The alignment model records both the
Chris@319:      * reference and the alignment.  This model takes ownership of the
Chris@319:      * alignment model.
Chris@319:      */
Chris@319:     virtual void setAlignment(AlignmentModel *alignment);
Chris@319: 
Chris@319:     /**
Chris@407:      * Retrieve the alignment model for this model.  This is not a
Chris@407:      * generally useful function, as the alignment you really want may
Chris@407:      * be performed by the source model instead.  You should normally
Chris@407:      * use getAlignmentReference, alignToReference and
Chris@407:      * alignFromReference instead of this.  The main intended
Chris@407:      * application for this function is in streaming out alignments to
Chris@407:      * the session file.
Chris@407:      */
Chris@407:     virtual const AlignmentModel *getAlignment() const;
Chris@407: 
Chris@407:     /**
Chris@319:      * Return the reference model for the current alignment timeline,
Chris@319:      * if any.
Chris@319:      */
Chris@319:     virtual const Model *getAlignmentReference() const;
Chris@319: 
Chris@319:     /**
Chris@319:      * Return the frame number of the reference model that corresponds
Chris@319:      * to the given frame number in this model.
Chris@319:      */
Chris@1038:     virtual sv_frame_t alignToReference(sv_frame_t frame) const;
Chris@319: 
Chris@319:     /**
Chris@319:      * Return the frame number in this model that corresponds to the
Chris@319:      * given frame number of the reference model.
Chris@319:      */
Chris@1038:     virtual sv_frame_t alignFromReference(sv_frame_t referenceFrame) const;
Chris@319: 
Chris@319:     /**
Chris@319:      * Return the completion percentage for the alignment model: 100
Chris@319:      * if there is no alignment model or it has been entirely
Chris@319:      * calculated, or less than 100 if it is still being calculated.
Chris@319:      */
Chris@319:     virtual int getAlignmentCompletion() const;
Chris@297: 
Chris@558:     /**
Chris@558:      * Set the event, feature, or signal type URI for the features
Chris@558:      * contained in this model, according to the Audio Features RDF
Chris@558:      * ontology.
Chris@558:      */
Chris@558:     void setRDFTypeURI(QString uri) { m_typeUri = uri; }
Chris@558: 
Chris@558:     /**
Chris@558:      * Retrieve the event, feature, or signal type URI for the
Chris@558:      * features contained in this model, if previously set with
Chris@558:      * setRDFTypeURI.
Chris@558:      */
Chris@558:     QString getRDFTypeURI() const { return m_typeUri; }
Chris@558: 
Chris@1580:     void toXml(QTextStream &stream,
Chris@1608:                QString indent = "",
Chris@1608:                QString extraAttributes = "") const override;
Chris@150: 
Chris@838:     virtual QString toDelimitedDataString(QString delimiter) const {
Chris@1072:         return toDelimitedDataStringSubset
Chris@1451:             (delimiter, getStartFrame(), getEndFrame());
Chris@838:     }
Chris@1060:     virtual QString toDelimitedDataStringWithOptions(QString delimiter, DataExportOptions opts) const {
Chris@1072:         return toDelimitedDataStringSubsetWithOptions
Chris@1451:             (delimiter, opts, getStartFrame(), getEndFrame());
Chris@1060:     }
Chris@1038:     virtual QString toDelimitedDataStringSubset(QString, sv_frame_t /* f0 */, sv_frame_t /* f1 */) const {
Chris@838:         return "";
Chris@838:     }
Chris@1060:     virtual QString toDelimitedDataStringSubsetWithOptions(QString delimiter, DataExportOptions, sv_frame_t f0, sv_frame_t f1) const {
Chris@1060:         // Default implementation supports no options
Chris@1060:         return toDelimitedDataStringSubset(delimiter, f0, f1);
Chris@1060:     }
Chris@150: 
Chris@319: public slots:
Chris@319:     void aboutToDelete();
Chris@319:     void sourceModelAboutToBeDeleted();
Chris@319: 
Chris@150: signals:
Chris@150:     /**
Chris@150:      * Emitted when a model has been edited (or more data retrieved
Chris@150:      * from cache, in the case of a cached model that generates slowly)
Chris@150:      */
Chris@150:     void modelChanged();
Chris@150: 
Chris@150:     /**
Chris@150:      * Emitted when a model has been edited (or more data retrieved
Chris@150:      * from cache, in the case of a cached model that generates slowly)
Chris@150:      */
Chris@1038:     void modelChangedWithin(sv_frame_t startFrame, sv_frame_t endFrame);
Chris@150: 
Chris@150:     /**
Chris@150:      * Emitted when some internal processing has advanced a stage, but
Chris@150:      * the model has not changed externally.  Views should respond by
Chris@150:      * updating any progress meters or other monitoring, but not
Chris@150:      * refreshing the actual view.
Chris@150:      */
Chris@150:     void completionChanged();
Chris@150: 
Chris@319:     /**
Chris@411:      * Emitted when internal processing is complete (i.e. when
Chris@411:      * isReady() would return true, with completion at 100).
Chris@411:      */
Chris@411:     void ready();
Chris@411: 
Chris@411:     /**
Chris@319:      * Emitted when the completion percentage changes for the
Chris@319:      * calculation of this model's alignment model.
Chris@319:      */
Chris@319:     void alignmentCompletionChanged();
Chris@319: 
Chris@319:     /**
Chris@319:      * Emitted when something notifies this model (through calling
Chris@319:      * aboutToDelete() that it is about to delete it.  Note that this
Chris@319:      * depends on an external agent such as a Document object or
Chris@319:      * owning model telling the model that it is about to delete it;
Chris@319:      * there is nothing in the model to guarantee that this signal
Chris@319:      * will be emitted before the actual deletion.
Chris@319:      */
Chris@319:     void aboutToBeDeleted();
Chris@319: 
Chris@150: protected:
Chris@1500:     Model() :
Chris@1500:         m_id(getNextId()),
Chris@923:         m_sourceModel(0), 
Chris@923:         m_alignment(0), 
Chris@923:         m_abandoning(false), 
Chris@923:         m_aboutToDelete(false) { }
Chris@150: 
Chris@150:     // Not provided.
Chris@150:     Model(const Model &);
Chris@150:     Model &operator=(const Model &); 
Chris@297: 
Chris@1500:     const ModelId m_id;
Chris@297:     Model *m_sourceModel;
Chris@319:     AlignmentModel *m_alignment;
Chris@558:     QString m_typeUri;
Chris@923:     bool m_abandoning;
Chris@319:     bool m_aboutToDelete;
Chris@1500: 
Chris@1500:     int getNextId();
Chris@150: };
Chris@150: 
Chris@150: #endif