libs/ardour/ardour/panner.h

   1 /*
   2     Copyright (C) 2004-2011 Paul Davis
   3
   4     This program is free software; you can redistribute it and/or modify
   5     it under the terms of the GNU General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or
   7     (at your option) any later version.
   8
   9     This program is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12     GNU General Public License for more details.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this program; if not, write to the Free Software
  16     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17
  18 */
  19
  20 #ifndef __ardour_panner_h__
  21 #define __ardour_panner_h__
  22
  23 #include <cmath>
  24 #include <cassert>
  25 #include <vector>
  26 #include <string>
  27 #include <iostream>
  28
  29 #include "pbd/cartesian.h"
  30 #include "pbd/signals.h"
  31 #include "pbd/stateful.h"
  32
  33 #include "ardour/types.h"
  34 #include "ardour/automation_control.h"
  35 #include "ardour/automatable.h"
  36
  37 namespace ARDOUR {
  38
  39 class Session;
  40 class Pannable;
  41 class BufferSet;
  42 class AudioBuffer;
  43 class Speakers;
  44
  45 class Panner : public PBD::Stateful, public PBD::ScopedConnectionList
  46 {
  47   public:
  48         Panner (boost::shared_ptr<Pannable>);
  49         ~Panner ();
  50
  51         virtual ChanCount in() const = 0;
  52         virtual ChanCount out() const = 0;
  53
  54         virtual void configure_io (ARDOUR::ChanCount in, ARDOUR::ChanCount out) {}
  55
  56         /* derived implementations of these methods must indicate
  57            whether it is legal for a Controllable to use the
  58            value of the argument (post-call) in a call to
  59            Controllable::set_value().
  60
  61            they have a choice of:
  62
  63            * return true, leave argument unchanged
  64            * return true, modify argument
  65            * return false
  66
  67         */
  68
  69         virtual bool clamp_position (double&) { return true; }
  70         virtual bool clamp_width (double&) { return true; }
  71         virtual bool clamp_elevation (double&) { return true; }
  72
  73         virtual void set_position (double) { }
  74         virtual void set_width (double) { }
  75         virtual void set_elevation (double) { }
  76
  77         virtual double position () const { return 0.0; }
  78         virtual double width () const { return 0.0; }
  79         virtual double elevation () const { return 0.0; }
  80
  81         virtual void reset() {}
  82
  83         virtual bool bypassed() const { return _bypassed; }
  84         virtual void set_bypassed (bool yn);
  85
  86         virtual bool is_mono () const { return _mono; }
  87         virtual void set_mono (bool);
  88
  89         void      set_automation_state (AutoState);
  90         AutoState automation_state() const;
  91         void      set_automation_style (AutoStyle);
  92         AutoStyle automation_style() const;
  93
  94         virtual std::set<Evoral::Parameter> what_can_be_automated() const;
  95         virtual std::string describe_parameter (Evoral::Parameter);
  96
  97         bool touching() const;
  98
  99         static double azimuth_to_lr_fract (double azi) {
 100                 /* 180.0 degrees=> left => 0.0 */
 101                 /* 0.0 degrees => right => 1.0 */
 102
 103                 /* humans can only distinguish 1 degree of arc between two positions,
 104                    so force azi back to an integral value before computing
 105                 */
 106
 107                 return 1.0 - (rint(azi)/180.0);
 108         }
 109
 110         static double lr_fract_to_azimuth (double fract) {
 111                 /* fract = 0.0 => degrees = 180.0 => left */
 112                 /* fract = 1.0 => degrees = 0.0 => right */
 113
 114                 /* humans can only distinguish 1 degree of arc between two positions,
 115                    so force azi back to an integral value after computing
 116                 */
 117
 118                 return rint (180.0 - (fract * 180.0));
 119         }
 120
 121         /**
 122          *  Pan some input buffers to a number of output buffers.
 123          *
 124          *  @param ibufs Input buffers (one per panner input)
 125          *  @param obufs Output buffers (one per panner output).
 126          *  @param gain_coeff fixed, additional gain coefficient to apply to output samples.
 127          *  @param nframes Number of frames in the input.
 128          *
 129          *  Derived panners can choose to implement these if they need to gain more control over the panning algorithm.
 130          *  the default is to (1) check if _mono is true, and if so, just deliver .. (2) otherwise, call
 131          *  distribute_one() or distribute_one_automated() on each input buffer to deliver it to each output
 132          *  buffer.
 133          *
 134          *  If a panner does not need to override this default behaviour, it can just implement
 135          *  distribute_one() and distribute_one_automated() (below).
 136          */
 137         virtual void distribute (BufferSet& ibufs, BufferSet& obufs, gain_t gain_coeff, pframes_t nframes);
 138         virtual void distribute_automated (BufferSet& ibufs, BufferSet& obufs,
 139                                            framepos_t start, framepos_t end, pframes_t nframes,
 140                                            pan_t** buffers);
 141
 142         PBD::Signal0<void> Changed;      /* for positional info */
 143         PBD::Signal0<void> StateChanged; /* for mute, mono */
 144
 145         int set_state (const XMLNode&, int version);
 146         virtual XMLNode& state (bool full_state) = 0;
 147
 148         boost::shared_ptr<Pannable> pannable() const { return _pannable; }
 149
 150         //virtual std::string describe_parameter (Evoral::Parameter);
 151         //virtual std::string value_as_string (Evoral::Parameter, double val);
 152
 153         static bool equivalent (pan_t a, pan_t b) {
 154                 return fabsf (a - b) < 0.002; // about 1 degree of arc for a stereo panner
 155         }
 156
 157         static bool equivalent (const PBD::AngularVector& a, const PBD::AngularVector& b) {
 158                 /* XXX azimuth only, at present */
 159                 return fabs (a.azi - b.azi) < 1.0;
 160         }
 161
 162   protected:
 163         boost::shared_ptr<Pannable> _pannable;
 164         bool        _mono;
 165         bool        _bypassed;
 166
 167         XMLNode& get_state ();
 168
 169
 170         virtual void distribute_one (AudioBuffer&, BufferSet& obufs, gain_t gain_coeff, pframes_t nframes, uint32_t which) = 0;
 171         virtual void distribute_one_automated (AudioBuffer&, BufferSet& obufs,
 172                                                framepos_t start, framepos_t end, pframes_t nframes,
 173                                                pan_t** buffers, uint32_t which) = 0;
 174 };
 175
 176 } // namespace
 177
 178 extern "C" {
 179         struct PanPluginDescriptor {
 180             std::string name;
 181             int32_t in;
 182             int32_t out;
 183             ARDOUR::Panner* (*factory)(boost::shared_ptr<ARDOUR::Pannable>, ARDOUR::Speakers&);
 184         };
 185 }
 186
 187 #endif /* __ardour_panner_h__ */