mirror of
https://github.com/HifiExperiments/overte.git
synced 2025-04-07 10:02:24 +02:00
Midi JSDoc
This commit is contained in:
David Rowe
parent
d321ae9b79
commit
6837d7e5e8
2 changed files with 130 additions and 37 deletions
|
|
@ -261,6 +261,61 @@ void Midi::MidiCleanup() {
|
|||
}
|
||||
#endif
|
||||
|
||||
/**jsdoc
|
||||
* A MIDI message.
|
||||
* <p><strong>Warning:</strong> The <code>status</code> property is NOT a MIDI status value.</p>
|
||||
* @typedef {object} Midi.MidiMessage
|
||||
* @property {number} device - Device number.
|
||||
* @property {Midi.RawMidiMessage} raw - Raw MIDI message - {@link Midi.RawMidiMessage}.
|
||||
* @property {number} status - Channel + status. <em>Legacy value.</em>
|
||||
* @property {number} channel - Channel: <code>1</code> – <code>16</code>.
|
||||
* @property {number} type - Status: {@link Midi.MidiStatus}; <code>8</code> – <code>15</code>.
|
||||
* @property {number} note - Note: <code>0</code> – <code>127</code>.
|
||||
* @property {number} velocity - Note velocity: <code>0</code> – <code>127</code>. (<code>0</code> means "note off".)
|
||||
* @property {number} bend - Pitch bend: <code>-8192</code> – <code>8191</code>.
|
||||
* @property {number} program - Program change: <code>0</code> – <code>127</code>.
|
||||
*/
|
||||
/**jsdoc
|
||||
* An integer DWORD (unsigned 32 bit) message with bits having values as follows:
|
||||
* <table>
|
||||
* <tbody>
|
||||
* <tr>
|
||||
* <td width=25%><code>00000000</code></td>
|
||||
* <td width=25%><code>0vvvvvvv</code></td>
|
||||
* <td width=25%><code>0nnnnnnn</code></td>
|
||||
* <td width=12%><code>1sss</code></td>
|
||||
* <td width=12%><code>cccc</code></td>
|
||||
* </tbody>
|
||||
* </table>
|
||||
* <p>Where:</p>
|
||||
* <ul>
|
||||
* <li><code>v</code> = Velocity.
|
||||
* <li><code>n</code> = Note.
|
||||
* <li><code>s</code> = Status - {@link Midi.MidiStatus}
|
||||
* <li><code>c</code> = Channel.
|
||||
* </ul>
|
||||
* <p>The number in the first bit of each byte denotes whether it is a command (1) or data (0).
|
||||
* @typedef {number} Midi.RawMidiMessage
|
||||
*/
|
||||
/**jsdoc
|
||||
* <p>A MIDI status value. The following MIDI status values are supported:</p>
|
||||
* <table>
|
||||
* <thead>
|
||||
* <tr><th>Value</th><th>Description</th>
|
||||
* </thead>
|
||||
* <tbody>
|
||||
* <tr><td><code>8</code></td><td>Note off.</td></tr>
|
||||
* <tr><td><code>9</code></td><td>Note on.</td></tr>
|
||||
* <tr><td><code>10</code></td><td>Polyphonic key pressure.</td></tr>
|
||||
* <tr><td><code>11</code></td><td>Control change.</td></tr>
|
||||
* <tr><td><code>12</code></td><td>Program change.</td></tr>
|
||||
* <tr><td><code>13</code></td><td>Channel pressure.</td></tr>
|
||||
* <tr><td><code>14</code></td><td>Pitch bend.</td></tr>
|
||||
* <tr><td><code>15</code></td><td>System message.</td></tr>
|
||||
* </tbody>
|
||||
* </table>
|
||||
* @typedef {number} Midi.MidiStatus
|
||||
*/
|
||||
void Midi::midiReceived(int device, int raw, int channel, int status, int type, int note, int velocity, int bend, int program) {
|
||||
QVariantMap eventData;
|
||||
eventData["device"] = device;
|
||||
|
|
|
|||
|
|
@ -21,6 +21,12 @@
|
|||
#include <string>
|
||||
|
||||
/**jsdoc
|
||||
* The <code>Midi</code> API provides the ability to connect Interface with musical instruments and other external or virtual
|
||||
* devices via the MIDI protocol. For further information and examples, see the tutorial:
|
||||
* <a href="https://docs.highfidelity.com/en/rc81/script/midi-tutorial.html">Use MIDI to Control Your Environment</a>.</p>
|
||||
*
|
||||
* <p><strong>Note:</strong> Only works on Windows.</p>
|
||||
*
|
||||
* @namespace Midi
|
||||
*
|
||||
* @hifi-interface
|
||||
|
|
@ -49,88 +55,112 @@ private:
|
|||
void MidiCleanup();
|
||||
|
||||
signals:
|
||||
void midiNote(QVariantMap eventData);
|
||||
void midiMessage(QVariantMap eventData);
|
||||
void midiReset();
|
||||
|
||||
public slots:
|
||||
|
||||
/**jsdoc
|
||||
* Send Raw MIDI packet to a particular device.
|
||||
* Triggered when a connected device sends an output.
|
||||
* @function Midi.midiNote
|
||||
* @param {MidiMessage} message - The MIDI message.
|
||||
* @returns {Signal}
|
||||
* @deprecated Use {@link Midi.midiMessage|midiMessage} instead.
|
||||
*/
|
||||
void midiNote(QVariantMap eventData);
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when a connected device sends an output.
|
||||
* @function Midi.midiMessage
|
||||
* @param {MidiMessage} message - The MIDI message.
|
||||
* @returns {Signal}
|
||||
*/
|
||||
void midiMessage(QVariantMap eventData);
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when the system detects there was a reset such as when a device is plugged in or unplugged.
|
||||
* @function Midi.midiReset
|
||||
* @returns {Signal}
|
||||
*/
|
||||
void midiReset();
|
||||
|
||||
public slots:
|
||||
|
||||
/**jsdoc
|
||||
* Sends a raw MIDI packet to a particular device.
|
||||
* @function Midi.sendRawDword
|
||||
* @param {number} device - Integer device number.
|
||||
* @param {number} raw - Integer (DWORD) raw MIDI message.
|
||||
* @param {Midi.RawMidiMessage} raw - Raw MIDI message.
|
||||
*/
|
||||
Q_INVOKABLE void sendRawDword(int device, int raw);
|
||||
|
||||
/**jsdoc
|
||||
* Send MIDI message to a particular device.
|
||||
* Sends a MIDI message to a particular device.
|
||||
* @function Midi.sendMidiMessage
|
||||
* @param {number} device - Integer device number.
|
||||
* @param {number} channel - Integer channel number.
|
||||
* @param {number} type - 0x8 is note off, 0x9 is note on (if velocity=0, note off), etc.
|
||||
* @param {number} note - MIDI note number.
|
||||
* @param {number} velocity - Note velocity (0 means note off).
|
||||
* @param {Midi.MidiStatus} type - Integer status value.
|
||||
* @param {number} note - Note number.
|
||||
* @param {number} velocity - Note velocity. (<code>0</code> means "note off".)
|
||||
* @comment The "type" parameter has that name to match up with {@link Midi.MidiMessage}.
|
||||
*/
|
||||
Q_INVOKABLE void sendMidiMessage(int device, int channel, int type, int note, int velocity);
|
||||
|
||||
/**jsdoc
|
||||
* Play a note on all connected devices.
|
||||
* Plays a note on all connected devices.
|
||||
* @function Midi.playMidiNote
|
||||
* @param {number} status - 0x80 is note off, 0x90 is note on (if velocity=0, note off), etc.
|
||||
* @param {number} note - MIDI note number.
|
||||
* @param {number} velocity - Note velocity (0 means note off).
|
||||
* @param {MidiStatus} status - Note status.
|
||||
* @param {number} note - Note number.
|
||||
* @param {number} velocity - Note velocity. (<code>0</code> means "note off".)
|
||||
*/
|
||||
Q_INVOKABLE void playMidiNote(int status, int note, int velocity);
|
||||
|
||||
/**jsdoc
|
||||
* Turn off all notes on all connected devices.
|
||||
* Turns off all notes on all connected MIDI devices.
|
||||
* @function Midi.allNotesOff
|
||||
*/
|
||||
Q_INVOKABLE void allNotesOff();
|
||||
|
||||
/**jsdoc
|
||||
* Clean up and re-discover attached devices.
|
||||
* Cleans up and rediscovers attached MIDI devices.
|
||||
* @function Midi.resetDevices
|
||||
*/
|
||||
Q_INVOKABLE void resetDevices();
|
||||
|
||||
/**jsdoc
|
||||
* Get a list of inputs/outputs.
|
||||
* Gets a list of MIDI input or output devices.
|
||||
* @function Midi.listMidiDevices
|
||||
* @param {boolean} output
|
||||
* @param {boolean} output - <code>true</code> to list output devices, <code>false</code> to list input devices.
|
||||
* @returns {string[]}
|
||||
*/
|
||||
Q_INVOKABLE QStringList listMidiDevices(bool output);
|
||||
|
||||
/**jsdoc
|
||||
* Block an input/output by name.
|
||||
* Blocks a MIDI device's input or output.
|
||||
* @function Midi.blockMidiDevice
|
||||
* @param {string} name
|
||||
* @param {boolean} output
|
||||
* @param {string} name - The name of the MIDI device to block.
|
||||
* @param {boolean} output - <code>true</code> to block the device's output, <code>false</code> to block its input.
|
||||
*/
|
||||
Q_INVOKABLE void blockMidiDevice(QString name, bool output);
|
||||
|
||||
/**jsdoc
|
||||
* Unblock an input/output by name.
|
||||
* Unblocks a MIDI device's input or output.
|
||||
* @function Midi.unblockMidiDevice
|
||||
* @param {string} name
|
||||
* @param {boolean} output
|
||||
* @param {string} name- The name of the MIDI device to unblock.
|
||||
* @param {boolean} output - <code>true</code> to block the device's output, <code>false</code> to block its input.
|
||||
*/
|
||||
Q_INVOKABLE void unblockMidiDevice(QString name, bool output);
|
||||
|
||||
/**jsdoc
|
||||
* Repeat all incoming notes to all outputs (default disabled).
|
||||
* Enables or disables repeating all incoming notes to all outputs. (Default is disabled.)
|
||||
* @function Midi.thruModeEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable repeating all incoming notes to all output, <code>false</code> to
|
||||
* disable.
|
||||
*/
|
||||
Q_INVOKABLE void thruModeEnable(bool enable);
|
||||
|
||||
|
||||
/**jsdoc
|
||||
* Broadcast on all unblocked devices.
|
||||
* Enables or disables broadcasts to all unblocked devices.
|
||||
* @function Midi.broadcastEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to have "send" functions broadcast to all devices, <code>false</code> to
|
||||
* have them send to specific output devices.
|
||||
*/
|
||||
Q_INVOKABLE void broadcastEnable(bool enable);
|
||||
|
||||
|
|
@ -138,50 +168,58 @@ signals:
|
|||
/// filter by event types
|
||||
|
||||
/**jsdoc
|
||||
* Enables or disables note off events.
|
||||
* @function Midi.typeNoteOffEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable, <code>false</code> to disable.
|
||||
*/
|
||||
Q_INVOKABLE void typeNoteOffEnable(bool enable);
|
||||
|
||||
/**jsdoc
|
||||
* Enables or disabled note on events.
|
||||
* @function Midi.typeNoteOnEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable, <code>false</code> to disable.
|
||||
*/
|
||||
Q_INVOKABLE void typeNoteOnEnable(bool enable);
|
||||
|
||||
/**jsdoc
|
||||
* Enables or disabled ply key pressure events.
|
||||
* @function Midi.typePolyKeyPressureEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable, <code>false</code> to disable.
|
||||
*/
|
||||
Q_INVOKABLE void typePolyKeyPressureEnable(bool enable);
|
||||
|
||||
/**jsdoc
|
||||
* Enables or disabled control change events.
|
||||
* @function Midi.typeControlChangeEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable, <code>false</code> to disable.
|
||||
*/
|
||||
Q_INVOKABLE void typeControlChangeEnable(bool enable);
|
||||
|
||||
/**jsdoc
|
||||
* Enables or disabled program change events.
|
||||
* @function Midi.typeProgramChangeEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable, <code>false</code> to disable.
|
||||
*/
|
||||
Q_INVOKABLE void typeProgramChangeEnable(bool enable);
|
||||
|
||||
/**jsdoc
|
||||
* Enables or disables channel pressure events.
|
||||
* @function Midi.typeChanPressureEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable, <code>false</code> to disable.
|
||||
*/
|
||||
Q_INVOKABLE void typeChanPressureEnable(bool enable);
|
||||
|
||||
/**jsdoc
|
||||
* Enables or disabled pitch bend events.
|
||||
* @function Midi.typePitchBendEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable, <code>false</code> to disable.
|
||||
*/
|
||||
Q_INVOKABLE void typePitchBendEnable(bool enable);
|
||||
|
||||
/**jsdoc
|
||||
* Enables or disables system message events.
|
||||
* @function Midi.typeSystemMessageEnable
|
||||
* @param {boolean} enable
|
||||
* @param {boolean} enable - <code>true</code> to enable, <code>false</code> to disable.
|
||||
*/
|
||||
Q_INVOKABLE void typeSystemMessageEnable(bool enable);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue