document PortEngine API

1 files changed, 190 insertions, 25 deletions

diff --git a/libs/ardour/ardour/port_engine.h b/libs/ardour/ardour/port_engine.h
index f03a8e263f..8e36ad8b09 100644
--- a/libs/ardour/ardour/port_engine.h
+++ b/libs/ardour/ardour/port_engine.h
@@ -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;
+
+    /** 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;
 
-    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;
+    /** 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;