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@329: #ifndef _TRANSFORMER_H_
Chris@329: #define _TRANSFORMER_H_
Chris@320: 
Chris@320: #include "base/Thread.h"
Chris@320: 
Chris@320: #include "data/model/Model.h"
Chris@320: 
Chris@383: #include "Transform.h"
Chris@383: 
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@320: 
Chris@331: class ModelTransformer : public Thread
Chris@320: {
Chris@320: public:
Chris@331:     virtual ~ModelTransformer();
Chris@320: 
Chris@383:     class Input {
Chris@383:     public:
Chris@383:         Input(Model *m) : m_model(m), m_channel(-1) { }
Chris@383:         Input(Model *m, int c) : m_model(m), m_channel(c) { }
Chris@383: 
Chris@383:         Model *getModel() const { return m_model; }
Chris@383:         void setModel(Model *m) { m_model = m; }
Chris@383: 
Chris@383:         int getChannel() const { return m_channel; }
Chris@383:         void setChannel(int c) { m_channel = c; }
Chris@383: 
Chris@383:     protected:
Chris@383:         Model *m_model;
Chris@383:         int m_channel;
Chris@383:     };
Chris@383: 
Chris@383:     /**
Chris@383:      * Hint to the processing thread that it should give up, for
Chris@383:      * example because the process is going to exit or we want to get
Chris@383:      * rid of the input model.  Caller should still wait() and/or
Chris@383:      * delete the transform before assuming its input and output
Chris@383:      * models are no longer required.
Chris@383:      */
Chris@320:     void abandon() { m_abandoned = true; }
Chris@320: 
Chris@383:     /**
Chris@383:      * Return the input model for the transform.
Chris@383:      */
Chris@383:     Model *getInputModel()  { return m_input.getModel(); }
Chris@383: 
Chris@383:     /**
Chris@383:      * Return the input channel spec for the transform.
Chris@383:      */
Chris@383:     int getInputChannel() { return m_input.getChannel(); }
Chris@383: 
Chris@383:     /**
Chris@383:      * Return the output model created by the transform.  Returns a
Chris@383:      * null model if the transform could not be initialised; an error
Chris@383:      * message may be available via getMessage() in this situation.
Chris@383:      */
Chris@320:     Model *getOutputModel() { return m_output; }
Chris@383: 
Chris@383:     /**
Chris@383:      * Return the output model, also detaching it from the transformer
Chris@383:      * so that it will not be deleted when the transformer is.  The
Chris@383:      * caller takes ownership of the model.
Chris@383:      */
Chris@320:     Model *detachOutputModel() { m_detached = true; return m_output; }
Chris@320: 
Chris@383:     /**
Chris@383:      * Return a warning or error message.  If getOutputModel returned
Chris@383:      * a null pointer, this should contain a fatal error message for
Chris@383:      * the transformer; otherwise it may contain a warning to show to
Chris@383:      * the user about e.g. suboptimal block size or whatever.  
Chris@383:      */
Chris@383:     QString getMessage() const { return m_message; }
Chris@383: 
Chris@320: protected:
Chris@383:     ModelTransformer(Input input, const Transform &transform);
Chris@320: 
Chris@383:     Transform m_transform;
Chris@383:     Input m_input; // I don't own the model in this
Chris@320:     Model *m_output; // I own this, unless...
Chris@320:     bool m_detached; // ... this is true.
Chris@320:     bool m_abandoned;
Chris@383:     QString m_message;
Chris@320: };
Chris@320: 
Chris@320: #endif