juce/source/src/audio/midi/juce_MidiBuffer.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_MIDIBUFFER_JUCEHEADER__
  27 #define __JUCE_MIDIBUFFER_JUCEHEADER__
  28
  29 #include "../../memory/juce_MemoryBlock.h"
  30 #include "juce_MidiMessage.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     Holds a sequence of time-stamped midi events.
  36
  37     Analogous to the AudioSampleBuffer, this holds a set of midi events with
  38     integer time-stamps. The buffer is kept sorted in order of the time-stamps.
  39
  40     @see MidiMessage
  41 */
  42 class JUCE_API  MidiBuffer
  43 {
  44 public:
  45     //==============================================================================
  46     /** Creates an empty MidiBuffer. */
  47     MidiBuffer() noexcept;
  48
  49     /** Creates a MidiBuffer containing a single midi message. */
  50     explicit MidiBuffer (const MidiMessage& message) noexcept;
  51
  52     /** Creates a copy of another MidiBuffer. */
  53     MidiBuffer (const MidiBuffer& other) noexcept;
  54
  55     /** Makes a copy of another MidiBuffer. */
  56     MidiBuffer& operator= (const MidiBuffer& other) noexcept;
  57
  58     /** Destructor */
  59     ~MidiBuffer();
  60
  61     //==============================================================================
  62     /** Removes all events from the buffer. */
  63     void clear() noexcept;
  64
  65     /** Removes all events between two times from the buffer.
  66
  67         All events for which (start <= event position < start + numSamples) will
  68         be removed.
  69     */
  70     void clear (int start, int numSamples);
  71
  72     /** Returns true if the buffer is empty.
  73
  74         To actually retrieve the events, use a MidiBuffer::Iterator object
  75     */
  76     bool isEmpty() const noexcept;
  77
  78     /** Counts the number of events in the buffer.
  79
  80         This is actually quite a slow operation, as it has to iterate through all
  81         the events, so you might prefer to call isEmpty() if that's all you need
  82         to know.
  83     */
  84     int getNumEvents() const noexcept;
  85
  86     /** Adds an event to the buffer.
  87
  88         The sample number will be used to determine the position of the event in
  89         the buffer, which is always kept sorted. The MidiMessage's timestamp is
  90         ignored.
  91
  92         If an event is added whose sample position is the same as one or more events
  93         already in the buffer, the new event will be placed after the existing ones.
  94
  95         To retrieve events, use a MidiBuffer::Iterator object
  96     */
  97     void addEvent (const MidiMessage& midiMessage, int sampleNumber);
  98
  99     /** Adds an event to the buffer from raw midi data.
 100
 101         The sample number will be used to determine the position of the event in
 102         the buffer, which is always kept sorted.
 103
 104         If an event is added whose sample position is the same as one or more events
 105         already in the buffer, the new event will be placed after the existing ones.
 106
 107         The event data will be inspected to calculate the number of bytes in length that
 108         the midi event really takes up, so maxBytesOfMidiData may be longer than the data
 109         that actually gets stored. E.g. if you pass in a note-on and a length of 4 bytes,
 110         it'll actually only store 3 bytes. If the midi data is invalid, it might not
 111         add an event at all.
 112
 113         To retrieve events, use a MidiBuffer::Iterator object
 114     */
 115     void addEvent (const void* rawMidiData,
 116                    int maxBytesOfMidiData,
 117                    int sampleNumber);
 118
 119     /** Adds some events from another buffer to this one.
 120
 121         @param otherBuffer          the buffer containing the events you want to add
 122         @param startSample          the lowest sample number in the source buffer for which
 123                                     events should be added. Any source events whose timestamp is
 124                                     less than this will be ignored
 125         @param numSamples           the valid range of samples from the source buffer for which
 126                                     events should be added - i.e. events in the source buffer whose
 127                                     timestamp is greater than or equal to (startSample + numSamples)
 128                                     will be ignored. If this value is less than 0, all events after
 129                                     startSample will be taken.
 130         @param sampleDeltaToAdd     a value which will be added to the source timestamps of the events
 131                                     that are added to this buffer
 132     */
 133     void addEvents (const MidiBuffer& otherBuffer,
 134                     int startSample,
 135                     int numSamples,
 136                     int sampleDeltaToAdd);
 137
 138     /** Returns the sample number of the first event in the buffer.
 139
 140         If the buffer's empty, this will just return 0.
 141     */
 142     int getFirstEventTime() const noexcept;
 143
 144     /** Returns the sample number of the last event in the buffer.
 145
 146         If the buffer's empty, this will just return 0.
 147     */
 148     int getLastEventTime() const noexcept;
 149
 150     //==============================================================================
 151     /** Exchanges the contents of this buffer with another one.
 152
 153         This is a quick operation, because no memory allocating or copying is done, it
 154         just swaps the internal state of the two buffers.
 155     */
 156     void swapWith (MidiBuffer& other) noexcept;
 157
 158     /** Preallocates some memory for the buffer to use.
 159         This helps to avoid needing to reallocate space when the buffer has messages
 160         added to it.
 161     */
 162     void ensureSize (size_t minimumNumBytes);
 163
 164     //==============================================================================
 165     /**
 166         Used to iterate through the events in a MidiBuffer.
 167
 168         Note that altering the buffer while an iterator is using it isn't a
 169         safe operation.
 170
 171         @see MidiBuffer
 172     */
 173     class JUCE_API  Iterator
 174     {
 175     public:
 176         //==============================================================================
 177         /** Creates an Iterator for this MidiBuffer. */
 178         Iterator (const MidiBuffer& buffer) noexcept;
 179
 180         /** Destructor. */
 181         ~Iterator() noexcept;
 182
 183         //==============================================================================
 184         /** Repositions the iterator so that the next event retrieved will be the first
 185             one whose sample position is at greater than or equal to the given position.
 186         */
 187         void setNextSamplePosition (int samplePosition) noexcept;
 188
 189         /** Retrieves a copy of the next event from the buffer.
 190
 191             @param result   on return, this will be the message (the MidiMessage's timestamp
 192                             is not set)
 193             @param samplePosition   on return, this will be the position of the event
 194             @returns        true if an event was found, or false if the iterator has reached
 195                             the end of the buffer
 196         */
 197         bool getNextEvent (MidiMessage& result,
 198                            int& samplePosition) noexcept;
 199
 200         /** Retrieves the next event from the buffer.
 201
 202             @param midiData     on return, this pointer will be set to a block of data containing
 203                                 the midi message. Note that to make it fast, this is a pointer
 204                                 directly into the MidiBuffer's internal data, so is only valid
 205                                 temporarily until the MidiBuffer is altered.
 206             @param numBytesOfMidiData   on return, this is the number of bytes of data used by the
 207                                         midi message
 208             @param samplePosition   on return, this will be the position of the event
 209             @returns        true if an event was found, or false if the iterator has reached
 210                             the end of the buffer
 211         */
 212         bool getNextEvent (const uint8* &midiData,
 213                            int& numBytesOfMidiData,
 214                            int& samplePosition) noexcept;
 215
 216     private:
 217         //==============================================================================
 218         const MidiBuffer& buffer;
 219         const uint8* data;
 220
 221         JUCE_DECLARE_NON_COPYABLE (Iterator);
 222     };
 223
 224 private:
 225     //==============================================================================
 226     friend class MidiBuffer::Iterator;
 227     MemoryBlock data;
 228     int bytesUsed;
 229
 230     uint8* getData() const noexcept;
 231     uint8* findEventAfter (uint8* d, int samplePosition) const noexcept;
 232     static int getEventTime (const void* d) noexcept;
 233     static uint16 getEventDataSize (const void* d) noexcept;
 234     static uint16 getEventTotalSize (const void* d) noexcept;
 235
 236     JUCE_LEAK_DETECTOR (MidiBuffer);
 237 };
 238
 239
 240 #endif   // __JUCE_MIDIBUFFER_JUCEHEADER__