common/JackMidiRawInputWriteQueue.h

   1 /*
   2 Copyright (C) 2010 Devin Anderson
   3
   4 This program is free software; you can redistribute it and/or modify
   5 it under the terms of the GNU Lesser General Public License as published by
   6 the Free Software Foundation; either version 2.1 of the License, or
   7 (at your option) any later version.
   8
   9 This program is distributed in the hope that it will be useful,
  10 but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 GNU Lesser General Public License for more details.
  13
  14 You should have received a copy of the GNU Lesser General Public License
  15 along with this program; if not, write to the Free Software
  16 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  17
  18 */
  19
  20 #ifndef __JackMidiRawInputWriteQueue__
  21 #define __JackMidiRawInputWriteQueue__
  22
  23 #include "JackMidiAsyncQueue.h"
  24 #include "JackMidiWriteQueue.h"
  25
  26 namespace Jack {
  27
  28     /**
  29      * This queue enqueues raw, unparsed MIDI packets, and outputs complete
  30      * MIDI messages to a write queue.
  31      *
  32      * Use this queue if the MIDI API you're interfacing with gives you raw
  33      * MIDI bytes that must be parsed.
  34      */
  35
  36     class SERVER_EXPORT JackMidiRawInputWriteQueue: public JackMidiWriteQueue {
  37
  38     private:
  39
  40         jack_midi_event_t event;
  41         jack_midi_data_t event_byte;
  42         bool event_pending;
  43         size_t expected_bytes;
  44         jack_midi_data_t *input_buffer;
  45         size_t input_buffer_size;
  46         jack_midi_event_t *packet;
  47         JackMidiAsyncQueue *packet_queue;
  48         jack_midi_data_t status_byte;
  49         size_t total_bytes;
  50         size_t unbuffered_bytes;
  51         JackMidiWriteQueue *write_queue;
  52
  53         void
  54         Clear();
  55
  56         bool
  57         PrepareBufferedEvent(jack_nframes_t time);
  58
  59         bool
  60         PrepareByteEvent(jack_nframes_t time, jack_midi_data_t byte);
  61
  62         void
  63         PrepareEvent(jack_nframes_t time, size_t size,
  64                      jack_midi_data_t *buffer);
  65
  66         bool
  67         ProcessByte(jack_nframes_t time, jack_midi_data_t byte);
  68
  69         void
  70         RecordByte(jack_midi_data_t byte);
  71
  72         bool
  73         WriteEvent(jack_nframes_t boundary_frame);
  74
  75     protected:
  76
  77         /**
  78          * Override this method to specify what happens when there isn't enough
  79          * room in the ringbuffer to contain a parsed event.  The default
  80          * method outputs an error message.
  81          */
  82
  83         virtual void
  84         HandleBufferFailure(size_t unbuffered_bytes, size_t total_bytes);
  85
  86         /**
  87          * Override this method to specify what happens when a parsed event
  88          * can't be written to the write queue because the event's size exceeds
  89          * the total possible space in the write queue.  The default method
  90          * outputs an error message.
  91          */
  92
  93         virtual void
  94         HandleEventLoss(jack_midi_event_t *event);
  95
  96         /**
  97          * Override this method to specify what happens when an incomplete MIDI
  98          * message is parsed.  The default method outputs an error message.
  99          */
 100
 101         virtual void
 102         HandleIncompleteMessage(size_t total_bytes);
 103
 104         /**
 105          * Override this method to specify what happens when an invalid MIDI
 106          * status byte is parsed.  The default method outputs an error message.
 107          */
 108
 109         virtual void
 110         HandleInvalidStatusByte(jack_midi_data_t byte);
 111
 112         /**
 113          * Override this method to specify what happens when a sysex end byte
 114          * is parsed without first parsing a sysex begin byte.  The default
 115          * method outputs an error message.
 116          */
 117
 118         virtual void
 119         HandleUnexpectedSysexEnd(size_t total_bytes);
 120
 121     public:
 122
 123         using JackMidiWriteQueue::EnqueueEvent;
 124
 125         /**
 126          * Called to create a new raw input write queue.  The `write_queue`
 127          * argument is the queue to write parsed messages to.  The optional
 128          * `max_packets` argument specifies the number of packets that can be
 129          * enqueued in the internal queue.  The optional `max_packet_data`
 130          * argument specifies the total number of MIDI bytes that can be put in
 131          * the internal queue, AND the maximum size for an event that can be
 132          * written to the write queue.
 133          */
 134
 135         JackMidiRawInputWriteQueue(JackMidiWriteQueue *write_queue,
 136                                    size_t max_packet_data=4096,
 137                                    size_t max_packets=1024);
 138
 139         ~JackMidiRawInputWriteQueue();
 140
 141         EnqueueResult
 142         EnqueueEvent(jack_nframes_t time, size_t size,
 143                      jack_midi_data_t *buffer);
 144
 145         /**
 146          * Returns the maximum size event that can be enqueued right *now*.
 147          */
 148
 149         size_t
 150         GetAvailableSpace();
 151
 152         /**
 153          * The `Process()` method should be called each time the
 154          * `EnqueueEvent()` method returns `OK`.  The `Process()` method will
 155          * return the next frame at which an event should be sent.  The return
 156          * value from `Process()` depends upon the result of writing bytes to
 157          * the write queue:
 158          *
 159          * -If the return value is '0', then all *complete* events have been
 160          * sent successfully to the write queue.  Don't call `Process()` again
 161          * until another event has been enqueued.
 162          *
 163          * -If the return value is a non-zero value, then it specifies the
 164          * frame that a pending event is scheduled to sent at.  If the frame is
 165          * in the future, then `Process()` should be called again at that time;
 166          * otherwise, `Process()` should be called as soon as the write queue
 167          * will accept events again.
 168          */
 169
 170         jack_nframes_t
 171         Process(jack_nframes_t boundary_frame=0);
 172
 173     };
 174
 175 }
 176
 177 #endif