port_engine.h

Go to the documentation of this file.

/*
 * Copyright (C) 2013-2018 Paul Davis <paul@linuxaudiosystems.com>
 * Copyright (C) 2015-2018 Robin Gareus <robin@gareus.org>
 *
 * 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.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */
 
#pragma once
 
#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 ProtoPort {
  public:
        ProtoPort() {}
        virtual ~ProtoPort () {}
};
 
class LIBARDOUR_API PortEngine
{
public:
        PortEngine (PortManager& pm) : manager (pm) {}
        virtual ~PortEngine() {}
 
        virtual void* private_handle() const = 0;
 
        typedef std::shared_ptr<ProtoPort> PortPtr;
 
        /* We use this to declare arguments to methods/functions, in order to
         * avoid copying shared_ptr<ProtoPort> every time (a practice we use in
         * other contexts where we pass shared_ptr<T>). 
         */
        typedef PortPtr const & PortHandle;
 
        virtual const std::string& my_name() 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 port) const = 0;
 
        virtual PortFlags get_port_flags (PortHandle port) const = 0;
 
        virtual int get_port_property (PortHandle, const std::string& key, std::string& value, std::string& type) const { return -1; }
 
        virtual int set_port_property (PortHandle, const std::string& key, const std::string& value, const std::string& type) { return -1; }
 
        virtual PortPtr get_port_by_name (const std::string& name) 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 PortPtr register_port (const std::string& shortname, ARDOUR::DataType type, ARDOUR::PortFlags flags) = 0;
 
        /* Destroy the port referred to by \p port, including all resources
         * associated with it. This will also disconnect \p port from any ports it
         * is connected to.
         *
         * @param port \ref PortHandle of the port to destroy
         */
        virtual void    unregister_port (PortHandle port) = 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 port, const std::string& name, bool process_callback_safe = true) = 0;
 
        virtual bool  physically_connected (PortHandle port, bool process_callback_safe = true) = 0;
 
        virtual bool  externally_connected (PortHandle port, bool process_callback_safe = true) {
                /* only with JACK, provides client ports that are not physical */
                return physically_connected (port, process_callback_safe);
        }
 
        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 const** 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 \p port to be on or off, depending on the true/false
         * status of \p yn. The request count is ignored when using this
         * method, so if this is called with \p yn set to false, input monitoring will
         * be disabled regardless of the number of requests to enable it.
         *
         * @param port \ref PortHandle
         * @param yn true to enable hardware monitoring, false to disable
         * @return 0 on success, -1 otherwise
         */
        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 port, pframes_t off) = 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 samplepos_t sample_time_at_cycle_start () = 0;
 
protected:
        PortManager& manager;
};
 
} // namespace