Jack2: Jack::JackMidiRawOutputWriteQueue Class Reference

Jack2 1.9.12

Public Member Functions | Protected Member Functions | List of all members
Jack::JackMidiRawOutputWriteQueue Class Reference

`#include <JackMidiRawOutputWriteQueue.h>`

Inheritance diagram for Jack::JackMidiRawOutputWriteQueue:

## Public Member Functions
| JackMidiRawOutputWriteQueue (JackMidiSendQueue *send_queue, size_t non_rt_size=4096, size_t max_non_rt_messages=1024, size_t max_rt_messages=128)
EnqueueResult | EnqueueEvent (jack_nframes_t time, size_t size, jack_midi_data_t *buffer)
jack_nframes_t | Process (jack_nframes_t boundary_frame=0)
virtual EnqueueResult | EnqueueEvent (jack_nframes_t time, size_t size, jack_midi_data_t *buffer)=0
EnqueueResult | EnqueueEvent (jack_midi_event_t *event, jack_nframes_t frame_offset=0)
Public Member Functions inherited from Jack::JackMidiWriteQueue
EnqueueResult | EnqueueEvent (jack_midi_event_t *event, jack_nframes_t frame_offset=0)

## Protected Member Functions
virtual void | HandleWriteQueueBug (jack_nframes_t time, jack_midi_data_t byte)

## Additional Inherited Members
Public Types inherited from Jack::JackMidiWriteQueue
enum | EnqueueResult { BUFFER_FULL, BUFFER_TOO_SMALL, EVENT_EARLY, EN_ERROR, OK }

## Detailed Description

This queue enqueues valid MIDI events and modifies them for raw output to a write queue. It has a couple of advantages over straight MIDI event copying:

-Running status: Status bytes can be omitted when the status byte of the current MIDI message is the same as the status byte of the last sent MIDI message.

-Realtime messages: Realtime messages are given priority over non-realtime messages. Realtime bytes are interspersed with non-realtime bytes so that realtime messages can be sent as close as possible to the time they're scheduled for sending.

Use this queue if the MIDI API you're interfacing with allows you to send raw MIDI bytes.

Definition at line 46 of file JackMidiRawOutputWriteQueue.h.

## Constructor & Destructor Documentation

## ◆ JackMidiRawOutputWriteQueue()

JackMidiRawOutputWriteQueue::JackMidiRawOutputWriteQueue | ( | JackMidiSendQueue * | send_queue,
|  | size_t | non_rt_size = `4096`,
|  | size_t | max_non_rt_messages = `1024`,
|  | size_t | max_rt_messages = `128`
| ) |  |

Called to create a new raw write queue. The `send_queue` argument is the queue to write raw bytes to. The optional `max_rt_messages` argument specifies the number of messages that can be enqueued in the internal realtime queue. The optional `max_non_rt_messages` argument specifies the number of messages that can be enqueued in the internal non-realtime queue. The optional `non_rt_size` argument specifies the total number of MIDI bytes that can be put in the non-realtime queue.

Definition at line 32 of file JackMidiRawOutputWriteQueue.cpp.

## Member Function Documentation

## ◆ HandleWriteQueueBug()

void JackMidiRawOutputWriteQueue::HandleWriteQueueBug | ( | jack_nframes_t | time,
|  | jack_midi_data_t | byte
| ) |  |
| protectedvirtual

Override this method to specify what happens when the write queue says that a 1-byte event is too large for its buffer. Basically, this should never happen.

Definition at line 82 of file JackMidiRawOutputWriteQueue.cpp.

## ◆ EnqueueEvent() [1/3]

Jack::JackMidiWriteQueue::EnqueueResult JackMidiRawOutputWriteQueue::EnqueueEvent | ( | jack_nframes_t | time,
|  | size_t | size,
|  | jack_midi_data_t * | buffer
| ) |  |
| virtual

Enqueues a data packet in the write queue of `size` bytes contained in `buffer` that will be sent the absolute time specified by `time`. This method should not block unless 1.) this write queue represents the actual outbound MIDI connection, 2.) the MIDI event is being sent now, meaning that `time` is less than or equal to now, and 3.) the method is not being called in the process thread. The method should return `OK` if the event was enqueued, `BUFFER_FULL` if the write queue isn't able to accept the event right now, `BUFFER_TOO_SMALL` if this write queue will never be able to accept the event because the event is too large, `EVENT_EARLY` if this queue cannot schedule events ahead of time, and `EN_ERROR` if an error occurs that cannot be specified by another return code.

Implements Jack::JackMidiWriteQueue.

Definition at line 73 of file JackMidiRawOutputWriteQueue.cpp.

## ◆ Process()

jack_nframes_t JackMidiRawOutputWriteQueue::Process | ( | jack_nframes_t | boundary_frame = `0` | ) |

The `Process()` method should be called each time the `EnqueueEvent()` method returns 'OK'. The `Process()` method will return the next frame at which an event should be sent. The return value from `Process()` depends upon the result of writing bytes to the write queue:

-If the return value is '0', then all events that have been enqueued in this queue have been sent successfully to the write queue. Don't call `Process()` again until another event has been enqueued.

-If the return value is an earlier frame or the current frame, it means that the write queue returned 'BUFFER_FULL', 'ERROR', or 'EVENT_EARLY' when this queue attempted to send the next byte, and that the byte should have already been sent, or is scheduled to be sent now. `Process()` should be called again when the write queue can enqueue events again successfully. How to determine when this will happen is left up to the caller.

-If the return value is in the future, then `Process()` should be called again at that time, or after another event is enqueued.

Definition at line 92 of file JackMidiRawOutputWriteQueue.cpp.

## ◆ EnqueueEvent() [2/3]

virtual EnqueueResult Jack::JackMidiWriteQueue::EnqueueEvent

Enqueues a data packet in the write queue of `size` bytes contained in `buffer` that will be sent the absolute time specified by `time`. This method should not block unless 1.) this write queue represents the actual outbound MIDI connection, 2.) the MIDI event is being sent now, meaning that `time` is less than or equal to now, and 3.) the method is not being called in the process thread. The method should return `OK` if the event was enqueued, `BUFFER_FULL` if the write queue isn't able to accept the event right now, `BUFFER_TOO_SMALL` if this write queue will never be able to accept the event because the event is too large, `EVENT_EARLY` if this queue cannot schedule events ahead of time, and `EN_ERROR` if an error occurs that cannot be specified by another return code.

## ◆ EnqueueEvent() [3/3]

EnqueueResult Jack::JackMidiWriteQueue::EnqueueEvent
| inline

A wrapper method for the `EnqueueEvent` method above. The optional 'frame_offset' argument is an amount of frames to add to the event's time.

Definition at line 72 of file JackMidiWriteQueue.h.

The documentation for this class was generated from the following files:

- JackMidiRawOutputWriteQueue.h
- JackMidiRawOutputWriteQueue.cpp