Chris@320: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@320: 
Chris@320: /*
Chris@320:     Sonic Visualiser
Chris@320:     An audio file viewer and annotation editor.
Chris@320:     Centre for Digital Music, Queen Mary, University of London.
Chris@320:     This file copyright 2006 Chris Cannam.
Chris@320:    
Chris@320:     This program is free software; you can redistribute it and/or
Chris@320:     modify it under the terms of the GNU General Public License as
Chris@320:     published by the Free Software Foundation; either version 2 of the
Chris@320:     License, or (at your option) any later version.  See the file
Chris@320:     COPYING included with this distribution for more information.
Chris@320: */
Chris@320: 
Chris@1367: #ifndef SV_MODEL_TRANSFORMER_H
Chris@1367: #define SV_MODEL_TRANSFORMER_H
Chris@320: 
Chris@320: #include "base/Thread.h"
Chris@320: 
Chris@320: #include "data/model/Model.h"
Chris@320: 
Chris@350: #include "Transform.h"
Chris@350: 
Chris@320: /**
Chris@331:  * A ModelTransformer turns one data model into another.
Chris@320:  *
Chris@331:  * Typically in this application, a ModelTransformer might have a
Chris@320:  * DenseTimeValueModel as its input (e.g. an audio waveform) and a
Chris@320:  * SparseOneDimensionalModel (e.g. detected beats) as its output.
Chris@320:  *
Chris@331:  * The ModelTransformer typically runs in the background, as a
Chris@331:  * separate thread populating the output model.  The model is
Chris@331:  * available to the user of the ModelTransformer immediately, but may
Chris@331:  * be initially empty until the background thread has populated it.
Chris@320:  */
Chris@331: class ModelTransformer : public Thread
Chris@320: {
Chris@320: public:
Chris@331:     virtual ~ModelTransformer();
Chris@320: 
Chris@1739:     typedef std::vector<ModelId> Models;
Chris@849: 
Chris@350:     class Input {
Chris@350:     public:
Chris@1739:         Input(ModelId m) : m_model(m), m_channel(-1) { }
Chris@1739:         Input(ModelId m, int c) : m_model(m), m_channel(c) { }
Chris@350: 
Chris@1739:         ModelId getModel() const { return m_model; }
Chris@1739:         void setModel(ModelId m) { m_model = m; }
Chris@350: 
Chris@350:         int getChannel() const { return m_channel; }
Chris@350:         void setChannel(int c) { m_channel = c; }
Chris@350: 
Chris@350:     protected:
Chris@1739:         ModelId m_model;
Chris@350:         int m_channel;
Chris@350:     };
Chris@350: 
Chris@361:     /**
Chris@361:      * Hint to the processing thread that it should give up, for
Chris@1739:      * example because the process is going to exit or the
Chris@1739:      * model/document context is being replaced.  Caller should still
Chris@1739:      * wait() to be sure that processing has ended.
Chris@361:      */
Chris@320:     void abandon() { m_abandoned = true; }
Chris@320: 
Chris@361:     /**
Chris@1079:      * Return true if the processing thread is being or has been
Chris@1079:      * abandoned, i.e. if abandon() has been called.
Chris@1079:      */
Chris@1079:     bool isAbandoned() const { return m_abandoned; }
Chris@1079:     
Chris@1079:     /**
Chris@361:      * Return the input model for the transform.
Chris@361:      */
Chris@1739:     ModelId getInputModel()  { return m_input.getModel(); }
Chris@361: 
Chris@361:     /**
Chris@361:      * Return the input channel spec for the transform.
Chris@361:      */
Chris@350:     int getInputChannel() { return m_input.getChannel(); }
Chris@350: 
Chris@361:     /**
Chris@1739:      * Return the set of output model IDs created by the transform or
Chris@1739:      * transforms. Returns an empty list if any transform could not be
Chris@1739:      * initialised; an error message may be available via getMessage()
Chris@1739:      * in this situation. The returned models have been added to
Chris@1739:      * ModelById.
Chris@361:      */
Chris@1211:     Models getOutputModels() {
Chris@1211:         awaitOutputModels();
Chris@1211:         return m_outputs;
Chris@1211:     }
Chris@361: 
Chris@361:     /**
Chris@877:      * Return any additional models that were created during
Chris@877:      * processing. This might happen if, for example, a transform was
Chris@877:      * configured to split a multi-bin output into separate single-bin
Chris@877:      * models as it processed. These should not be queried until after
Chris@877:      * the transform has completed.
Chris@877:      */
Chris@877:     virtual Models getAdditionalOutputModels() { return Models(); }
Chris@877: 
Chris@877:     /**
Chris@877:      * Return true if the current transform is one that may produce
Chris@877:      * additional models (to be retrieved through
Chris@877:      * getAdditionalOutputModels above).
Chris@877:      */
Chris@877:     virtual bool willHaveAdditionalOutputModels() { return false; }
Chris@877: 
Chris@877:     /**
Chris@361:      * Return a warning or error message.  If getOutputModel returned
Chris@361:      * a null pointer, this should contain a fatal error message for
Chris@361:      * the transformer; otherwise it may contain a warning to show to
Chris@361:      * the user about e.g. suboptimal block size or whatever.  
Chris@361:      */
Chris@361:     QString getMessage() const { return m_message; }
Chris@361: 
Chris@320: protected:
Chris@350:     ModelTransformer(Input input, const Transform &transform);
Chris@849:     ModelTransformer(Input input, const Transforms &transforms);
Chris@320: 
Chris@1211:     virtual void awaitOutputModels() = 0;
Chris@1211:     
Chris@849:     Transforms m_transforms;
Chris@1739:     Input m_input;
Chris@1739:     Models m_outputs;
Chris@320:     bool m_abandoned;
Chris@361:     QString m_message;
Chris@320: };
Chris@320: 
Chris@320: #endif