#include <port_engine.h>

Inheritance diagram for ARDOUR::PortEngine:

Public Types
typedef void *	PortHandle

Public Member Functions
	PortEngine (PortManager &pm)

virtual	~PortEngine ()

virtual void *	private_handle () const =0

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

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

virtual void	unregister_port (PortHandle)=0

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

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

virtual bool	can_monitor_input () const =0

virtual int	request_input_monitoring (PortHandle port, bool yn)=0

virtual int	ensure_input_monitoring (PortHandle port, bool yn)=0

virtual bool	monitoring_input (PortHandle port)=0

virtual void	set_latency_range (PortHandle port, bool for_playback, LatencyRange r)=0

virtual LatencyRange	get_latency_range (PortHandle port, bool for_playback)=0

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

virtual framepos_t	sample_time_at_cycle_start ()=0

Protected Attributes
PortManager &	manager

Detailed Description

PortEngine is an abstract base class that defines the functionality required by Ardour.

A Port is basically an endpoint for a datastream (which can either be continuous, like audio, or event-based, like MIDI). Ports have buffers associated with them into which data can be written (if they are output ports) and from which data can be read (if they input ports). Ports can be connected together so that data written to an output port can be read from an input port. These connections can be 1:1, 1:N OR N:1.

Ports may be associated with software only, or with hardware. Hardware related ports are often referred to as physical, and correspond to some relevant physical entity on a hardware device, such as an audio jack or a MIDI connector. Physical ports may be potentially asked to monitor their inputs, though some implementations may not support this.

Most physical ports will also be considered "terminal", which means that data delivered there or read from there will go to or comes from a system outside of the PortEngine implementation's control (e.g. the analog domain for audio, or external MIDI devices for MIDI). Non-physical ports can also be considered "terminal". For example, the output port of a software synthesizer is a terminal port, because the data contained in its buffer does not and cannot be considered to come from any other port - it is synthesized by its owner.

Ports also have latency associated with them. Each port has a playback latency and a capture latency:

capture latency: how long since the data read from the buffer of a port arrived at at a terminal port. The data will have come from the "outside world" if the terminal port is also physical, or will have been synthesized by the entity that owns the terminal port.

playback latency: how long until the data written to the buffer of port will reach a terminal port.

For more detailed questions about the PortEngine API, consult the JACK API documentation, on which this entire object is based.

Definition at line 78 of file port_engine.h.

Member Typedef Documentation

typedef void* ARDOUR::PortEngine::PortHandle

Definition at line 96 of file port_engine.h.

Constructor & Destructor Documentation

ARDOUR::PortEngine::PortEngine ( PortManager & pm )

inline

Definition at line 80 of file port_engine.h.

virtual ARDOUR::PortEngine::~PortEngine ( )

inlinevirtual

Definition at line 81 of file port_engine.h.

Member Function Documentation

virtual bool ARDOUR::PortEngine::available ( ) const

pure virtual

Return true if the underlying mechanism/API is still available for us to utilize. return false if some or all of the AudioBackend API can no longer be effectively used.

virtual bool ARDOUR::PortEngine::can_monitor_input ( ) const

pure virtual

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 int ARDOUR::PortEngine::connect	(	const std::string &	src,
		const std::string &	dst
	)

pure virtual

Ensure that data written to the port named by

Parameters

src	will be readable from the port named by
dst.	Return zero on success, non-zero otherwise.

virtual int ARDOUR::PortEngine::connect	(	PortHandle	src,
		const std::string &	dst
	)

pure virtual

Ensure that data written to the port referenced by

Parameters

portwill	be readable from the port named by
dst.	Return zero on success, non-zero otherwise.

virtual bool ARDOUR::PortEngine::connected	(	PortHandle	port,
		bool	process_callback_safe = `true`
	)

pure virtual

Return true if the port referred to by

Parameters

port	has any connections to other ports. Return false otherwise.

virtual bool ARDOUR::PortEngine::connected_to	(	PortHandle	,
		const std::string &	name,
		bool	process_callback_safe = `true`
	)

pure virtual

Return true if the port referred to by

Parameters

port	is connected to the port named by
name.	Return false otherwise.

virtual int ARDOUR::PortEngine::disconnect	(	const std::string &	src,
		const std::string &	dst
	)

pure virtual

Remove any existing connection between the ports named by

Parameters

src	and
dst.	Return zero on success, non-zero otherwise.

virtual int ARDOUR::PortEngine::disconnect	(	PortHandle	src,
		const std::string &	dst
	)

pure virtual

Remove any existing connection between the port referenced by

Parameters

src	and the port named
dst.	Return zero on success, non-zero otherwise.

virtual int ARDOUR::PortEngine::disconnect_all ( PortHandle port )

pure virtual

Remove all connections between the port referred to by

Parameters

port	and any other ports. Return zero on success, non-zero otherwise.

virtual int ARDOUR::PortEngine::ensure_input_monitoring	(	PortHandle	port,
		bool	yn
	)

pure virtual

virtual void* ARDOUR::PortEngine::get_buffer	(	PortHandle	,
		pframes_t
	)

pure virtual

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 int ARDOUR::PortEngine::get_connections	(	PortHandle	port,
		std::vector< std::string > &	names,
		bool	process_callback_safe = `true`
	)

pure virtual

Place the names of all ports connected to the port named by

Parameters

ports	into
names,and	return the number of connections.

virtual LatencyRange ARDOUR::PortEngine::get_latency_range	(	PortHandle	port,
		bool	for_playback
	)

pure virtual

Return the latency range for the port referred to by

Parameters

port.	The playback range will be returned if
for_playback	is true, otherwise the capture range will be returned.

virtual uint32_t ARDOUR::PortEngine::get_midi_event_count ( void * port_buffer )

pure virtual

Return the number of MIDI events in the data at

Parameters

port_buffer

virtual void ARDOUR::PortEngine::get_physical_inputs	(	DataType	type,
		std::vector< std::string > &	names
	)

pure virtual

Store into

Parameters

names	the names of all ports with the IsInput and IsPhysical flags set, that handle data of type
type.	This can be used to discover inputs associated with hardware devices.

virtual void ARDOUR::PortEngine::get_physical_outputs	(	DataType	type,
		std::vector< std::string > &	names
	)

pure virtual

Store into

Parameters

names	the names of all ports with the IsOutput and IsPhysical flag set, that handle data of type
type.	This can be used to discover outputs associated with hardware devices.

virtual PortHandle ARDOUR::PortEngine::get_port_by_name ( const std::string & ) const

pure virtual

Return a reference to a port with the fullname

Parameters

name. Return an "empty" PortHandle (analogous to a null pointer) if no such port exists.

virtual std::string ARDOUR::PortEngine::get_port_name ( PortHandle ) const

pure virtual

Return the name of the port referred to by

Parameters

port. If the port does not exist, return an empty string.

virtual int ARDOUR::PortEngine::get_port_property	(	PortHandle	,
		const std::string &	key,
		std::string &	value,
		std::string &	type
	)		const

inlinevirtual

Return the port-property value and type for a given key. (eg query a human readable port name)

The API follows jack_get_property():

Parameters

key	The key of the property to retrieve
value	Set to the value of the property if found
type	The type of the property if set ( Type of data, either a MIME type or URI. If type is empty, the data is assumed to be a UTF-8 encoded string.

Returns: 0 on success, -1 if the subject has no key property.

for available keys, see https://github.com/jackaudio/headers/blob/master/metadata.h https://github.com/drobilla/jackey/blob/master/jackey.h

Definition at line 139 of file port_engine.h.

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

pure virtual

Find the set of ports whose names, types and flags match specified values, place the names of each port into

Parameters

ports,and return the count of the number found.

To avoid selecting by name, pass an empty string for

Parameters

port_name_pattern.	To avoid selecting by type, pass DataType::NIL as
type.	To avoid selecting by flags, pass PortFlags (0) as
flags.

virtual void ARDOUR::PortEngine::midi_clear ( void * port_buffer )

pure virtual

Clear the buffer at

Parameters

port_buffer of all MIDI events.

After a call to this method, an immediate, subsequent call to get_midi_event_count() with the same

Parameters

port_buffer argument must return zero.

virtual int ARDOUR::PortEngine::midi_event_get	(	pframes_t &	timestamp,
		size_t &	size,
		uint8_t **	buf,
		void *	port_buffer,
		uint32_t	event_index
	)

pure virtual

Retrieve a MIDI event from the data at

Parameters

port_buffer.	The event number to be retrieved is given by
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

Parameters

buf	and the number of bytes written will be stored in
size.	The timestamp of the event (which is always relative to the start of the current process cycle, in samples) will be stored in
timestamp

virtual int ARDOUR::PortEngine::midi_event_put	(	void *	port_buffer,
		pframes_t	timestamp,
		const uint8_t *	buffer,
		size_t	size
	)

pure virtual

Place a MIDI event consisting of

Parameters

size	bytes copied from the data at
buf	into the port buffer referred to by
port_buffer.	The MIDI event will be marked with a time given by
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 bool ARDOUR::PortEngine::monitoring_input ( PortHandle port )

pure virtual

Return true if input monitoring is enabled for the hardware channel represented by the port referred to by

Parameters

port. Return false otherwise.

virtual const std::string& ARDOUR::PortEngine::my_name ( ) const

pure virtual

Return the name of this process as used by the port manager when naming ports.

virtual ChanCount ARDOUR::PortEngine::n_physical_inputs ( ) const

pure virtual

Return the total count (possibly mixed between different data types) of the number of ports with the IsPhysical and IsInput flags set.

virtual ChanCount ARDOUR::PortEngine::n_physical_outputs ( ) const

pure virtual

Return the total count (possibly mixed between different data types) of the number of ports with the IsPhysical and IsOutput flags set.

virtual bool ARDOUR::PortEngine::physically_connected	(	PortHandle	port,
		bool	process_callback_safe = `true`
	)

pure virtual

Return true if the port referred to by

Parameters

port	has any connections to ports marked with the PortFlag IsPhysical. Return false otherwise.

virtual DataType ARDOUR::PortEngine::port_data_type ( PortHandle port ) const

pure virtual

Return the Ardour data type handled by the port referred to by

Parameters

port. Returns DataType::NIL if the port does not exist.

virtual bool ARDOUR::PortEngine::port_is_physical ( PortHandle port ) const

pure virtual

Return true if the port referred to by

Parameters

port	has the IsPhysical flag set. Return false otherwise.

virtual uint32_t ARDOUR::PortEngine::port_name_size ( ) const

pure virtual

Return the maximum size of a port name

virtual void* ARDOUR::PortEngine::private_handle ( ) const

pure virtual

Return a private, type-free pointer to any data that might be useful to a concrete implementation

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

pure virtual

Create a new port whose fullname will be the conjuction of my_name(), ":" and

Parameters

shortname.	The port will handle data specified by
type	and will have the flags given by
flags.	If successfull, return a reference to the port, otherwise return a null pointer.

virtual int ARDOUR::PortEngine::request_input_monitoring	(	PortHandle	port,
		bool	yn
	)

pure virtual

Increment or decrement the number of requests to monitor the input of the hardware channel represented by the port referred to by

Parameters

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 framepos_t ARDOUR::PortEngine::sample_time_at_cycle_start ( )

pure virtual

Implemented in ARDOUR::AudioBackend.

virtual void ARDOUR::PortEngine::set_latency_range	(	PortHandle	port,
		bool	for_playback,
		LatencyRange	r
	)

pure virtual

Set the latency range for the port referred to by

Parameters

port	to
r.	The playback range will be set if
for_playback	is true, otherwise the capture range will be set.

virtual int ARDOUR::PortEngine::set_port_name	(	PortHandle	port,
		const std::string &	name
	)

pure virtual

Returns zero if the port referred to by

Parameters

port	was set to
name.	Return non-zero otherwise.

virtual void ARDOUR::PortEngine::unregister_port ( PortHandle )

pure virtual

Member Data Documentation

PortManager& ARDOUR::PortEngine::manager

protected

Definition at line 361 of file port_engine.h.

The documentation for this class was generated from the following file:

/usr/local/music/src/ardour/4.0/libs/ardour/ardour/port_engine.h

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation