drivers/midi/VirtualMidiDevice.h

/*
    Copyright (C) 2008 - 2012 Christian Schoenebeck
 */

#ifndef LS_VIRTUALMIDIDEVICE_H
#define LS_VIRTUALMIDIDEVICE_H

#include "../../common/global.h"

namespace LinuxSampler {

/**
 * Light-weight MIDI interface (for MIDI in & out) intended to be used by
 * pure software MIDI "devices", that is e.g. a graphical virtual MIDI
 * keyboard in an instrument editor or in a sampler frontend. This class
 * should not be used for regular MIDI input device drivers for the sampler.
 * This primitive interface by design doesn't care about jitter, fast event
 * delivery or masses and masses of events in a short time!
 */
class VirtualMidiDevice {
public:
    enum event_type_t {
        EVENT_TYPE_NOTEON  = 1,
        EVENT_TYPE_NOTEOFF = 2,
        EVENT_TYPE_CC      = 3
    };

    struct event_t {
        event_type_t Type;
        uint8_t      Arg1; ///< Depends on @c Type (e.g. key number for note on/off events).
        uint8_t      Arg2; ///< Depends on @c Type (e.g. velocity for note on/off events).
    };

    /////////////////////////////////////////////////////////////////
    // Device methods
    //     (called by the VirtualMidiDevice implementation)

    /**
     * Sends a MIDI @e note @e on event to the sampler.
     *
     * @returns true on success, false if internal FIFO full
     *          (or provided values invalid)
     */
    bool SendNoteOnToSampler(uint8_t Key, uint8_t Velocity);

    /**
     * Sends a MIDI @e note @e off event to the sampler.
     *
     * @returns true on success, false if internal FIFO full
     *          (or provided values invalid)
     */
    bool SendNoteOffToSampler(uint8_t Key, uint8_t Velocity);

    /**
     * Sends a MIDI @e Control @e Change event to the sampler.
     *
     * @returns true on success, false if internal FIFO full
     *          (or provided values invalid)
     */
    bool SendCCToSampler(uint8_t Controller, uint8_t Value);

    /**
     * Can be called by the virtual MIDI device to check whether a new note
     * on or note off MIDI event arrived to the sampler during the last
     * call to this method. So this is a asynchronously, "polling" based
     * communication mechanism, which works in conjunction with the
     * NoteIsActive() method call.
     */
    bool NotesChanged();

    /**
     * Can be called by the virtual MIDI device to check whether a new note
     * on or note off MIDI event arrived to the sampler for @a Key during
     * the last call to this method. So this is a asynchronously,
     * "polling" based communication mechanism, which works in
     * conjunction with the NoteIsActive() method call.
     */
    bool NoteChanged(uint8_t Key);

    /**
     * Can be called by the virtual MIDI device to check which key / note
     * is currently active by the sampler, e.g. to highlight the
     * respective keys on a graphical virtual keyboard.
     *
     * @see NotesChanged(), NoteChanged()
     */
    bool NoteIsActive(uint8_t Key);

    /**
     * Returns the velocity of the @e last note on event. No FIFO is used!
     */
    uint8_t NoteOnVelocity(uint8_t Key);

    /**
     * Returns the velocity of the @e last note off event. No FIFO is used!
     */
    uint8_t NoteOffVelocity(uint8_t Key);

    /**
     * Can be called by the virtual MIDI device to check whether a Control
     * Change MIDI event arrived to the sampler during the last
     * call to this method. So this is a asynchronously, "polling" based
     * communication mechanism, which works in conjunction with the
     * ControllerValue() method call.
     */
    bool ControllersChanged();

    /**
     * Can be called by the virtual MIDI device to check whether a Control
     * Change MIDI event arrived to the sampler for @a Controller during
     * the last call to this method. So this is a asynchronously,
     * "polling" based communication mechanism, which works in
     * conjunction with the ControllerValue() method call.
     */
    bool ControllerChanged(uint8_t Controller);

    /**
     * Returns the value of the @e last Control Change event. No FIFO is used!
     */
    uint8_t ControllerValue(uint8_t Controller);

    /////////////////////////////////////////////////////////////////
    // Sampler methods
    //     (usually only called by the Sampler)

    /**
     * Informs the virtual MIDI device that a @e note @e on event occured
     * (e.g. caused by a MIDI keyboard connected to the sampler).
     * Communication acts asynchronously, that is this method call doesn't
     * lock in any way and returns immediately. It is thus realtime safe.
     *
     * @e Note: this method is usually only called by the sampler.
     *
     * @see ActiveNotesChanged(), NoteIsActive()
     */
    void SendNoteOnToDevice(uint8_t Key, uint8_t Velocity);

    /**
     * Informs the virtual MIDI device that a @e note @e off event occured
     * (e.g. caused by a MIDI keyboard connected to the sampler).
     * Communication acts asynchronously, that is this method call doesn't
     * lock in any way and returns immediately. It is thus realtime safe.
     *
     * @e Note: this method is usually only called by the sampler.
     *
     * @see ActiveNotesChanged(), NoteIsActive()
     */
    void SendNoteOffToDevice(uint8_t Key, uint8_t Velocity);

    /**
     * Informs the virtual MIDI device that a @e Control @e Change event
     * occured (e.g. caused by a MIDI keyboard connected to the sampler).
     * Communication acts asynchronously, that is this method call doesn't
     * lock in any way and returns immediately. It is thus realtime safe.
     *
     * @e Note: this method is usually only called by the sampler.
     *
     * @see ControllersChanged(), ControllerValue()
     */
    void SendCCToDevice(uint8_t Controller, uint8_t Value);

    /**
     * Gets the next pending MIDI event from the virtual MIDI device by
     * using a lockfree FIFO.
     *
     * @e Note: this method is usually only called by the sampler.
     *
     * @param Event - destination for writing the next event to
     * @returns true on success, false if no event pending
     */
    bool GetMidiEventFromDevice(event_t& Event);
    
    /////////////////////////////////////////////////////////////////
    // General Purpose Methods
    
    /**
     * Adjusts the internal event buffer to cover at least the given
     * amount of MIDI events. This might be useful, since the internal
     * event buffer is by default quite small (i.e. just 12 events).
     *
     * This method is not thread safe! Any operations upon this device
     * have to be stopped before calling this method!
     */
    void SetMaxEvents(int n);

    /**
     * Constructor
     */
    VirtualMidiDevice();

    /**
     * Destructor
     */
    virtual ~VirtualMidiDevice();

private:
    struct private_data_t;
    private_data_t* const p;
};

} // namespace LinuxSampler

#endif // LS_VIRTUALMIDIDEVICE_H
1	schoenebeck	1659	/*
2	schoenebeck	2384	Copyright (C) 2008 - 2012 Christian Schoenebeck
3	schoenebeck	1659	*/
4
5			#ifndef LS_VIRTUALMIDIDEVICE_H
6			#define LS_VIRTUALMIDIDEVICE_H
7
8			#include "../../common/global.h"
9
10			namespace LinuxSampler {
11
12			/**
13			* Light-weight MIDI interface (for MIDI in & out) intended to be used by
14			* pure software MIDI "devices", that is e.g. a graphical virtual MIDI
15			* keyboard in an instrument editor or in a sampler frontend. This class
16			* should not be used for regular MIDI input device drivers for the sampler.
17			* This primitive interface by design doesn't care about jitter, fast event
18			* delivery or masses and masses of events in a short time!
19			*/
20			class VirtualMidiDevice {
21			public:
22			enum event_type_t {
23			EVENT_TYPE_NOTEON = 1,
24	schoenebeck	2025	EVENT_TYPE_NOTEOFF = 2,
25			EVENT_TYPE_CC = 3
26	schoenebeck	1659	};
27
28			struct event_t {
29			event_type_t Type;
30	schoenebeck	2025	uint8_t Arg1; ///< Depends on @c Type (e.g. key number for note on/off events).
31			uint8_t Arg2; ///< Depends on @c Type (e.g. velocity for note on/off events).
32	schoenebeck	1659	};
33
34			/////////////////////////////////////////////////////////////////
35			// Device methods
36			// (called by the VirtualMidiDevice implementation)
37
38			/**
39			* Sends a MIDI @e note @e on event to the sampler.
40			*
41			* @returns true on success, false if internal FIFO full
42			* (or provided values invalid)
43			*/
44			bool SendNoteOnToSampler(uint8_t Key, uint8_t Velocity);
45
46			/**
47			* Sends a MIDI @e note @e off event to the sampler.
48			*
49			* @returns true on success, false if internal FIFO full
50			* (or provided values invalid)
51			*/
52			bool SendNoteOffToSampler(uint8_t Key, uint8_t Velocity);
53
54			/**
55	schoenebeck	2025	* Sends a MIDI @e Control @e Change event to the sampler.
56			*
57			* @returns true on success, false if internal FIFO full
58			* (or provided values invalid)
59			*/
60			bool SendCCToSampler(uint8_t Controller, uint8_t Value);
61
62			/**
63	schoenebeck	1659	* Can be called by the virtual MIDI device to check whether a new note
64			* on or note off MIDI event arrived to the sampler during the last
65			* call to this method. So this is a asynchronously, "polling" based
66			* communication mechanism, which works in conjunction with the
67			* NoteIsActive() method call.
68			*/
69			bool NotesChanged();
70
71			/**
72			* Can be called by the virtual MIDI device to check whether a new note
73			* on or note off MIDI event arrived to the sampler for @a Key during
74			* the last call to this method. So this is a asynchronously,
75			* "polling" based communication mechanism, which works in
76			* conjunction with the NoteIsActive() method call.
77			*/
78			bool NoteChanged(uint8_t Key);
79
80			/**
81			* Can be called by the virtual MIDI device to check which key / note
82			* is currently active by the sampler, e.g. to highlight the
83			* respective keys on a graphical virtual keyboard.
84			*
85			* @see NotesChanged(), NoteChanged()
86			*/
87			bool NoteIsActive(uint8_t Key);
88
89	schoenebeck	1663	/**
90			* Returns the velocity of the @e last note on event. No FIFO is used!
91			*/
92			uint8_t NoteOnVelocity(uint8_t Key);
93
94			/**
95			* Returns the velocity of the @e last note off event. No FIFO is used!
96			*/
97			uint8_t NoteOffVelocity(uint8_t Key);
98
99	schoenebeck	2025	/**
100			* Can be called by the virtual MIDI device to check whether a Control
101			* Change MIDI event arrived to the sampler during the last
102			* call to this method. So this is a asynchronously, "polling" based
103			* communication mechanism, which works in conjunction with the
104			* ControllerValue() method call.
105			*/
106			bool ControllersChanged();
107
108			/**
109			* Can be called by the virtual MIDI device to check whether a Control
110			* Change MIDI event arrived to the sampler for @a Controller during
111			* the last call to this method. So this is a asynchronously,
112			* "polling" based communication mechanism, which works in
113			* conjunction with the ControllerValue() method call.
114			*/
115			bool ControllerChanged(uint8_t Controller);
116
117			/**
118			* Returns the value of the @e last Control Change event. No FIFO is used!
119			*/
120			uint8_t ControllerValue(uint8_t Controller);
121
122	schoenebeck	1659	/////////////////////////////////////////////////////////////////
123			// Sampler methods
124			// (usually only called by the Sampler)
125
126			/**
127			* Informs the virtual MIDI device that a @e note @e on event occured
128			* (e.g. caused by a MIDI keyboard connected to the sampler).
129			* Communication acts asynchronously, that is this method call doesn't
130			* lock in any way and returns immediately. It is thus realtime safe.
131			*
132			* @e Note: this method is usually only called by the sampler.
133			*
134			* @see ActiveNotesChanged(), NoteIsActive()
135			*/
136			void SendNoteOnToDevice(uint8_t Key, uint8_t Velocity);
137
138			/**
139			* Informs the virtual MIDI device that a @e note @e off event occured
140			* (e.g. caused by a MIDI keyboard connected to the sampler).
141			* Communication acts asynchronously, that is this method call doesn't
142			* lock in any way and returns immediately. It is thus realtime safe.
143			*
144			* @e Note: this method is usually only called by the sampler.
145			*
146			* @see ActiveNotesChanged(), NoteIsActive()
147			*/
148			void SendNoteOffToDevice(uint8_t Key, uint8_t Velocity);
149
150			/**
151	schoenebeck	2025	* Informs the virtual MIDI device that a @e Control @e Change event
152			* occured (e.g. caused by a MIDI keyboard connected to the sampler).
153			* Communication acts asynchronously, that is this method call doesn't
154			* lock in any way and returns immediately. It is thus realtime safe.
155			*
156			* @e Note: this method is usually only called by the sampler.
157			*
158			* @see ControllersChanged(), ControllerValue()
159			*/
160			void SendCCToDevice(uint8_t Controller, uint8_t Value);
161
162			/**
163	schoenebeck	1659	* Gets the next pending MIDI event from the virtual MIDI device by
164			* using a lockfree FIFO.
165			*
166			* @e Note: this method is usually only called by the sampler.
167			*
168			* @param Event - destination for writing the next event to
169			* @returns true on success, false if no event pending
170			*/
171			bool GetMidiEventFromDevice(event_t& Event);
172	schoenebeck	2384
173			/////////////////////////////////////////////////////////////////
174			// General Purpose Methods
175
176			/**
177			* Adjusts the internal event buffer to cover at least the given
178			* amount of MIDI events. This might be useful, since the internal
179			* event buffer is by default quite small (i.e. just 12 events).
180			*
181			* This method is not thread safe! Any operations upon this device
182			* have to be stopped before calling this method!
183			*/
184			void SetMaxEvents(int n);
185	schoenebeck	1659
186			/**
187			* Constructor
188			*/
189			VirtualMidiDevice();
190
191			/**
192			* Destructor
193			*/
194			virtual ~VirtualMidiDevice();
195
196			private:
197	persson	1896	struct private_data_t;
198			private_data_t* const p;
199	schoenebeck	1659	};
200
201			} // namespace LinuxSampler
202
203			#endif // LS_VIRTUALMIDIDEVICE_H