port_engine.h

Go to the documentation of this file.

/*
    Copyright (C) 2013 Paul Davis

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

*/

#ifndef __libardour_port_engine_h__
#define __libardour_port_engine_h__

#include <vector>
#include <string>

#include <stdint.h>

#include "ardour/data_type.h"
#include "ardour/libardour_visibility.h"
#include "ardour/types.h"

namespace ARDOUR {

class PortManager;

class LIBARDOUR_API PortEngine {
  public:
    PortEngine (PortManager& pm) : manager (pm) {}
    virtual ~PortEngine() {}
    
    virtual void* private_handle() const = 0;

    /* We use void* here so that the API can be defined for any implementation.
     * 
     * We could theoretically use a template (PortEngine<T>) and define
     * PortHandle as T, but this complicates the desired inheritance
     * pattern in which FooPortEngine handles things for the Foo API,
     * rather than being a derivative of PortEngine<Foo>.
    */
       
    typedef void* PortHandle;

    virtual const std::string& my_name() const = 0;
 
    virtual bool available() const = 0;

    virtual uint32_t port_name_size() const = 0;

    virtual int         set_port_name (PortHandle port, const std::string& name) = 0;
    virtual std::string get_port_name (PortHandle) const = 0;

    virtual int get_port_property (PortHandle, const std::string& key, std::string& value, std::string& type) const { return -1; }

    virtual PortHandle get_port_by_name (const std::string&) const = 0;

    virtual int get_ports (const std::string& port_name_pattern, DataType type, PortFlags flags, std::vector<std::string>& ports) const = 0;

    virtual DataType port_data_type (PortHandle port) const = 0;

    virtual PortHandle register_port (const std::string& shortname, ARDOUR::DataType type, ARDOUR::PortFlags flags) = 0;

    /* Destroy the port referred to by @param port, including all resources
     * associated with it. This will also disconnect @param port from any ports it
     * is connected to.
     */
    virtual void       unregister_port (PortHandle) = 0;
    
    /* Connection management */

    virtual int   connect (const std::string& src, const std::string& dst) = 0;

    virtual int   disconnect (const std::string& src, const std::string& dst) = 0;
    
    
    virtual int   connect (PortHandle src, const std::string& dst) = 0;
    virtual int   disconnect (PortHandle src, const std::string& dst) = 0;

    virtual int   disconnect_all (PortHandle port) = 0;

    virtual bool  connected (PortHandle port, bool process_callback_safe = true) = 0;
    virtual bool  connected_to (PortHandle, const std::string& name, bool process_callback_safe = true) = 0;

    virtual bool  physically_connected (PortHandle port, bool process_callback_safe = true) = 0;

    virtual int   get_connections (PortHandle port, std::vector<std::string>& names, bool process_callback_safe = true) = 0;

    /* MIDI */

    virtual int      midi_event_get (pframes_t& timestamp, size_t& size, uint8_t** buf, void* port_buffer, uint32_t event_index) = 0;

    virtual int      midi_event_put (void* port_buffer, pframes_t timestamp, const uint8_t* buffer, size_t size) = 0;

    virtual uint32_t get_midi_event_count (void* port_buffer) = 0;

    virtual void     midi_clear (void* port_buffer) = 0;

    /* Monitoring */

    virtual bool  can_monitor_input() const = 0;
    virtual int   request_input_monitoring (PortHandle port, bool yn) = 0;
    /* Force input monitoring of the hardware channel represented by the port
     * referred to by @param port to be on or off, depending on the true/false
     * status of @param yn. The request count is ignored when using this
     * method, so if this is called with yn set to false, input monitoring will
     * be disabled regardless of the number of requests to enable it.
    */
    virtual int   ensure_input_monitoring (PortHandle port, bool yn) = 0;
    virtual bool  monitoring_input (PortHandle port) = 0;

    /* Latency management
     */
    
    virtual void          set_latency_range (PortHandle port, bool for_playback, LatencyRange r) = 0;
    virtual LatencyRange  get_latency_range (PortHandle port, bool for_playback) = 0;

    /* Discovering physical ports */

    virtual bool      port_is_physical (PortHandle port) const = 0;

    virtual void      get_physical_outputs (DataType type, std::vector<std::string>& names) = 0;
    virtual void      get_physical_inputs (DataType type, std::vector<std::string>& names) = 0;
    virtual ChanCount n_physical_outputs () const = 0;
    virtual ChanCount n_physical_inputs () const = 0;

    virtual void* get_buffer (PortHandle, pframes_t) = 0;

    /* MIDI ports (the ones in libmidi++) need this to be able to correctly
     * schedule MIDI events within their buffers. It is a bit odd that we
     * expose this here, because it is also exposed by AudioBackend, but they
     * only have access to a PortEngine object, not an AudioBackend.
     * 
     * Return the time according to the sample clock in use when the current 
     * buffer process cycle began. 
     *
     * XXX to be removed after some more design cleanup. 
     */
    virtual framepos_t sample_time_at_cycle_start () = 0;

  protected:
    PortManager& manager;
};

}

#endif /* __libardour_port_engine_h__ */