diff --git a/src/track/beats.h b/src/track/beats.h index bddbd04bb711..9bea3197e96c 100644 --- a/src/track/beats.h +++ b/src/track/beats.h @@ -22,22 +22,28 @@ class BeatIterator { virtual double next() = 0; }; -// Beats is the base class for BPM and beat management classes. It -// provides a specification of all methods a beat-manager class must provide, as -// well as a capability model for representing optional features. +/// Beats is the base class for BPM and beat management classes. It provides a +/// specification of all methods a beat-manager class must provide, as well as +/// a capability model for representing optional features. class Beats { public: virtual ~Beats() = default; enum Capabilities { - BEATSCAP_NONE = 0x0000, - BEATSCAP_ADDREMOVE = 0x0001, // Add or remove a single beat - BEATSCAP_TRANSLATE = 0x0002, // Move all beat markers earlier or later - BEATSCAP_SCALE = 0x0004, // Scale beat distance by a fixed ratio - BEATSCAP_MOVEBEAT = 0x0008, // Move a single Beat - BEATSCAP_SETBPM = 0x0010 // Set new bpm, beat grid only + BEATSCAP_NONE = 0x0000, + /// Add or remove a single beat + BEATSCAP_ADDREMOVE = 0x0001, + /// Move all beat markers earlier or later + BEATSCAP_TRANSLATE = 0x0002, + /// Scale beat distance by a fixed ratio + BEATSCAP_SCALE = 0x0004, + /// Move a single Beat + BEATSCAP_MOVEBEAT = 0x0008, + /// Set new bpm, beat grid only + BEATSCAP_SETBPM = 0x0010 }; - typedef int CapabilitiesFlags; // Allows us to do ORing + /// Allows us to do ORing + typedef int CapabilitiesFlags; enum BPMScale { DOUBLE, @@ -48,17 +54,18 @@ class Beats { THREEHALVES, }; + /// Retrieve the capabilities supported by the beats implementation. virtual Beats::CapabilitiesFlags getCapabilities() const = 0; - // Serialization + /// Serialize beats to QByteArray. virtual QByteArray toByteArray() const = 0; - // A string representing the version of the beat-processing code that - // produced this Beats instance. Used by BeatsFactory for associating a - // given serialization with the version that produced it. + /// A string representing the version of the beat-processing code that + /// produced this Beats instance. Used by BeatsFactory for associating a + /// given serialization with the version that produced it. virtual QString getVersion() const = 0; - // A sub-version can be used to represent the preferences used to generate - // the beats object. + /// A sub-version can be used to represent the preferences used to generate + /// the beats object. virtual QString getSubVersion() const = 0; //////////////////////////////////////////////////////////////////////////// @@ -70,62 +77,62 @@ class Beats { // TODO: We may want to implement these with common code that returns // the triple of closest, next, and prev. - // Starting from sample dSamples, return the sample of the next beat in the - // track, or -1 if none exists. If dSamples refers to the location of a - // beat, dSamples is returned. + /// Starting from dSamples, return the sample of the next beat in the + /// track, or -1 if none exists. If dSamples refers to the location of a + /// beat, dSamples is returned. virtual double findNextBeat(double dSamples) const = 0; - // Starting from sample dSamples, return the sample of the previous beat in - // the track, or -1 if none exists. If dSamples refers to the location of - // beat, dSamples is returned. + /// Starting from sample dSamples, return the sample of the previous beat + /// in the track, or -1 if none exists. If dSamples refers to the location + /// of beat, dSamples is returned. virtual double findPrevBeat(double dSamples) const = 0; - // Starting from sample dSamples, fill the samples of the previous beat - // and next beat. Either can be -1 if none exists. If dSamples refers - // to the location of the beat, the first value is dSamples, and the second - // value is the next beat position. Non- -1 values are guaranteed to be - // even. Returns false if *at least one* sample is -1. (Can return false - // with one beat successfully filled) + /// Starting from sample dSamples, fill the samples of the previous beat + /// and next beat. Either can be -1 if none exists. If dSamples refers to + /// the location of the beat, the first value is dSamples, and the second + /// value is the next beat position. Non- -1 values are guaranteed to be + /// even. Returns false if *at least one* sample is -1. (Can return false + /// with one beat successfully filled) virtual bool findPrevNextBeats(double dSamples, double* dpPrevBeatSamples, double* dpNextBeatSamples, bool snapToNearBeats) const = 0; - // Starting from sample dSamples, return the sample of the closest beat in - // the track, or -1 if none exists. Non- -1 values are guaranteed to be - // even. + /// Starting from sample dSamples, return the sample of the closest beat in + /// the track, or -1 if none exists. Non- -1 values are guaranteed to be + /// even. virtual double findClosestBeat(double dSamples) const = 0; - // Find the Nth beat from sample dSamples. Works with both positive and - // negative values of n. Calling findNthBeat with n=0 is invalid. Calling - // findNthBeat with n=1 or n=-1 is equivalent to calling findNextBeat and - // findPrevBeat, respectively. If dSamples refers to the location of a beat, - // then dSamples is returned. If no beat can be found, returns -1. + /// Find the Nth beat from sample dSamples. Works with both positive and + /// negative values of n. Calling findNthBeat with n=0 is invalid. Calling + /// findNthBeat with n=1 or n=-1 is equivalent to calling findNextBeat and + /// findPrevBeat, respectively. If dSamples refers to the location of a + /// beat, then dSamples is returned. If no beat can be found, returns -1. virtual double findNthBeat(double dSamples, int n) const = 0; int numBeatsInRange(double dStartSample, double dEndSample) const; - // Find the sample N beats away from dSample. The number of beats may be - // negative and does not need to be an integer. + /// Find the sample N beats away from dSample. The number of beats may be + /// negative and does not need to be an integer. double findNBeatsFromSample(double fromSample, double beats) const; - - // Adds to pBeatsList the position in samples of every beat occurring between - // startPosition and endPosition. BeatIterator must be iterated while - // holding a strong references to the Beats object to ensure that the Beats - // object is not deleted. Caller takes ownership of the returned BeatIterator; + /// Adds to pBeatsList the position in samples of every beat occurring + /// between startPosition and endPosition. BeatIterator must be iterated + /// while holding a strong references to the Beats object to ensure that + /// the Beats object is not deleted. Caller takes ownership of the returned + /// BeatIterator; virtual std::unique_ptr findBeats(double startSample, double stopSample) const = 0; - // Return whether or not a sample lies between startPosition and endPosition + /// Return whether or not a sample lies between startPosition and endPosition. virtual bool hasBeatInRange(double startSample, double stopSample) const = 0; - // Return the average BPM over the entire track if the BPM is - // valid, otherwise returns -1 + /// Return the average BPM over the entire track if the BPM is valid, + /// otherwise returns -1 virtual mixxx::Bpm getBpm() const = 0; - // Return the average BPM over the range of n*2 beats centered around - // curSample. (An n of 4 results in an averaging of 8 beats). Invalid - // BPM returns -1. + /// Return the average BPM over the range of n*2 beats centered around + /// curSample. (An n of 4 results in an averaging of 8 beats). Invalid + /// BPM returns -1. virtual mixxx::Bpm getBpmAroundPosition(double curSample, int n) const = 0; virtual audio::SampleRate getSampleRate() const = 0; @@ -134,17 +141,17 @@ class Beats { // Beat mutations //////////////////////////////////////////////////////////////////////////// - // Translate all beats in the song by dNumSamples samples. Beats that lie - // before the start of the track or after the end of the track are not - // removed. Beats instance must have the capability BEATSCAP_TRANSLATE. + /// Translate all beats in the song by dNumSamples samples. Beats that lie + /// before the start of the track or after the end of the track are not + /// removed. Beats instance must have the capability BEATSCAP_TRANSLATE. virtual BeatsPointer translate(double dNumSamples) const = 0; - // Scale the position of every beat in the song by dScalePercentage. Beats - // class must have the capability BEATSCAP_SCALE. + /// Scale the position of every beat in the song by dScalePercentage. Beats + /// class must have the capability BEATSCAP_SCALE. virtual BeatsPointer scale(enum BPMScale scale) const = 0; - // Adjust the beats so the global average BPM matches bpm. Beats class must - // have the capability BEATSCAP_SET. + /// Adjust the beats so the global average BPM matches bpm. Beats class + /// must have the capability BEATSCAP_SET. virtual BeatsPointer setBpm(mixxx::Bpm bpm) = 0; };