smokephil/ardour
1
0
Fork 0
mirror of https://github.com/Ardour/ardour.git synced 2025-12-06 06:44:57 +01:00
Code Issues Projects Releases Wiki Activity

Fix a few hundred doxygen warnings..

Browse source 
There are still over a hundred left, but this addresses many already.
In particular @param references to undocumented parameters.
Most notably in audio_backend.h
This commit is contained in:
Robin Gareus 2019-09-30 04:45:59 +02:00
parent f04092c0b1
commit 959a37144b
No known key found for this signature in database
GPG key ID: A090BCE02CF57F04
11 changed files with 336 additions and 206 deletions
Download patch file Download diff file Expand all files Collapse all files

69
libs/ardour/ardour/audio_backend.h
View file

@ -175,13 +175,13 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
*/
virtual std::vector<std::string> enumerate_drivers() const { return std::vector<std::string>(); }
/** Returns zero if the backend can successfully use @param name as the
* driver, non-zero otherwise.
/** Returns zero if the backend can successfully use \param drivername
* as the driver, non-zero otherwise.
*
* Should not be used unless the backend returns true from
* requires_driver_selection()
*/
virtual int set_driver (const std::string& /*drivername*/) { return 0; }
virtual int set_driver (const std::string& drivername) { return 0; }
/** used to list device names along with whether or not they are currently
* available.
@ -288,7 +288,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
virtual bool get_use_buffered_io () { return false; }
/** Returns a collection of float identifying sample rates that are
* potentially usable with the hardware identified by @param device.
* potentially usable with the hardware identified by \param device .
* Any of these values may be supplied in other calls to this backend
* as the desired sample rate to use with the name device, but the
* requested sample rate may turn out to be unavailable, or become invalid
@ -296,7 +296,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
*/
virtual std::vector<float> available_sample_rates (const std::string& device) const = 0;
/* backends that support separate input and output devices should
/* backends that suppor586t separate input and output devices should
* implement this function and return an intersection (not union) of available
* sample rates valid for the given input + output device combination.
*/
@ -321,7 +321,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
}
/** Returns a collection of uint32 identifying buffer sizes that are
* potentially usable with the hardware identified by @param device.
* potentially usable with the hardware identified by \param device .
* Any of these values may be supplied in other calls to this backend
* as the desired buffer size to use with the name device, but the
* requested buffer size may turn out to be unavailable, or become invalid
@ -353,7 +353,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
}
/** Returns the maximum number of input channels that are potentially
* usable with the hardware identified by @param device. Any number from 1
* usable with the hardware identified by \param device . Any number from 1
* to the value returned may be supplied in other calls to this backend as
* the input channel count to use with the name device, but the requested
* count may turn out to be unavailable, or become invalid at any time.
@ -361,7 +361,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
virtual uint32_t available_input_channel_count (const std::string& device) const = 0;
/** Returns the maximum number of output channels that are potentially
* usable with the hardware identified by @param device. Any number from 1
* usable with the hardware identified by \param device . Any number from 1
* to the value returned may be supplied in other calls to this backend as
* the output channel count to use with the name device, but the requested
* count may turn out to be unavailable, or become invalid at any time.
@ -429,7 +429,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
*/
virtual int set_buffer_size (uint32_t) = 0;
/** Set the preferred underlying hardware data layout.
* If @param yn is true, then the hardware will interleave
* If \param yn is true, then the hardware will interleave
* samples for successive channels; otherwise, the hardware will store
* samples for a single channel contiguously.
*
@ -506,7 +506,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
*/
virtual std::vector<std::string> enumerate_midi_options () const = 0;
/* Request the use of the MIDI option named @param option, which
/* Request the use of the MIDI option named \param option, which
* should be one of the strings returned by enumerate_midi_options()
*
* @return zero if successful, non-zero otherwise
@ -534,8 +534,8 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
* the most recent calls to set_sample_rate() etc. etc.
*
* At some undetermined time after this function is successfully called,
* the backend will start calling the ::process_callback() method of
* the AudioEngine referenced by @param engine. These calls will
* the backend will start calling the process_callback method of
* the AudioEngine referenced by \ref engine. These calls will
* occur in a thread created by and/or under the control of the backend.
*
* @param for_latency_measurement if true, the device is being started
@ -546,9 +546,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
* Return zero if successful, negative values otherwise.
*
*
*
*
* Why is this non-virtual but ::_start() is virtual ?
* Why is this non-virtual but \ref _start() is virtual ?
* Virtual methods with default parameters create possible ambiguity
* because a derived class may implement the same method with a different
* type or value of default parameter.
@ -566,7 +564,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
/** Stop using the device currently in use.
*
* If the function is successfully called, no subsequent calls to the
* process_callback() of @param engine will be made after the function
* process_callback() of \ref engine will be made after the function
* returns, until parameters are reset and start() are called again.
*
* The backend is considered to be un-configured after a successful
@ -586,7 +584,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
virtual int reset_device() = 0;
/** While remaining connected to the device, and without changing its
* configuration, start (or stop) calling the process_callback() of @param engine
* configuration, start (or stop) calling the process_callback of the engine
* without waiting for the device. Once process_callback() has returned, it
* will be called again immediately, thus allowing for faster-than-realtime
* processing.
@ -595,11 +593,12 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
* unaltered. However, any physical ports should NOT be used by the
* process_callback() during freewheeling - the data behaviour is undefined.
*
* If @param start_stop is true, begin this behaviour; otherwise cease this
* If \param start_stop is true, begin this behaviour; otherwise cease this
* behaviour if it currently occuring, and return to calling
* process_callback() of @param engine by waiting for the device.
* process_callback() of the engine by waiting for the device.
*
* Return zero on success, non-zero otherwise.
* @param start_stop true to engage freewheel processing
* @return zero on success, non-zero otherwise.
*/
virtual int freewheel (bool start_stop) = 0;
@ -613,11 +612,11 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
* Implementations can feel free to smooth the values returned over
* time (e.g. high pass filtering, or its equivalent).
*/
virtual float dsp_load() const = 0;
virtual float dsp_load() const = 0;
/* Transport Control (JACK is the only audio API that currently offers
the concept of shared transport control)
*/
* the concept of shared transport control)
*/
/** Attempt to change the transport state to TransportRolling.
*/
@ -628,15 +627,15 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
/** return the current transport state
*/
virtual TransportState transport_state () const { return TransportStopped; }
/** Attempt to locate the transport to @param pos
/** Attempt to locate the transport to \param pos
*/
virtual void transport_locate (samplepos_t /*pos*/) {}
virtual void transport_locate (samplepos_t pos) {}
/** Return the current transport location, in samples measured
* from the origin (defined by the transport time master)
*/
virtual samplepos_t transport_sample() const { return 0; }
/** If @param yn is true, become the time master for any inter-application transport
/** If \param yn is true, become the time master for any inter-application transport
* timebase, otherwise cease to be the time master for the same.
*
* Return zero on success, non-zero otherwise
@ -644,7 +643,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
* JACK is the only currently known audio API with the concept of a shared
* transport timebase.
*/
virtual int set_time_master (bool /*yn*/) { return 0; }
virtual int set_time_master (bool yn) { return 0; }
virtual int usecs_per_cycle () const { return 1000000 * (buffer_size() / sample_rate()); }
virtual size_t raw_buffer_size (DataType t) = 0;
@ -680,11 +679,11 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
/** Return true if it possible to determine the offset in samples of the
* first video frame that starts within the current buffer process cycle,
* measured from the first sample of the cycle. If returning true,
* set @param offset to that offset.
* set \param offset to that offset.
*
* Eg. if it can be determined that the first video frame within the cycle
* starts 28 samples after the first sample of the cycle, then this method
* should return true and set @param offset to 28.
* should return true and set \param offset to 28.
*
* May be impossible to support outside of JACK, which has specific support
* (in some cases, hardware support) for this feature.
@ -692,13 +691,15 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
* Can ONLY be called from within a process() callback tree (which implies
* that it can only be called by a process thread)
*/
virtual bool get_sync_offset (pframes_t& /*offset*/) const { return false; }
virtual bool get_sync_offset (pframes_t& offset) const { return false; }
/** Create a new thread suitable for running part of the buffer process
* cycle (i.e. Realtime scheduling, memory allocation, etc. etc are all
* correctly setup), with a stack size given in bytes by specified @param
* stacksize. The thread will begin executing @param func, and will exit
* cycle (i.e. Realtime scheduling, memory allocation, stacksize, etc.
* are all correctly setup).
* The thread will begin executing func, and will exit
* when that function returns.
*
* @param func process function to run
*/
virtual int create_process_thread (boost::function<void()> func) = 0;
@ -722,7 +723,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
virtual void update_latencies () = 0;
/** Set @param speed and @param position to the current speed and position
/** Set \param speed and \param position to the current speed and position
* indicated by some transport sync signal. Return whether the current
* transport state is pending, or finalized.
*

33
libs/ardour/ardour/audio_buffer.h
View file

@ -38,7 +38,7 @@ public:
/** silence buffer
* @param len number of samples to clear
* @laram offset start offset
* @param offset start offset
*/
void silence (samplecnt_t len, samplecnt_t offset = 0);
@ -86,7 +86,7 @@ public:
_written = true;
}
/** Accumulate (add) @a len samples @a src starting at @a src_offset into self starting at @a dst_offset */
/** Accumulate (add) \param len samples from \param src starting at \param src_offset into self starting at \param dst_offset */
void merge_from (const Buffer& src, samplecnt_t len, sampleoffset_t dst_offset = 0, sampleoffset_t src_offset = 0)
{
const AudioBuffer* ab = dynamic_cast<const AudioBuffer*> (&src);
@ -94,7 +94,7 @@ public:
accumulate_from (*ab, len, dst_offset, src_offset);
}
/** Accumulate (add) @a len samples @a src starting at @a src_offset into self starting at @a dst_offset */
/** Accumulate (add) \param len samples from \param src starting at \param src_offset into self starting at \param dst_offset */
void accumulate_from (const AudioBuffer& src, samplecnt_t len, sampleoffset_t dst_offset = 0, sampleoffset_t src_offset = 0)
{
assert (_capacity > 0);
@ -111,7 +111,9 @@ public:
_written = true;
}
/** Accumulate (add) @a len samples @a src starting at @a src_offset into self starting at @a dst_offset */
/** Accumulate (add) \param len samples of \param src starting at \param src_offset into self
* starting at \param dst_offset
*/
void accumulate_from (const Sample* src, samplecnt_t len, sampleoffset_t dst_offset = 0, sampleoffset_t src_offset = 0)
{
assert (_capacity > 0);
@ -126,8 +128,9 @@ public:
_written = true;
}
/** Accumulate (add) @a len samples @a src starting at @a src_offset into self starting at @dst_offset
* scaling by @a gain_coeff */
/** Accumulate (add) \param len samples if \param src starting at \param src_offset into self
* starting at \param dst_offset scaling by \param gain_coeff
*/
void accumulate_with_gain_from (const AudioBuffer& src, samplecnt_t len, gain_t gain_coeff, sampleoffset_t dst_offset = 0, sampleoffset_t src_offset = 0)
{
assert (_capacity > 0);
@ -146,8 +149,9 @@ public:
_written = true;
}
/** Accumulate (add) @a len samples FROM THE START OF @a src into self
* scaling by @a gain_coeff */
/** Accumulate (add) \param len samples from the start of \param src_raw into self at \param dst_offset
* scaling by \param gain_coeff
*/
void accumulate_with_gain_from (const Sample* src_raw, samplecnt_t len, gain_t gain_coeff, sampleoffset_t dst_offset = 0)
{
assert (_capacity > 0);
@ -161,8 +165,9 @@ public:
_written = true;
}
/** Accumulate (add) @a len samples FROM THE START OF @a src into self
* scaling by @a gain_coeff */
/** Accumulate (add) \param len samples from the start of \param src into self at \param dst_offset
* using a linear gain ramp from \param initial to \param target .
*/
void accumulate_with_ramped_gain_from (const Sample* src, samplecnt_t len, gain_t initial, gain_t target, sampleoffset_t dst_offset = 0)
{
assert (_capacity > 0);
@ -184,7 +189,8 @@ public:
_written = true;
}
/** apply a fixed gain factor to the audio buffer
/** Apply a fixed gain factor to the audio buffer
*
* @param gain gain factor
* @param len number of samples to amplify
*/
@ -213,7 +219,7 @@ public:
_written = false;
}
/** Reallocate the buffer used internally to handle at least @nframes of data
/** Reallocate the buffer used internally to handle at least \param nframes of data
*
* Constructor MUST have been passed capacity!=0 or this will die (to prevent mem leaks).
*/
@ -232,7 +238,8 @@ public:
return _data + offset;
}
/** check buffer for silence
/** Check buffer for silence
*
* @param nframes number of samples to check
* @param n first non zero sample (if any)
* @return true if all samples are zero

7
libs/ardour/ardour/chan_count.h
View file

@ -58,12 +58,13 @@ public:
}
/** set channel count for given type
* @param type data type
* @param t data type
* @param count number of channels
*/
void set(DataType t, uint32_t count) { assert(t != DataType::NIL); _counts[t] = count; }
/** query channel count for given type
* @param type data type
* @param t data type
* @returns channel count for given type
*/
uint32_t get(DataType t) const { assert(t != DataType::NIL); return _counts[t]; }
@ -74,6 +75,7 @@ public:
* @returns number of audio channels
*/
inline uint32_t n_audio() const { return _counts[DataType::AUDIO]; }
/** set number of audio channels
* @param a number of audio channels
*/
@ -83,6 +85,7 @@ public:
* @returns number of midi channels
*/
inline uint32_t n_midi() const { return _counts[DataType::MIDI]; }
/** set number of audio channels
* @param m number of midi channels
*/

13
libs/ardour/ardour/chan_mapping.h
View file

@ -53,29 +53,30 @@ public:
* @param valid pointer to a boolean. If not NULL it is set to true if the mapping is found, and false otherwise.
* @returns first "from" that matches given "to"
*/
uint32_t get_src(DataType t, uint32_t to, bool* valid) const;
uint32_t get_src(DataType type, uint32_t to, bool* valid) const;
/** get buffer mapping for given data type and pin
* @param type data type
* @param from numeric source id
* @returns mapped buffer number (or ChanMapping::Invalid)
*/
uint32_t get (DataType t, uint32_t from) const { return get (t, from, NULL); }
uint32_t get (DataType type, uint32_t from) const { return get (type, from, NULL); }
/** set buffer mapping for given data type
* @param type data type
* @param from numeric source id
* @param to buffer
*/
void set(DataType t, uint32_t from, uint32_t to);
void offset_from(DataType t, int32_t delta);
void offset_to(DataType t, int32_t delta);
void set (DataType type, uint32_t from, uint32_t to);
void offset_from (DataType t, int32_t delta);
void offset_to (DataType t, int32_t delta);
/** remove mapping
* @param type data type
* @param from numeric source to remove from mapping
*/
void unset(DataType t, uint32_t from);
void unset(DataType type, uint32_t from);
/** Test mapping matrix for identity
* @param offset per data-type offset to take into account

19
libs/ardour/ardour/lv2_extensions.h
View file

@ -20,7 +20,7 @@
#include "lv2/lv2plug.in/ns/lv2core/lv2.h"
/**
@defgroup inlinedisplay Inline-Display
@defgroup lv2inlinedisplay Inline-Display
Support for displaying a miniaturized generic view
directly in the host's Mixer Window.
@ -80,7 +80,7 @@ typedef struct {
*/
/**
@defgroup automate Self-Automation
@defgroup lv2automate Self-Automation
Support for plugins to write automation data via Atom Events
@ -111,7 +111,7 @@ typedef struct {
*/
/**
@defgroup license License-Report
@defgroup lv2license License-Report
Allow for commercial LV2 to report their
licensing status.
@ -149,7 +149,7 @@ typedef struct _LV2_License_Interface {
*/
/**
@defgroup plugin provided bypass
@defgroup lv2bypass Plugin-provided bypass
A port with the designation "processing#enable" must
control a plugin's internal bypass mode.
@ -182,7 +182,7 @@ typedef struct _LV2_License_Interface {
/**
@defgroup plugin port/routing control
@defgroup lv2routing plugin port/routing control
This is a "feature" to simplify per port meta-data of
http://lv2plug.in/ns/ext/port-groups/port-groups.html#source
@ -204,7 +204,7 @@ typedef struct _LV2_License_Interface {
*/
/**
@defgroup midnam MIDI Naming
@defgroup lv2midnam MIDI Naming
@{
*/
@ -231,7 +231,7 @@ typedef struct {
* text which is a valid midnam desciption
* (or NULL in case of error).
*
* The midnam <Model> must be unique and
* The midnam \<Model\> must be unique and
* specific for the given plugin-instance.
*/
char* (*midnam)(LV2_Handle instance);
@ -253,7 +253,10 @@ typedef struct {
*/
/**
@defgroup bankpatch
@defgroup lv2bankpatch MIDI Bank/Patch Notifications
LV2 extension to allow a synth to inform a host about the
currentl used MIDI bank/program.
@{
*/

294
libs/ardour/ardour/port_engine.h
View file

@ -86,14 +86,15 @@ public:
*/
virtual void* private_handle() const = 0;
/* We use void* here so that the API can be defined for any implementation.
/** Opaque handle to use as reference for Ports
*
* We could theoretically use a template (PortEngine<T>) and define
* 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>.
* rather than being a derivative of PortEngine\<Foo\>.
*/
typedef void* PortHandle;
/** Return the name of this process as used by the port manager
@ -101,23 +102,32 @@ public:
*/
virtual const std::string& my_name() const = 0;
/** Return the maximum size of a port name
*/
/** Return the maximum size of a port name */
virtual uint32_t port_name_size() const = 0;
/** Returns zero if the port referred to by @param port was set to @param
* name. Return non-zero otherwise.
/** Set/rename port
*
* @param port \ref PortHandle to operate on
* @param name new name to use for this port
* @return zero if successful, 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 the flags of the port referred to by @param port. If the port
* does not exist, return PortFlags (0)
/** Query port name
*
* @param port \ref PortHandle
* @return the name of the port referred to by @param port . If the port
* does not exist, return an empty string.
*/
virtual PortFlags get_port_flags (PortHandle) const = 0;
virtual std::string get_port_name (PortHandle port) const = 0;
/** Query port-flags
*
* @param port \ref PortHandle
* @return the flags of the port referred to by \param port . If the port
* does not exist, return PortFlags (0)
*/
virtual PortFlags get_port_flags (PortHandle port) const = 0;
/** Return the port-property value and type for a given key.
* (eg query a human readable port name)
@ -149,132 +159,194 @@ public:
*/
virtual int set_port_property (PortHandle, const std::string& key, const std::string& value, const std::string& type) { return -1; }
/** Return a reference to a port with the fullname @param name. Return
* an "empty" PortHandle (analogous to a null pointer) if no such port exists.
/** Return a reference to a port with the fullname \param name .
*
* @param name Full port-name to lookup
* @return PortHandle if lookup was successful, or an "empty" PortHandle (analogous to a null pointer) if no such port exists.
*/
virtual PortHandle get_port_by_name (const std::string&) const = 0;
virtual PortHandle get_port_by_name (const std::string& name) const = 0;
/** 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.
* specified values, place the names of each port into \param ports .
*
* 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.
* @param port_name_pattern match by given pattern. To avoid selecting by name, pass an empty string.
* @param type filter by given type; pass DataType::NIL to match all types.
* @param flags filter by flags, pass PortFlags (0) to avoid selecting by flags.
* @return the count of the number found
*/
virtual int get_ports (const std::string& port_name_pattern, DataType type, PortFlags flags, std::vector<std::string>& ports) 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.
/** Lookup data type of a port
*
* @param port \ref PortHandle of the port to lookup.
* @return the Ardour data type handled by the port referred to by \param port .
* DataType::NIL is returned if the port does not exist.
*/
virtual DataType port_data_type (PortHandle port) 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.
/** Create a new port whose fullname will be the conjunction 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 successful,
*
* @param shortname Name of port to create
* @param type type of port to create
* @param flags flags of the port to create
* @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;
/* Destroy the port referred to by @param port, including all resources
* associated with it. This will also disconnect @param port from any ports it
/* 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.
*
* @param port \ref PortHandle of the port to destroy
*/
virtual void unregister_port (PortHandle) = 0;
virtual void unregister_port (PortHandle port) = 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.
/** Ensure that data written to the port named by \param src will be
* readable from the port named by \param dst
*
* @param src name of source port to connect
* @param dst name of destination (sink) port
* @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.
/** Remove any existing connection between the ports named by \param src and
* \param dst
*
* @param src name of source port to dis-connect to disconnect from
* @param dst name of destination (sink) port to disconnect
* @return zero on success, non-zero otherwise.
*/
virtual int disconnect (const std::string& src, const std::string& dst) = 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.
/** Ensure that data written to the port referenced by \param src will be
* readable from the port named by \param dst
*
* @param src \ref PortHandle of source port to connect
* @param dst \ref PortHandle of destination (sink) port
* @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.
/** Remove any existing connection between the port referenced by \param src and
* the port named \param dst
*
* @param src \ref PortHandle of source port to disconnect from
* @param dst \ref PortHandle of destination (sink) port to disconnect
* @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.
/** Remove all connections between the port referred to by \param port and
* any other ports.
*
* @param port \ref PortHandle of port to disconnect
* @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.
/** Test if given \param port is connected
*
* @param port \ref PortHandle of port to test
* @param process_callback_safe true if this method is not called from rt-context of backend callbacks
* @return true if the port referred to by \param port has any connections to other ports. Return false otherwise.
*/
virtual bool connected (PortHandle port, bool process_callback_safe = true) = 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, bool process_callback_safe = true) = 0;
/** Return true if the port referred to by @param port has any connections
* to ports marked with the PortFlag IsPhysical. Return false otherwise.
/** Test port connection
*
* @param port \ref PortHandle of source port to test
* @param name name of destination to test
* @param process_callback_safe true if this method is not called from rt-context of backend callbacks
* @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 port, const std::string& name, bool process_callback_safe = true) = 0;
/** Test if given \param port is is connected to physical I/O ports.
*
* @param port \ref PortHandle of source port to test
* @param process_callback_safe true if this method is not called from rt-context of backend callbacks
* @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, bool process_callback_safe = true) = 0;
/** Return true if the port referred to by @param port has any connections
* to external, not-ardour owned, ports.
/** Test if given \param port is has external connections.
*
* @param port \ref PortHandle of port to test
* @param process_callback_safe true if this method is not called from rt-context of backend callbacks
* @return true if the port referred to by \param port has any connections
* to external, not-ardour owned, ports.
*/
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);
}
/** Place the names of all ports connected to the port named by @param
* ports into @param names, and return the number of connections.
/** Place the names of all ports connected to the port named by
* \param port into \param names .
*
* @param port \ref PortHandle
* @param names array or returned port-names
* @param process_callback_safe true if this method is not called from rt-context of backend callbacks
* @return number of connections found
*/
virtual int get_connections (PortHandle port, std::vector<std::string>& names, bool process_callback_safe = true) = 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).
/** 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
* \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 .
*
* @param timestamp time in samples relative to the current cycle start
* @param size number of bytes read into \param buf
* @param buf raw MIDI data
* @param port_buffer the midi-port buffer
* @param event_index index of event to retrieve
* @return 0 on success, -1 otherwise
*/
virtual int midi_event_get (pframes_t& timestamp, size_t& size, uint8_t const** 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.
/** Place a MIDI event consisting of \param size bytes copied from the data
* at \param buffer into the port buffer referred to by \param port_buffer .
* The MIDI event will be marked with a time given by \param timestamp .
*
* 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.
*
* @param port_buffer the midi-port buffer
* @param timestamp time in samples relative to the current cycle start
* @param buffer raw MIDI data to emplace
* @param size number of bytes of \param buffer
* @return zero on success, non-zero otherwise.
*/
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
/** Query the number of MIDI events in the data at \param port_buffer
*
* @param port_buffer the midi-port buffer
* @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.
/** 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
* \ref get_midi_event_count with the same \param port_buffer argument must
* return zero.
*
* @param port_buffer the buffer to clear
*/
virtual void midi_clear (void* port_buffer) = 0;
@ -289,67 +361,101 @@ public:
* APIs can offer it.
*/
virtual bool can_monitor_input() const = 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.
* 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)
*
* @param port \ref PortHandle
* @param yn true to enable hardware monitoring, false to disable
* @return 0 on success, -1 otherwise
*/
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
* 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 \param 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;
/** Return true if input monitoring is enabled for the hardware channel
* represented by the port referred to by @param port. Return false
* otherwise.
/** Query status of hardware monitoring for given \param port
*
* @param port \ref PortHandle to test
* @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 */
/** 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,
/** 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.
*
* @param port \ref PortHandle to operate on
* @param for_playback When true, playback latency is set: How long will it be
* until the signal arrives at the edge of the process graph.
* When false the capture latency is set: ow long has it been
* since the signal arrived at the edge of the process graph.
* @param r min/max latency for given port.
*/
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.
/** 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.
*
* @param port The PortHandle to query
* @param for_playback When true, playback (downstream) latency is queried,
* false for capture (upstream) latency.
*/
virtual LatencyRange get_latency_range (PortHandle port, bool for_playback) = 0;
/* Discovering physical ports */
/** Return true if the port referred to by @param port has the IsPhysical
/** Return true if the port referred to by \param port has the IsPhysical
* flag set. Return false otherwise.
*
* @param port \ref PortHandle to query
*/
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.
/** 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.
*
* @param type Data-type to lookup
* @param names return value to populate with names
*/
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.
* 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)
/** @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)
/** @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;
@ -360,8 +466,12 @@ public:
*
* The return value is untyped because buffers containing different data
* depending on the port type.
*
* @param port \ref PortHandle
* @param off memory offset
* @return pointer to raw memory area
*/
virtual void* get_buffer (PortHandle, pframes_t) = 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

2
libs/ardour/ardour/session.h
View file

@ -1992,7 +1992,7 @@ private:
static bool _disable_all_loaded_plugins;
static bool _bypass_all_loaded_plugins;
mutable bool have_looped; ///< Used in ::audible_sample(*)
mutable bool have_looped; ///< Used in \ref audible_sample
void update_route_record_state ();
gint _have_rec_enabled_track;

4
libs/libltc/ltc/ltc.h
View file

@ -430,8 +430,8 @@ int ltc_decoder_free(LTCDecoder *d);
*
* @param d decoder handle
* @param buf pointer to ltcsnd_sample_t - unsigned 8 bit mono audio data
* @param size \anchor size number of samples to parse
* @param posinfo (optional, recommended) sample-offset in the audio-stream. It is added to \ref off_start, \ref off_end in \ref LTCFrameExt and should be monotonic (ie incremented by \ref size for every call to ltc_decoder_write)
* @param size size number of samples to parse
* @param posinfo (optional, recommended) sample-offset in the audio-stream. It is added to \ref off_start, \ref off_end in \ref LTCFrameExt and should be monotonic (ie incremented by \param size for every call to ltc_decoder_write)
*/
void ltc_decoder_write(LTCDecoder *d,
ltcsnd_sample_t *buf, size_t size,

61
libs/pbd/pbd/controllable.h
View file

@ -52,6 +52,22 @@ namespace PBD {
* Without overriding upper() and lower(), a derived class will function
* as a control whose value can range between 0 and 1.0.
*
*
* We express Controllable values in one of three ways:
* 1. `user' --- as presented to the user (e.g. dB, Hz, etc.)
* 2. `interface' --- as used in some cases for the UI representation
* (in order to make controls behave logarithmically).
* 3. `internal' --- as passed to a processor, track, plugin, or whatever.
*
* Note that in some cases user and internal may be the same
* (and interface different) e.g. frequency, which is presented
* to the user and passed to the processor in linear terms, but
* which needs log scaling in the interface.
*
* In other cases, user and interface may be the same (and internal different)
* e.g. gain, which is presented to the user in log terms (dB)
* but passed to the processor as a linear quantity.
*/
class LIBPBD_API Controllable : public PBD::StatefulDestructible, public boost::enable_shared_from_this<Controllable>
{
@ -65,47 +81,34 @@ public:
Controllable (const std::string& name, Flag f = Flag (0));
/* We express Controllable values in one of three ways:
* 1. `user' --- as presented to the user (e.g. dB, Hz, etc.)
* 2. `interface' --- as used in some cases for the UI representation
* (in order to make controls behave logarithmically).
* 3. `internal' --- as passed to a processor, track, plugin, or whatever.
*
* Note that in some cases user and internal may be the same
* (and interface different) e.g. frequency, which is presented
* to the user and passed to the processor in linear terms, but
* which needs log scaling in the interface.
*
* In other cases, user and interface may be the same (and internal different)
* e.g. gain, which is presented to the user in log terms (dB)
* but passed to the processor as a linear quantity.
*/
/* Within an application, various Controllables might be considered to
/** Within an application, various Controllables might be considered to
* be "grouped" in a way that implies that setting 1 of them also
* modifies others in the group.
*/
enum GroupControlDisposition {
InverseGroup, /* set all controls in the same "group" as this one */
NoGroup, /* set only this control */
UseGroup, /* use group settings to decide which group controls are altered */
ForGroup /* this setting is being done *for* the group
(i.e. UseGroup was set in the callchain
somewhere).
*/
InverseGroup, /**< set all controls in the same "group" as this one */
NoGroup, /**< set only this control */
UseGroup, /**< use group settings to decide which group controls are altered */
ForGroup /**< this setting is being done *for* the group (i.e. UseGroup was set in the callchain somewhere). */
};
/** Get and Set `internal' value
/** Set `internal' value
*
* All derived classes must implement this.
*
* Basic derived classes will ignore @param group_override,
* Basic derived classes will ignore \param group_override
* but more sophisticated children, notably those that
* proxy the value setting logic via an object that is aware of group
* relationships between this control and others, will find it useful.
*
* @param value raw numeric value to set
* @param group_override if and how to propagate value to grouped controls
*/
virtual void set_value (double value, GroupControlDisposition group_override) = 0;
/** Get `internal' value
* @return raw value as used for the plugin/processor control port
*/
virtual void set_value (double, GroupControlDisposition group_override) = 0;
virtual double get_value (void) const = 0;
/** This is used when saving state. By default it just calls
@ -189,7 +192,7 @@ public:
IgnorableControllable () : PBD::Controllable ("ignoreMe") {}
~IgnorableControllable () {}
void set_value (double /*v*/, PBD::Controllable::GroupControlDisposition /* group_override */) {}
void set_value (double v, PBD::Controllable::GroupControlDisposition group_override) {}
double get_value () const { return 0.0; }
};

12
libs/pbd/pbd/crossthread.h
View file

@ -34,11 +34,11 @@
/** A simple abstraction of a mechanism of signalling one thread from another.
* The signaller calls ::wakeup() to tell the signalled thread to check for
* The signaller calls \ref wakeup() to tell the signalled thread to check for
* work to be done.
*
* This implementation provides both ::selectable() for use in direct
* poll/select-based event loops, and a Glib::IOSource via ::ios() for use
* This implementation provides both selectable() for use in direct
* poll/select-based event loops, and a Glib::IOSource via ios() for use
* in Glib main loop based situations.
*/
@ -56,7 +56,7 @@ public:
void wakeup();
/* if the listening thread cares about the precise message
* it is being sent, then ::deliver() can be used to send
* it is being sent, then \ref deliver() can be used to send
* a single byte message rather than a simple wakeup. These
* two mechanisms should not be used on the same CrossThreadChannel
* because there is no way to know which byte value will be used
@ -64,8 +64,8 @@ public:
*/
int deliver (char msg);
/** if using ::deliver() to wakeup the listening thread, then
* the listener should call ::receive() to fetch the message
/** if using \ref deliver() to wakeup the listening thread, then
* the listener should call \ref receive() to fetch the message
* type from the channel.
*
* wait = true only make sense for non_blocking channels,

28
libs/pbd/pbd/rcu.h
View file

@ -27,22 +27,24 @@
#include "pbd/libpbd_visibility.h"
/** @file Defines a set of classes to implement Read-Copy-Update. We do not attempt to define RCU here - use google.
The design consists of two parts: an RCUManager and an RCUWriter.
/** @file rcu.h
* Define a set of classes to implement Read-Copy-Update. We do not attempt to define RCU here - use google.
*
* The design consists of two parts: an RCUManager and an RCUWriter.
*/
/** An RCUManager is an object which takes over management of a pointer to another object.
It provides three key methods:
- reader() : obtains a shared pointer to the managed object that may be used for reading, without synchronization
- write_copy() : obtains a shared pointer to the object that may be used for writing/modification
- update() : accepts a shared pointer to a (presumed) modified instance of the object and causes all
future reader() and write_copy() calls to use that instance.
Any existing users of the value returned by reader() can continue to use their copy even as a write_copy()/update() takes place.
The RCU manager will manage the various instances of "the managed object" in a way that is transparent to users of the manager
and managed object.
*
* It provides three key methods:
*
* - reader() : obtains a shared pointer to the managed object that may be used for reading, without synchronization
* - write_copy() : obtains a shared pointer to the object that may be used for writing/modification
* - update() : accepts a shared pointer to a (presumed) modified instance of the object and causes all
* future reader() and write_copy() calls to use that instance.
*
* Any existing users of the value returned by reader() can continue to use their copy even as a write_copy()/update() takes place.
* The RCU manager will manage the various instances of "the managed object" in a way that is transparent to users of the manager
* and managed object.
*/
template<class T>
class /*LIBPBD_API*/ RCUManager