drivers/midi/VirtualMidiDevice.h

/*
    Copyright (C) 2008 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
    };

    struct event_t {
        event_type_t Type;
        uint8_t      Key;
        uint8_t      Velocity;
    };

    /////////////////////////////////////////////////////////////////
    // 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);

    /**
     * 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);

    /////////////////////////////////////////////////////////////////
    // 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);

    /**
     * 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);

    /**
     * Constructor
     */
    VirtualMidiDevice();

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

private:
    void* pPrivateData;
};

} // namespace LinuxSampler

#endif // LS_VIRTUALMIDIDEVICE_H
1	schoenebeck	1659	/*
2			Copyright (C) 2008 Christian Schoenebeck
3			*/
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			EVENT_TYPE_NOTEOFF = 2
25			};
26
27			struct event_t {
28			event_type_t Type;
29			uint8_t Key;
30			uint8_t Velocity;
31			};
32
33			/////////////////////////////////////////////////////////////////
34			// Device methods
35			// (called by the VirtualMidiDevice implementation)
36
37			/**
38			* Sends a MIDI @e note @e on event to the sampler.
39			*
40			* @returns true on success, false if internal FIFO full
41			* (or provided values invalid)
42			*/
43			bool SendNoteOnToSampler(uint8_t Key, uint8_t Velocity);
44
45			/**
46			* Sends a MIDI @e note @e off event to the sampler.
47			*
48			* @returns true on success, false if internal FIFO full
49			* (or provided values invalid)
50			*/
51			bool SendNoteOffToSampler(uint8_t Key, uint8_t Velocity);
52
53			/**
54			* Can be called by the virtual MIDI device to check whether a new note
55			* on or note off MIDI event arrived to the sampler during the last
56			* call to this method. So this is a asynchronously, "polling" based
57			* communication mechanism, which works in conjunction with the
58			* NoteIsActive() method call.
59			*/
60			bool NotesChanged();
61
62			/**
63			* 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 for @a Key during
65			* the last call to this method. So this is a asynchronously,
66			* "polling" based communication mechanism, which works in
67			* conjunction with the NoteIsActive() method call.
68			*/
69			bool NoteChanged(uint8_t Key);
70
71			/**
72			* Can be called by the virtual MIDI device to check which key / note
73			* is currently active by the sampler, e.g. to highlight the
74			* respective keys on a graphical virtual keyboard.
75			*
76			* @see NotesChanged(), NoteChanged()
77			*/
78			bool NoteIsActive(uint8_t Key);
79
80			/////////////////////////////////////////////////////////////////
81			// Sampler methods
82			// (usually only called by the Sampler)
83
84			/**
85			* Informs the virtual MIDI device that a @e note @e on event occured
86			* (e.g. caused by a MIDI keyboard connected to the sampler).
87			* Communication acts asynchronously, that is this method call doesn't
88			* lock in any way and returns immediately. It is thus realtime safe.
89			*
90			* @e Note: this method is usually only called by the sampler.
91			*
92			* @see ActiveNotesChanged(), NoteIsActive()
93			*/
94			void SendNoteOnToDevice(uint8_t Key, uint8_t Velocity);
95
96			/**
97			* Informs the virtual MIDI device that a @e note @e off event occured
98			* (e.g. caused by a MIDI keyboard connected to the sampler).
99			* Communication acts asynchronously, that is this method call doesn't
100			* lock in any way and returns immediately. It is thus realtime safe.
101			*
102			* @e Note: this method is usually only called by the sampler.
103			*
104			* @see ActiveNotesChanged(), NoteIsActive()
105			*/
106			void SendNoteOffToDevice(uint8_t Key, uint8_t Velocity);
107
108			/**
109			* Gets the next pending MIDI event from the virtual MIDI device by
110			* using a lockfree FIFO.
111			*
112			* @e Note: this method is usually only called by the sampler.
113			*
114			* @param Event - destination for writing the next event to
115			* @returns true on success, false if no event pending
116			*/
117			bool GetMidiEventFromDevice(event_t& Event);
118
119			/**
120			* Constructor
121			*/
122			VirtualMidiDevice();
123
124			/**
125			* Destructor
126			*/
127			virtual ~VirtualMidiDevice();
128
129			private:
130			void* pPrivateData;
131			};
132
133			} // namespace LinuxSampler
134
135			#endif // LS_VIRTUALMIDIDEVICE_H