allanger/ardour
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Activity

document PortEngine API

Browse Source
This commit is contained in:
Paul Davis
2013-08-05 13:55:50 -04:00
parent a5f69910e4
commit 499b7fcfa9
1 changed files with 190 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
libs/ardour/ardour/port_engine.h
View File

@@ -89,73 +89,237 @@ class PortEngine {
typedef void* PortHandle;
/** Return a typeless pointer to an object that may be of interest
* that understands the internals of a particular PortEngine
* implementation.
*
* XXX the existence of this method is a band-aid over some design
* issues and will it will be removed in the future
*/
virtual void* private_handle() const = 0;
/** Return the name of this process as used by the port manager
* when naming ports.
*/
virtual const std::string& my_name() const = 0;
/** Return the maximum size of a port name
*/
virtual uint32_t port_name_size() const = 0;
virtual int set_port_name (PortHandle, const std::string&) = 0;
/** Returns zero if the port referred to by @param port was set to @param
* name. Return non-zero otherwise.
*/
virtual int set_port_name (PortHandle port, const std::string& name) = 0;
/** Return the name of the port referred to by @param port. If the port
* does not exist, return an empty string.
*/
virtual std::string get_port_name (PortHandle) const = 0;
/** Return a reference to a port with the fullname @param name. Return
* a null pointer if no such port exists.
*/
virtual PortHandle* get_port_by_name (const std::string&) const = 0;
/* Discovering the set of ports whose names, types and flags match
* specified values.
/** Find the set of ports whose names, types and flags match
* specified values, place the names of each port into @param ports,
* and return the count of the number found.
*
* To avoid selecting by name, pass an empty string for @param
* port_name_pattern.
*
* To avoid selecting by type, pass DataType::NIL as @param type.
*
* To avoid selecting by flags, pass PortFlags (0) as @param flags.
*/
virtual int get_ports (const std::string& port_name_pattern, DataType type, PortFlags flags, std::vector<std::string>& ports) const = 0;
virtual int get_ports (const std::string& port_name_pattern, DataType type, PortFlags flags, std::vector<std::string>&) const = 0;
/** Return the Ardour data type handled by the port referred to by @param
* port. Returns DataType::NIL if the port does not exist.
*/
virtual DataType port_data_type (PortHandle port) const = 0;
virtual DataType port_data_type (PortHandle) const = 0;
/** Create a new port whose fullname will be the conjuction of my_name(),
* ":" and @param shortname. The port will handle data specified by @param
* type and will have the flags given by @param flags. If successfull,
* return a reference to the port, otherwise return a null pointer.
*/
virtual PortHandle register_port (const std::string& shortname, ARDOUR::DataType type, ARDOUR::PortFlags flags) = 0;
virtual PortHandle register_port (const std::string& shortname, ARDOUR::DataType, ARDOUR::PortFlags) = 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 */
/** Ensure that data written to the port named by @param src will be
* readable from the port named by @param dst. Return zero on success,
* non-zero otherwise.
*/
virtual int connect (const std::string& src, const std::string& dst) = 0;
/** Remove any existing connection between the ports named by @param src and
* @param dst. Return zero on success, non-zero otherwise.
*/
virtual int disconnect (const std::string& src, const std::string& dst) = 0;
virtual int connect (PortHandle, const std::string&) = 0;
virtual int disconnect (PortHandle, const std::string&) = 0;
virtual int disconnect_all (PortHandle) = 0;
/** Ensure that data written to the port referenced by @param portwill be
* readable from the port named by @param dst. Return zero on success,
* non-zero otherwise.
*/
virtual int connect (PortHandle src, const std::string& dst) = 0;
/** Remove any existing connection between the port referenced by @param src and
* the port named @param dst. Return zero on success, non-zero otherwise.
*/
virtual int disconnect (PortHandle src, const std::string& dst) = 0;
virtual bool connected (PortHandle) = 0;
virtual bool connected_to (PortHandle, const std::string&) = 0;
virtual bool physically_connected (PortHandle) = 0;
virtual int get_connections (PortHandle, std::vector<std::string>&) = 0;
/** Remove all connections between the port referred to by @param port and
* any other ports. Return zero on success, non-zero otherwise.
*/
virtual int disconnect_all (PortHandle port) = 0;
/** Return true if the port referred to by @param port has any connections
* to other ports. Return false otherwise.
*/
virtual bool connected (PortHandle port) = 0;
/** Return true if the port referred to by @param port is connected to
* the port named by @param name. Return false otherwise.
*/
virtual bool connected_to (PortHandle, const std::string& name) = 0;
/** Return true if the port referred to by @param port has any connections
* to ports marked with the PortFlag IsPhysical. Return false otherwise.
*/
virtual bool physically_connected (PortHandle port) = 0;
/** Place the names of all ports connected to the port named by @param
* ports into @param names, and return the number of connections.
*/
virtual int get_connections (PortHandle port, std::vector<std::string>& names) = 0;
/* MIDI */
/** Retrieve a MIDI event from the data at @param port_buffer. The event
number to be retrieved is given by @param event_index (a value of zero
indicates that the first event in the port_buffer should be retrieved).
*
* The data associated with the event will be copied into the buffer at
* @param buf and the number of bytes written will be stored in @param
* size. The timestamp of the event (which is always relative to the start
* of the current process cycle, in samples) will be stored in @param
* timestamp
*/
virtual int midi_event_get (pframes_t& timestamp, size_t& size, uint8_t** buf, void* port_buffer, uint32_t event_index) = 0;
/** Place a MIDI event consisting of @param size bytes copied from the data
* at @param buf into the port buffer referred to by @param
* port_buffer. The MIDI event will be marked with a time given by @param
* timestamp. Return zero on success, non-zero otherwise.
*
* Events must be added monotonically to a port buffer. An attempt to
* add a non-monotonic event (e.g. out-of-order) will cause this method
* to return a failure status.
*/
virtual int midi_event_put (void* port_buffer, pframes_t timestamp, const uint8_t* buffer, size_t size) = 0;
/** Return the number of MIDI events in the data at @param port_buffer
*/
virtual uint32_t get_midi_event_count (void* port_buffer) = 0;
/** Clear the buffer at @param port_buffer of all MIDI events.
*
* After a call to this method, an immediate, subsequent call to
* get_midi_event_count() with the same @param port_buffer argument must
* return zero.
*/
virtual void midi_clear (void* port_buffer) = 0;
/* Monitoring */
/** Return true if the implementation can offer input monitoring.
*
* Input monitoring involves the (selective) routing of incoming data
* to an outgoing data stream, without the data being passed to the CPU.
*
* Only certain audio hardware can provide this, and only certain audio
* APIs can offer it.
*/
virtual bool can_monitor_input() const = 0;
virtual int request_input_monitoring (PortHandle, bool) = 0;
virtual int ensure_input_monitoring (PortHandle, bool) = 0;
virtual bool monitoring_input (PortHandle) = 0;
/** Increment or decrement the number of requests to monitor the input
* of the hardware channel represented by the port referred to by @param
* port.
*
* If the number of requests rises above zero, input monitoring will
* be enabled (if can_monitor_input() returns true for the implementation).
*
* If the number of requests falls to zero, input monitoring will be
* disabled (if can_monitor_input() returns true for the implementation)
*/
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;
/** Return true if input monitoring is enabled for the hardware channel
* represented by the port referred to by @param port. Return false
* otherwise.
*/
virtual bool monitoring_input (PortHandle port) = 0;
/* Latency management
*/
virtual void set_latency_range (PortHandle, bool for_playback, LatencyRange) = 0;
virtual LatencyRange get_latency_range (PortHandle, bool for_playback) = 0;
/** Set the latency range for the port referred to by @param port to @param
* r. The playback range will be set if @param for_playback is true,
* otherwise the capture range will be set.
*/
virtual void set_latency_range (PortHandle port, bool for_playback, LatencyRange r) = 0;
/** Return the latency range for the port referred to by @param port.
* The playback range will be returned if @param for_playback is true,
* otherwise the capture range will be returned.
*/
virtual LatencyRange get_latency_range (PortHandle port, bool for_playback) = 0;
/* Discovering physical ports */
virtual bool port_is_physical (PortHandle) const = 0;
virtual void get_physical_outputs (DataType type, std::vector<std::string>&) = 0;
virtual void get_physical_inputs (DataType type, std::vector<std::string>&) = 0;
/** Return true if the port referred to by @param port has the IsPhysical
* flag set. Return false otherwise.
*/
virtual bool port_is_physical (PortHandle port) const = 0;
/** Store into @param names the names of all ports with the IsOutput and
* IsPhysical flag set, that handle data of type @param type.
*
* This can be used to discover outputs associated with hardware devices.
*/
virtual void get_physical_outputs (DataType type, std::vector<std::string>& names) = 0;
/** Store into @param names the names of all ports with the IsInput and
* IsPhysical flags set, that handle data of type @param type.
*
* This can be used to discover inputs associated with hardware devices.
*/
virtual void get_physical_inputs (DataType type, std::vector<std::string>& names) = 0;
/** Return the total count (possibly mixed between different data types)
of the number of ports with the IsPhysical and IsOutput flags set.
*/
virtual ChanCount n_physical_outputs () const = 0;
/** Return the total count (possibly mixed between different data types)
of the number of ports with the IsPhysical and IsInput flags set.
*/
virtual ChanCount n_physical_inputs () const = 0;
/* getting the port buffer. untyped (void*) because this will return
* buffers containing different data depending on the port type
/** Return the address of the memory area where data for the port can be
* written (if the port has the PortFlag IsOutput set) or read (if the port
* has the PortFlag IsInput set).
*
* The return value is untyped because buffers containing different data
* depending on the port type.
*/
virtual void* get_buffer (PortHandle, pframes_t) = 0;
/* MIDI ports (the ones in libmidi++) need this to be able to correctly
@@ -165,7 +329,8 @@ class PortEngine {
*
* 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 pframes_t sample_time_at_cycle_start () = 0;