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 #if !defined(ARDOURPANNER_IS_IN_WINDLL)
  38         #if defined(COMPILER_MSVC) || defined(COMPILER_MINGW)
  39         // If you need '__declspec' compatibility, add extra compilers to the above as necessary
  40                 #define ARDOURPANNER_IS_IN_WINDLL 1
  41         #else
  42                 #define ARDOURPANNER_IS_IN_WINDLL 0
  43         #endif
  44 #endif
  45
  46 #if ARDOURPANNER_IS_IN_WINDLL && !defined(ARDOURPANNER_API)
  47         #if defined(BUILDING_ARDOURPANNERS)
  48                 #define ARDOURPANNER_API __declspec(dllexport)
  49                 #define ARDOURPANNER_APICALLTYPE __thiscall
  50                 #define ARDOURPANNER_CAPICALLTYPE __cdecl
  51         #elif defined(COMPILER_MSVC) || defined(COMPILER_MINGW) // Probably needs Cygwin too, at some point
  52                 #define ARDOURPANNER_API __declspec(dllimport)
  53                 #define ARDOURPANNER_APICALLTYPE __thiscall
  54                 #define ARDOURPANNER_CAPICALLTYPE __cdecl
  55         #else
  56                 #error "Attempting to define __declspec with an incompatible compiler !"
  57         #endif
  58 #elif !defined(ARDOURPANNER_API)
  59         // Other compilers / platforms could be accommodated here
  60         #define ARDOURPANNER_API
  61         #define ARDOURPANNER_APICALLTYPE
  62         #define ARDOURPANNER_CAPICALLTYPE
  63 #endif
  64
  65 namespace ARDOUR {
  66
  67 class Session;
  68 class Pannable;
  69 class BufferSet;
  70 class AudioBuffer;
  71 class Speakers;
  72
  73 class Panner : public PBD::Stateful, public PBD::ScopedConnectionList
  74 {
  75 public:
  76         Panner (boost::shared_ptr<Pannable>);
  77         ~Panner ();
  78
  79         virtual boost::shared_ptr<Speakers> get_speakers() const { return boost::shared_ptr<Speakers>(); }
  80
  81         virtual ChanCount in() const = 0;
  82         virtual ChanCount out() const = 0;
  83
  84         virtual void configure_io (ARDOUR::ChanCount /*in*/, ARDOUR::ChanCount /*out*/) {}
  85
  86         /* derived implementations of these methods must indicate
  87            whether it is legal for a Controllable to use the
  88            value of the argument (post-call) in a call to
  89            Controllable::set_value().
  90
  91            they have a choice of:
  92
  93            * return true, leave argument unchanged
  94            * return true, modify argument
  95            * return false
  96         */
  97
  98         virtual bool ARDOURPANNER_APICALLTYPE clamp_position (double&) { return true; }
  99         virtual bool clamp_width (double&) { return true; }
 100         virtual bool clamp_elevation (double&) { return true; }
 101
 102         virtual std::pair<double, double> position_range () const { return std::make_pair (-DBL_MAX, DBL_MAX); }
 103         virtual std::pair<double, double> width_range () const { return std::make_pair (-DBL_MAX, DBL_MAX); }
 104         virtual std::pair<double, double> elevation_range () const { return std::make_pair (-DBL_MAX, DBL_MAX); }
 105
 106         virtual void ARDOURPANNER_APICALLTYPE set_position (double) { }
 107         virtual void set_width (double) { }
 108         virtual void set_elevation (double) { }
 109
 110         virtual double position () const { return 0.0; }
 111         virtual double width () const { return 0.0; }
 112         virtual double elevation () const { return 0.0; }
 113
 114         virtual PBD::AngularVector signal_position (uint32_t) const { return PBD::AngularVector(); }
 115
 116         virtual void reset () = 0;
 117
 118         void      set_automation_state (AutoState);
 119         AutoState automation_state() const;
 120         void      set_automation_style (AutoStyle);
 121         AutoStyle automation_style() const;
 122
 123         virtual std::set<Evoral::Parameter> what_can_be_automated() const;
 124         virtual std::string describe_parameter (Evoral::Parameter);
 125         virtual std::string value_as_string (boost::shared_ptr<AutomationControl>) const;
 126
 127         bool touching() const;
 128
 129         static double azimuth_to_lr_fract (double azi) {
 130                 /* 180.0 degrees=> left => 0.0 */
 131                 /* 0.0 degrees => right => 1.0 */
 132
 133                 /* humans can only distinguish 1 degree of arc between two positions,
 134                    so force azi back to an integral value before computing
 135                 */
 136
 137                 return 1.0 - (rint(azi)/180.0);
 138         }
 139
 140         static double lr_fract_to_azimuth (double fract) {
 141                 /* fract = 0.0 => degrees = 180.0 => left */
 142                 /* fract = 1.0 => degrees = 0.0 => right */
 143
 144                 /* humans can only distinguish 1 degree of arc between two positions,
 145                    so force azi back to an integral value after computing
 146                 */
 147
 148                 return rint (180.0 - (fract * 180.0));
 149         }
 150
 151         /**
 152          *  Pan some input buffers to a number of output buffers.
 153          *
 154          *  @param ibufs Input buffers (one per panner input)
 155          *  @param obufs Output buffers (one per panner output).
 156          *  @param gain_coeff fixed, additional gain coefficient to apply to output samples.
 157          *  @param nframes Number of frames in the input.
 158          *
 159          *  Derived panners can choose to implement these if they need to gain more
 160          *  control over the panning algorithm.  The default is to call
 161          *  distribute_one() or distribute_one_automated() on each input buffer to
 162          *  deliver it to each output buffer.
 163          *
 164          *  If a panner does not need to override this default behaviour, it can
 165          *  just implement distribute_one() and distribute_one_automated() (below).
 166          */
 167         virtual void distribute (BufferSet& ibufs, BufferSet& obufs, gain_t gain_coeff, pframes_t nframes);
 168         virtual void distribute_automated (BufferSet& ibufs, BufferSet& obufs,
 169                                            framepos_t start, framepos_t end, pframes_t nframes,
 170                                            pan_t** buffers);
 171
 172         int set_state (const XMLNode&, int version);
 173         XMLNode& get_state ();
 174
 175         boost::shared_ptr<Pannable> pannable() const { return _pannable; }
 176
 177         static bool equivalent (pan_t a, pan_t b) {
 178                 return fabsf (a - b) < 0.002; // about 1 degree of arc for a stereo panner
 179         }
 180
 181         static bool equivalent (const PBD::AngularVector& a, const PBD::AngularVector& b) {
 182                 /* XXX azimuth only, at present */
 183                 return fabs (a.azi - b.azi) < 1.0;
 184         }
 185
 186         virtual void freeze ();
 187         virtual void thaw ();
 188
 189 protected:
 190         boost::shared_ptr<Pannable> _pannable;
 191
 192         virtual void distribute_one (AudioBuffer&, BufferSet& obufs, gain_t gain_coeff, pframes_t nframes, uint32_t which) = 0;
 193         virtual void distribute_one_automated (AudioBuffer&, BufferSet& obufs,
 194                                                framepos_t start, framepos_t end, pframes_t nframes,
 195                                                pan_t** buffers, uint32_t which) = 0;
 196
 197         int32_t _frozen;
 198 };
 199
 200 } // namespace
 201
 202 extern "C" {
 203 struct PanPluginDescriptor {
 204         std::string name;
 205         int32_t in;
 206         int32_t out;
 207         ARDOUR::Panner* (*factory)(boost::shared_ptr<ARDOUR::Pannable>, boost::shared_ptr<ARDOUR::Speakers>);
 208 };
 209 }
 210
 211 #endif /* __ardour_panner_h__ */