diff --git a/libs/ardour/ardour/bundle.h b/libs/ardour/ardour/bundle.h index 068c92c1f7..88f095dd33 100644 --- a/libs/ardour/ardour/bundle.h +++ b/libs/ardour/ardour/bundle.h @@ -77,10 +77,10 @@ class LIBARDOUR_API Bundle : public PBD::ScopedConnectionList ChanCount nchannels () const; uint32_t n_total () const; /* shortcut for nchannels().n_total() */ - /** @param Channel index. + /** @param c Channel index. * @return Ports associated with this channel. */ - PortList const & channel_ports (uint32_t) const; + PortList const & channel_ports (uint32_t c) const; void add_channel (std::string const &, DataType); void add_channel (std::string const &, DataType, std::string const &); diff --git a/libs/ardour/ardour/element_import_handler.h b/libs/ardour/ardour/element_import_handler.h index 6a7ea72531..98eda088a2 100644 --- a/libs/ardour/ardour/element_import_handler.h +++ b/libs/ardour/ardour/element_import_handler.h @@ -48,6 +48,7 @@ class LIBARDOUR_API ElementImportHandler * and create respective Elements stored in elements. * * @param source XML tree to be parsed + * @param session The Session * @see elements */ ElementImportHandler (XMLTree const & source, ARDOUR::Session & session) diff --git a/libs/ardour/ardour/meter.h b/libs/ardour/ardour/meter.h index 9e5fa9536e..332b05cc2d 100644 --- a/libs/ardour/ardour/meter.h +++ b/libs/ardour/ardour/meter.h @@ -91,7 +91,7 @@ private: /** The number of meters that we are currently handling; * may be different to _configured_input and _configured_output - * as it can be altered outside a ::configure_io by ::reflect_inputs. + * as it can be altered outside a \ref configure_io by \ref reflect_inputs . */ ChanCount current_meters; diff --git a/libs/ardour/ardour/midi_playlist.h b/libs/ardour/ardour/midi_playlist.h index f6e0c77b4d..82ec7b65e1 100644 --- a/libs/ardour/ardour/midi_playlist.h +++ b/libs/ardour/ardour/midi_playlist.h @@ -78,6 +78,7 @@ public: * @param chan_n Must be 0 (this is the audio-style "channel", where each * channel is backed by a separate region, not MIDI channels, which all * exist in the same region and are not handled here). + * @param filter Channel filter to apply or NULL to disable filter * @return The number of samples read (time, not an event count). */ samplecnt_t read (Evoral::EventSink& buf, diff --git a/libs/ardour/ardour/midi_source.h b/libs/ardour/ardour/midi_source.h index a08845639b..0334b95b06 100644 --- a/libs/ardour/ardour/midi_source.h +++ b/libs/ardour/ardour/midi_source.h @@ -56,12 +56,13 @@ class LIBARDOUR_API MidiSource : virtual public Source virtual ~MidiSource (); /** Write the data in the given time range to another MidiSource - * \param newsrc MidiSource to which data will be written. Should be a + * @param lock Reference to the Mutex to lock before modification + * @param newsrc MidiSource to which data will be written. Should be a * new, empty source. If it already has contents, the results are * undefined. Source must be writable. - * \param begin time of earliest event that can be written. - * \param end time of latest event that can be written. - * \return zero on success, non-zero if the write failed for any reason. + * @param begin time of earliest event that can be written. + * @param end time of latest event that can be written. + * @return zero on success, non-zero if the write failed for any reason. */ int write_to (const Lock& lock, boost::shared_ptr newsrc, @@ -69,12 +70,13 @@ class LIBARDOUR_API MidiSource : virtual public Source Temporal::Beats end = std::numeric_limits::max()); /** Export the midi data in the given time range to another MidiSource - * \param newsrc MidiSource to which data will be written. Should be a + * @param lock Reference to the Mutex to lock before modification + * @param newsrc MidiSource to which data will be written. Should be a * new, empty source. If it already has contents, the results are * undefined. Source must be writable. - * \param begin time of earliest event that can be written. - * \param end time of latest event that can be written. - * \return zero on success, non-zero if the write failed for any reason. + * @param begin time of earliest event that can be written. + * @param end time of latest event that can be written. + * @return zero on success, non-zero if the write failed for any reason. */ int export_write_to (const Lock& lock, boost::shared_ptr newsrc, @@ -83,13 +85,18 @@ class LIBARDOUR_API MidiSource : virtual public Source /** Read the data in a given time range from the MIDI source. * All time stamps in parameters are in audio samples (even if the source has tempo time). - * \param dst Ring buffer where read events are written. - * \param source_start Start position of the SOURCE in this read context. - * \param start Start of range to be read. - * \param cnt Length of range to be read (in audio samples). - * \param loop_range If non-null, all event times will be mapped into this loop range. - * \param tracker an optional pointer to MidiStateTracker object, for note on/off tracking. - * \param filtered Parameters whose MIDI messages will not be returned. + * @param lock Reference to the Mutex to lock before modification + * @param dst Ring buffer where read events are written. + * @param source_start Start position of the SOURCE in this read context. + * @param start Start of range to be read. + * @param cnt Length of range to be read (in audio samples). + * @param loop_range If non-null, all event times will be mapped into this loop range. + * @param cursor Cached iterator to start copying events + * @param filter Channel filter to apply or NULL to disable filter + * @param tracker an optional pointer to MidiStateTracker object, for note on/off tracking. + * @param filtered Parameters whose MIDI messages will not be returned. + * @param pos_beats Start position (quarter note = \p pos_beats - \p start_beats) + * @param start_beats Start position offset */ virtual samplecnt_t midi_read (const Lock& lock, Evoral::EventSink& dst, @@ -101,16 +108,17 @@ class LIBARDOUR_API MidiSource : virtual public Source MidiStateTracker* tracker, MidiChannelFilter* filter, const std::set& filtered, - const double pulse, + const double pos_beats, const double start_beats) const; /** Write data from a MidiRingBuffer to this source. - * @param source Source to read from. - * @param source_start This source's start position in session samples. - * @param cnt The length of time to write. + * @param lock Reference to the Mutex to lock before modification + * @param source Source to read from. + * @param source_start This source's start position in session samples. + * @param cnt The length of time to write. */ virtual samplecnt_t midi_write (const Lock& lock, - MidiRingBuffer& src, + MidiRingBuffer& source, samplepos_t source_start, samplecnt_t cnt); @@ -218,9 +226,10 @@ class LIBARDOUR_API MidiSource : virtual public Source MidiChannelFilter* filter) const = 0; /** Write data to this source from a MidiRingBuffer. - * @param source Buffer to read from. - * @param position This source's start position in session samples. - * @param cnt The duration of this block to write for. + * @param lock Reference to the Mutex to lock before modification + * @param source Buffer to read from. + * @param position This source's start position in session samples. + * @param cnt The duration of this block to write for. */ virtual samplecnt_t write_unlocked (const Lock& lock, MidiRingBuffer& source, diff --git a/libs/ardour/ardour/note_fixer.h b/libs/ardour/ardour/note_fixer.h index 6a0a2d6695..3e6fea6551 100644 --- a/libs/ardour/ardour/note_fixer.h +++ b/libs/ardour/ardour/note_fixer.h @@ -61,9 +61,11 @@ public: * are enqueued to compensate for edits which should be later sent with * emit() at the start of the next read. * + * @param tempo_map The tempo-map * @param cmd Command to compensate for. * @param origin Timeline position of edited source. * @param pos Current read position (last read end). + * @param active_notes currently active notes (read/write) */ void prepare(TempoMap& tempo_map, const MidiModel::NoteDiffCommand* cmd, diff --git a/libs/ardour/ardour/plugin.h b/libs/ardour/ardour/plugin.h index 9b35b75bf9..8433bf4447 100644 --- a/libs/ardour/ardour/plugin.h +++ b/libs/ardour/ardour/plugin.h @@ -211,7 +211,7 @@ class LIBARDOUR_API Plugin : public PBD::StatefulDestructible, public HasLatency /** Create a new plugin-preset from the current state * - * @param_name label to use for new preset (needs to be unique) + * @param name label to use for new preset (needs to be unique) * @return PresetRecord with empty URI on failure */ PresetRecord save_preset (std::string name); diff --git a/libs/ardour/ardour/region_factory.h b/libs/ardour/ardour/region_factory.h index 97a5400925..a3f61f8819 100644 --- a/libs/ardour/ardour/region_factory.h +++ b/libs/ardour/ardour/region_factory.h @@ -62,7 +62,7 @@ public: */ static PBD::Signal1 > CheckNewRegion; - /** create a "pure copy" of Region @param other */ + /** create a "pure copy" of Region \p other */ static boost::shared_ptr create (boost::shared_ptr other, bool announce = false, bool fork = false); static boost::shared_ptr create (boost::shared_ptr other, bool announce, bool fork) { return create (boost::shared_ptr(other), announce, fork); @@ -75,19 +75,19 @@ public: /** create a region from a multiple sources */ static boost::shared_ptr create (const SourceList &, const PBD::PropertyList&, bool announce = true); - /** create a copy of @other starting at zero within @param other's sources */ + /** create a copy of \p other starting at zero within \p other's sources */ static boost::shared_ptr create (boost::shared_ptr other, const PBD::PropertyList&, bool announce = true); - /** create a copy of @param other starting at @param offset within @param other */ + /** create a copy of \p other starting at \p offset within \p other */ static boost::shared_ptr create (boost::shared_ptr other, ARDOUR::MusicSample offset, const PBD::PropertyList&, bool announce = true); - /** create a "copy" of @param other but using a different set of sources @param srcs */ + /** create a "copy" of \p other but using a different set of sources \p srcs */ static boost::shared_ptr create (boost::shared_ptr other, const SourceList& srcs, const PBD::PropertyList&, bool announce = true); /** create a region with no sources, using XML state */ static boost::shared_ptr create (Session&, XMLNode&, bool); - /** create a region with specified sources @param srcs and XML state */ + /** create a region with specified sources \p srcs and XML state */ static boost::shared_ptr create (SourceList& srcs, const XMLNode&); static boost::shared_ptr get_whole_region_for_source (boost::shared_ptr); diff --git a/libs/ardour/ardour/session.h b/libs/ardour/ardour/session.h index 00e2439f61..ea0e4008db 100644 --- a/libs/ardour/ardour/session.h +++ b/libs/ardour/ardour/session.h @@ -265,9 +265,11 @@ public: std::string new_audio_source_path_for_embedded (const std::string& existing_path); std::string new_audio_source_path (const std::string&, uint32_t nchans, uint32_t chan, bool destructive, bool take_required); std::string new_midi_source_path (const std::string&, bool need_source_lock = true); + /** create a new track or bus from a template (XML path) * @param how_many how many tracks or busses to create * @param template_path path to xml template file + * @param insert_at position where to add new track, use PresentationInfo::max_order to append at the end. * @param name name (prefix) of the route to create * @param pd Playlist disposition * @return list of newly created routes @@ -539,6 +541,8 @@ public: * @param pending save a 'recovery', not full state (default: false) * @param switch_to_snapshot switch to given snapshot after saving (default: false) * @param template_only save a session template (default: false) + * @param for_archive save only data relevant for session-archive + * @param only_used_assets skip Sources that are not used, mainly useful with \p for_archive * @return zero on success */ int save_state (std::string snapshot_name, diff --git a/libs/ardour/ardour/transport_master.h b/libs/ardour/ardour/transport_master.h index 98c4f11156..cfeb2f894a 100644 --- a/libs/ardour/ardour/transport_master.h +++ b/libs/ardour/ardour/transport_master.h @@ -209,9 +209,12 @@ class LIBARDOUR_API TransportMaster : public PBD::Stateful { * * @param speed - The transport speed requested * @param position - The transport position requested + * @param lp last position (used for flywheel) + * @param when last timestamp (used for flywheel) + * @param now monotonic sample time * @return - The return value is currently ignored (see Session::follow_slave) */ - virtual bool speed_and_position (double& speed, samplepos_t& position, samplepos_t & lp, samplepos_t & when, samplepos_t now); + virtual bool speed_and_position (double& speed, samplepos_t& position, samplepos_t& lp, samplepos_t& when, samplepos_t now); virtual void reset (bool with_position) = 0; diff --git a/libs/canvas/canvas/canvas.h b/libs/canvas/canvas/canvas.h index b7060e60c0..7733f07a95 100644 --- a/libs/canvas/canvas/canvas.h +++ b/libs/canvas/canvas/canvas.h @@ -135,7 +135,7 @@ public: virtual Coord height () const = 0; /** Store the coordinates of the mouse pointer in window coordinates in - * @param winpos. Return true if the position was within the window, + * \p winpos . Return true if the position was within the window, * false otherwise. */ virtual bool get_mouse_position (Duple& winpos) const = 0; @@ -147,9 +147,9 @@ public: sigc::signal PreRender; - /** Ensures that the position given by @param winpos (in window + /** Ensures that the position given by \p winpos (in window * coordinates) is within the current window area, possibly reduced by - * @param border. + * \p border. */ Duple clamp_to_window (Duple const& winpos, Duple border = Duple()); diff --git a/libs/canvas/canvas/interpolated_curve.h b/libs/canvas/canvas/interpolated_curve.h index 2faf70dde6..3a8706a6bf 100644 --- a/libs/canvas/canvas/interpolated_curve.h +++ b/libs/canvas/canvas/interpolated_curve.h @@ -36,7 +36,7 @@ protected: /** * This method will calculate the Catmull-Rom interpolation curve, returning - * it as a list of Coord coordinate objects. This method in particular + * it as a list of Coord coordinate objects. This method in particular * adds the first and last control points which are not visible, but required * for calculating the spline. * @@ -47,6 +47,8 @@ protected: * point will depend on the spacing between the control points. * @return The list of interpolated coordinates. * @param curve_type Chordal (stiff), Uniform(floppy), or Centripetal(medium) + * @param closed Specify if the shape is open or closed + * @param results List of calculated coordinates * @throws gov.ca.water.shapelite.analysis.CatmullRomException if * points_per_segment is less than 2. */ @@ -176,7 +178,7 @@ private: * or centripetal curve types. Uniform can produce loops, chordal can * produce large distortions from the original lines, and centripetal is an * optimal balance without spaces. - * @return the list of coordinates that define the CatmullRom curve + * @param results List of calculated coordinates that define the CatmullRom curve * between the points defined by index+1 and index+2. */ static void diff --git a/libs/canvas/canvas/item.h b/libs/canvas/canvas/item.h index e71419e30c..d9d644abe1 100644 --- a/libs/canvas/canvas/item.h +++ b/libs/canvas/canvas/item.h @@ -83,22 +83,23 @@ public: */ virtual void prepare_for_render (Rect const & area) const { } - /** Adds one or more items to the vector @param items based on their - * covering @param point which is in **window** coordinates + /** Adds one or more items to the vector \p items based on their + * covering \p point which is in window coordinates * * Note that Item::add_items_at_window_point() is only intended to be * called on items already looked up in a LookupTable (i.e. by a - * parent) and thus known to cover @param point already. + * parent) and thus known to cover \p point already. * * Derived classes may add more items than themselves (e.g. containers). */ - virtual void add_items_at_point (Duple /*point*/, std::vector& items) const; + virtual void add_items_at_point (Duple point, std::vector& items) const; - /** Return true if the item covers @param point, false otherwise. + /** Test if point is inside the item * - * The point is in window coordinates + * @param point The point is in window coordinates + * @return true if the item covers \p point , false otherwise. */ - virtual bool covers (Duple const &) const; + virtual bool covers (Duple const& point) const; /** Update _bounding_box and _bounding_box_dirty */ virtual void compute_bounding_box () const = 0; @@ -118,13 +119,14 @@ public: const Item* closest_ancestor_with (const Item& other) const; bool common_ancestor_within (uint32_t, const Item& other) const; - /** returns true if this item is an ancestor of @param candidate, + /** returns true if this item is an ancestor of \p candidate , * and false otherwise. */ bool is_ancestor_of (const Item& candidate) const { return candidate.is_descendant_of (*this); } - /** returns true if this Item is a descendant of @param candidate, + + /** returns true if this Item is a descendant of \p candidate , * and false otherwise. */ bool is_descendant_of (const Item& candidate) const; diff --git a/libs/temporal/temporal/time.h b/libs/temporal/temporal/time.h index d75c232fe9..e527965d99 100644 --- a/libs/temporal/temporal/time.h +++ b/libs/temporal/temporal/time.h @@ -120,26 +120,46 @@ timecode_format_sampletime ( double sample_sample_rate, double timecode_frames_per_second, bool timecode_drop_frames); +/** Convert timecode (frames per second) to audio sample time (samples per second) + * + * @param timecode Timecode to convert (also includes frame-rate) + * @param sample returned corresponding audio sample time + * @param use_offset apply offset as given by \p offset_is_negative and \p offset_samples + * @param use_subframes use \p subframes_per_frame when converting + * @param sample_sample_rate target sample-rate, may include pull up/down + * @param subframes_per_frame sub-frames per frame -- must not be 0 if \p use_subframes \c == \c true + * @param offset_is_negative true if offset_samples is to be subtracted + * @param offset_samples sample offset to add or subtract + */ void LIBTEMPORAL_API timecode_to_sample ( - Timecode::Time& timecode, int64_t& sample, + Timecode::Time const& timecode, int64_t& sample, bool use_offset, bool use_subframes, - /* Note - framerate info is taken from Timecode::Time& */ - double sample_sample_rate /**< may include pull up/down */, - uint32_t subframes_per_frame /**< must not be 0 if use_subframes==true */, - /* optional offset - can be improved: function pointer to lazily query this*/ + double sample_sample_rate, + uint32_t subframes_per_frame, bool offset_is_negative, int64_t offset_samples); +/** Convert audio sample time (samples per second) to timecode (frames per second) + * + * @param sample audio sample time to convert + * @param timecode resulting Timecode + * @param use_offset apply offset as given by \p offset_is_negative and \p offset_samples + * @param use_subframes use \p subframes_per_frame when converting + * @param timecode_frames_per_second target framerate + * @param timecode_drop_frames true if fps uses drop-frame-counting. only valid for \c 29.97 \c = \c 30000/1001 fps + * @param sample_sample_rate source sample-rate, may include pull up/down + * @param subframes_per_frame sub-frames per frame -- must not be 0 if \p use_subframes \c == \c true + * @param offset_is_negative true if offset_samples is to be subtracted + * @param offset_samples sample offset to add or subtract + */ void LIBTEMPORAL_API sample_to_timecode ( int64_t sample, Timecode::Time& timecode, bool use_offset, bool use_subframes, - /* framerate info */ double timecode_frames_per_second, bool timecode_drop_frames, - double sample_sample_rate /**< can include pull up/down */, + double sample_sample_rate, uint32_t subframes_per_frame, - /* optional offset - can be improved: function pointer to lazily query this*/ bool offset_is_negative, int64_t offset_samples); } // namespace Timecode diff --git a/libs/temporal/time.cc b/libs/temporal/time.cc index c2bf96141f..5de23f342d 100644 --- a/libs/temporal/time.cc +++ b/libs/temporal/time.cc @@ -644,7 +644,7 @@ bool parse_timecode_format(std::string tc, Timecode::Time &TC) { void timecode_to_sample( - Timecode::Time& timecode, int64_t& sample, + Timecode::Time const& timecode, int64_t& sample, bool use_offset, bool use_subframes, /* Note - framerate info is taken from Timecode::Time& */ double sample_sample_rate /**< may include pull up/down */, diff --git a/libs/waveview/waveview/wave_view.h b/libs/waveview/waveview/wave_view.h index 5dbb2909ab..6a8012b5e4 100644 --- a/libs/waveview/waveview/wave_view.h +++ b/libs/waveview/waveview/wave_view.h @@ -87,8 +87,8 @@ public: void set_channel (int); void set_region_start (ARDOUR::sampleoffset_t); - /** Change the first position drawn by @param pixels. - * @param pixels must be positive. This is used by + /** Change the first position drawn by \p pixels . + * \p pixels must be positive. This is used by * AudioRegionViews in Ardour to avoid drawing the * first pixel of a waveform, and exists in case * there are uses for WaveView where we do not