source/modules/water/midi/MidiMessageSequence.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the Water library.
   5    Copyright (c) 2016 ROLI Ltd.
   6    Copyright (C) 2017-2022 Filipe Coelho <falktx@falktx.com>
   7
   8    Permission is granted to use this software under the terms of the ISC license
   9    http://www.isc.org/downloads/software-support-policy/isc-license/
  10
  11    Permission to use, copy, modify, and/or distribute this software for any
  12    purpose with or without fee is hereby granted, provided that the above
  13    copyright notice and this permission notice appear in all copies.
  14
  15    THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
  16    TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  17    FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
  18    OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  19    USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  20    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  21    OF THIS SOFTWARE.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef WATER_MIDIMESSAGESEQUENCE_H_INCLUDED
  27 #define WATER_MIDIMESSAGESEQUENCE_H_INCLUDED
  28
  29 #include "MidiMessage.h"
  30 #include "../containers/Array.h"
  31 #include "../containers/OwnedArray.h"
  32
  33 namespace water {
  34
  35 //==============================================================================
  36 /**
  37     A sequence of timestamped midi messages.
  38
  39     This allows the sequence to be manipulated, and also to be read from and
  40     written to a standard midi file.
  41
  42     @see MidiMessage, MidiFile
  43 */
  44 class MidiMessageSequence
  45 {
  46 public:
  47     //==============================================================================
  48     /** Creates an empty midi sequence object. */
  49     MidiMessageSequence();
  50
  51     /** Creates a copy of another sequence. */
  52     MidiMessageSequence (const MidiMessageSequence&);
  53
  54     /** Replaces this sequence with another one. */
  55     MidiMessageSequence& operator= (const MidiMessageSequence&);
  56
  57     /** Destructor. */
  58     ~MidiMessageSequence();
  59
  60     //==============================================================================
  61     /** Structure used to hold midi events in the sequence.
  62
  63         These structures act as 'handles' on the events as they are moved about in
  64         the list, and make it quick to find the matching note-offs for note-on events.
  65
  66         @see MidiMessageSequence::getEventPointer
  67     */
  68     class MidiEventHolder
  69     {
  70     public:
  71         //==============================================================================
  72         /** Destructor. */
  73         ~MidiEventHolder();
  74
  75         /** The message itself, whose timestamp is used to specify the event's time. */
  76         MidiMessage message;
  77
  78         /** The matching note-off event (if this is a note-on event).
  79
  80             If this isn't a note-on, this pointer will be nullptr.
  81
  82             Use the MidiMessageSequence::updateMatchedPairs() method to keep these
  83             note-offs up-to-date after events have been moved around in the sequence
  84             or deleted.
  85         */
  86         MidiEventHolder* noteOffObject;
  87
  88     private:
  89         //==============================================================================
  90         friend class MidiMessageSequence;
  91         MidiEventHolder (const MidiMessage&);
  92
  93         CARLA_DECLARE_NON_COPYABLE(MidiEventHolder);
  94     };
  95
  96     //==============================================================================
  97     /** Clears the sequence. */
  98     void clear();
  99
 100     /** Returns the number of events in the sequence. */
 101     int getNumEvents() const noexcept;
 102
 103     /** Returns a pointer to one of the events. */
 104     MidiEventHolder* getEventPointer (int index) const noexcept;
 105
 106     //==============================================================================
 107     /** Returns the timestamp of the first event in the sequence.
 108         @see getEndTime
 109     */
 110     double getStartTime() const noexcept;
 111
 112     /** Returns the timestamp of the last event in the sequence.
 113         @see getStartTime
 114     */
 115     double getEndTime() const noexcept;
 116
 117     /** Returns the timestamp of the event at a given index.
 118         If the index is out-of-range, this will return 0.0
 119     */
 120     double getEventTime (int index) const noexcept;
 121
 122     //==============================================================================
 123     /** Inserts a midi message into the sequence.
 124
 125         The index at which the new message gets inserted will depend on its timestamp,
 126         because the sequence is kept sorted.
 127
 128         Remember to call updateMatchedPairs() after adding note-on events.
 129
 130         @param newMessage       the new message to add (an internal copy will be made)
 131         @param timeAdjustment   an optional value to add to the timestamp of the message
 132                                 that will be inserted
 133         @see updateMatchedPairs
 134     */
 135     MidiEventHolder* addEvent (const MidiMessage& newMessage,
 136                                double timeAdjustment = 0);
 137
 138     /** Merges another sequence into this one.
 139         Remember to call updateMatchedPairs() after using this method.
 140
 141         @param other                    the sequence to add from
 142         @param timeAdjustmentDelta      an amount to add to the timestamps of the midi events
 143                                         as they are read from the other sequence
 144     */
 145     void addSequence (const MidiMessageSequence& other,
 146                       double timeAdjustmentDelta);
 147
 148     //==============================================================================
 149     /** Makes sure all the note-on and note-off pairs are up-to-date.
 150
 151         Call this after re-ordering messages or deleting/adding messages, and it
 152         will scan the list and make sure all the note-offs in the MidiEventHolder
 153         structures are pointing at the correct ones.
 154     */
 155     void updateMatchedPairs() noexcept;
 156
 157     /** Forces a sort of the sequence.
 158         You may need to call this if you've manually modified the timestamps of some
 159         events such that the overall order now needs updating.
 160     */
 161     void sort() noexcept;
 162
 163     //==============================================================================
 164     /** Swaps this sequence with another one. */
 165     void swapWith (MidiMessageSequence&) noexcept;
 166
 167 private:
 168     //==============================================================================
 169     friend class MidiFile;
 170     OwnedArray<MidiEventHolder> list;
 171 };
 172
 173 }
 174
 175 #endif // WATER_MIDIMESSAGESEQUENCE_H_INCLUDED