1
0
Fork 0
mirror of https://github.com/juce-framework/JUCE.git synced 2026-01-10 23:44:24 +00:00

UMP: Make documentation private until APIs become public

This commit is contained in:
reuk 2021-11-29 12:15:20 +00:00
parent 03428561ed
commit f269f1d6c9
No known key found for this signature in database
GPG key ID: FCB43929F012EE5C
16 changed files with 94 additions and 94 deletions

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Functions to assist conversion of UMP messages to/from other formats,
especially older 'bytestream' formatted MidiMessages.
@ -33,7 +33,7 @@ namespace universal_midi_packets
*/
struct Conversion
{
/** Converts from a MIDI 1 bytestream to MIDI 1 on Universal MIDI Packets.
/* Converts from a MIDI 1 bytestream to MIDI 1 on Universal MIDI Packets.
`callback` is a function which accepts a single View argument.
*/
@ -97,7 +97,7 @@ struct Conversion
}
}
/** Converts a MidiMessage to one or more messages in UMP format, using
/* Converts a MidiMessage to one or more messages in UMP format, using
the MIDI 1.0 Protocol.
`packets` is an out-param to allow the caller to control
@ -111,7 +111,7 @@ struct Conversion
toMidi1 (m, [&] (const View& view) { packets.add (view); });
}
/** Widens a 7-bit MIDI 1.0 value to a 8-bit MIDI 2.0 value. */
/* Widens a 7-bit MIDI 1.0 value to a 8-bit MIDI 2.0 value. */
static uint8_t scaleTo8 (uint8_t word7Bit)
{
const auto shifted = (uint8_t) (word7Bit << 0x1);
@ -120,7 +120,7 @@ struct Conversion
return (uint8_t) (shifted | ((repeat >> 5) & mask));
}
/** Widens a 7-bit MIDI 1.0 value to a 16-bit MIDI 2.0 value. */
/* Widens a 7-bit MIDI 1.0 value to a 16-bit MIDI 2.0 value. */
static uint16_t scaleTo16 (uint8_t word7Bit)
{
const auto shifted = (uint16_t) (word7Bit << 0x9);
@ -129,7 +129,7 @@ struct Conversion
return (uint16_t) (shifted | (((repeat << 3) | (repeat >> 3)) & mask));
}
/** Widens a 14-bit MIDI 1.0 value to a 16-bit MIDI 2.0 value. */
/* Widens a 14-bit MIDI 1.0 value to a 16-bit MIDI 2.0 value. */
static uint16_t scaleTo16 (uint16_t word14Bit)
{
const auto shifted = (uint16_t) (word14Bit << 0x2);
@ -138,7 +138,7 @@ struct Conversion
return (uint16_t) (shifted | ((repeat >> 11) & mask));
}
/** Widens a 7-bit MIDI 1.0 value to a 32-bit MIDI 2.0 value. */
/* Widens a 7-bit MIDI 1.0 value to a 32-bit MIDI 2.0 value. */
static uint32_t scaleTo32 (uint8_t word7Bit)
{
const auto shifted = (uint32_t) (word7Bit << 0x19);
@ -151,7 +151,7 @@ struct Conversion
| (repeat >> 5)) & mask));
}
/** Widens a 14-bit MIDI 1.0 value to a 32-bit MIDI 2.0 value. */
/* Widens a 14-bit MIDI 1.0 value to a 32-bit MIDI 2.0 value. */
static uint32_t scaleTo32 (uint16_t word14Bit)
{
const auto shifted = (uint32_t) (word14Bit << 0x12);
@ -160,22 +160,22 @@ struct Conversion
return (uint32_t) (shifted | (((repeat << 5) | (repeat >> 8)) & mask));
}
/** Narrows a 16-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */
/* Narrows a 16-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */
static uint8_t scaleTo7 (uint8_t word8Bit) { return (uint8_t) (word8Bit >> 1); }
/** Narrows a 16-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */
/* Narrows a 16-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */
static uint8_t scaleTo7 (uint16_t word16Bit) { return (uint8_t) (word16Bit >> 9); }
/** Narrows a 32-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */
/* Narrows a 32-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */
static uint8_t scaleTo7 (uint32_t word32Bit) { return (uint8_t) (word32Bit >> 25); }
/** Narrows a 32-bit MIDI 2.0 value to a 14-bit MIDI 1.0 value. */
/* Narrows a 32-bit MIDI 2.0 value to a 14-bit MIDI 1.0 value. */
static uint16_t scaleTo14 (uint16_t word16Bit) { return (uint16_t) (word16Bit >> 2); }
/** Narrows a 32-bit MIDI 2.0 value to a 14-bit MIDI 1.0 value. */
/* Narrows a 32-bit MIDI 2.0 value to a 14-bit MIDI 1.0 value. */
static uint16_t scaleTo14 (uint32_t word32Bit) { return (uint16_t) (word32Bit >> 18); }
/** Converts UMP messages which may include MIDI 2.0 channel voice messages into
/* Converts UMP messages which may include MIDI 2.0 channel voice messages into
equivalent MIDI 1.0 messages (still in UMP format).
`callback` is a function that accepts a single View argument and will be

View file

@ -24,7 +24,7 @@ namespace juce
{
namespace universal_midi_packets
{
/**
/*
Allows conversion from bytestream- or Universal MIDI Packet-formatted
messages to MIDI 1.0 messages in UMP format.
@ -45,7 +45,7 @@ namespace universal_midi_packets
}
};
/**
/*
Allows conversion from bytestream- or Universal MIDI Packet-formatted
messages to MIDI 2.0 messages in UMP format.
@ -76,7 +76,7 @@ namespace universal_midi_packets
Midi1ToMidi2DefaultTranslator translator;
};
/**
/*
Allows conversion from bytestream- or Universal MIDI Packet-formatted
messages to UMP format.
@ -131,7 +131,7 @@ namespace universal_midi_packets
const PacketProtocol mode{};
};
/**
/*
Allows conversion from bytestream- or Universal MIDI Packet-formatted
messages to bytestream format.

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Parses a raw stream of uint32_t, and calls a user-provided callback every time
a full Universal MIDI Packet is encountered.
@ -34,10 +34,10 @@ namespace universal_midi_packets
class Dispatcher
{
public:
/** Clears the dispatcher. */
/* Clears the dispatcher. */
void reset() { currentPacketLen = 0; }
/** Calls `callback` with a View of each packet encountered in the range delimited
/* Calls `callback` with a View of each packet encountered in the range delimited
by `begin` and `end`.
If the range ends part-way through a packet, the next call to `dispatch` will
@ -67,7 +67,7 @@ private:
};
//==============================================================================
/**
/*
Parses a stream of bytes representing a sequence of bytestream-encoded MIDI 1.0 messages,
converting the messages to UMP format and passing the packets to a user-provided callback
as they become ready.
@ -77,7 +77,7 @@ private:
class BytestreamToUMPDispatcher
{
public:
/** Initialises the dispatcher.
/* Initialises the dispatcher.
Channel messages will be converted to the requested protocol format `pp`.
`storageSize` bytes will be allocated to store incomplete messages.
@ -93,7 +93,7 @@ public:
converter.reset();
}
/** Calls `callback` with a View of each converted packet as it becomes ready.
/* Calls `callback` with a View of each converted packet as it becomes ready.
@param begin the first byte in a range of bytes representing bytestream-encoded MIDI messages.
@param end one-past the last byte in a range of bytes representing bytestream-encoded MIDI messages.
@ -145,7 +145,7 @@ private:
};
//==============================================================================
/**
/*
Parses a stream of 32-bit words representing a sequence of UMP-encoded MIDI messages,
converting the messages to MIDI 1.0 bytestream format and passing them to a user-provided
callback as they become ready.
@ -155,21 +155,21 @@ private:
class ToBytestreamDispatcher
{
public:
/** Initialises the dispatcher.
/* Initialises the dispatcher.
`storageSize` bytes will be allocated to store incomplete messages.
*/
explicit ToBytestreamDispatcher (int storageSize)
: converter (storageSize) {}
/** Clears the dispatcher. */
/* Clears the dispatcher. */
void reset()
{
dispatcher.reset();
converter.reset();
}
/** Calls `callback` with converted bytestream-formatted MidiMessage whenever
/* Calls `callback` with converted bytestream-formatted MidiMessage whenever
a new message becomes available.
@param begin the first word in a stream of words representing UMP-encoded MIDI packets.

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
This struct holds functions that can be used to create different kinds
of Universal MIDI Packet.
@ -33,7 +33,7 @@ namespace universal_midi_packets
*/
struct Factory
{
/** @internal */
/* @internal */
struct Detail
{
static PacketX1 makeSystem() { return PacketX1{}.withMessageType (1); }

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Enables iteration over a collection of Universal MIDI Packets stored as
a contiguous range of 32-bit words.
@ -37,10 +37,10 @@ namespace universal_midi_packets
class Iterator
{
public:
/** Creates an invalid (singular) iterator. */
/* Creates an invalid (singular) iterator. */
Iterator() noexcept = default;
/** Creates an iterator pointing at `ptr`. */
/* Creates an iterator pointing at `ptr`. */
explicit Iterator (const uint32_t* ptr, size_t bytes) noexcept
: view (ptr)
#if JUCE_DEBUG
@ -56,7 +56,7 @@ public:
using pointer = const View*;
using iterator_category = std::forward_iterator_tag;
/** Moves this iterator to the next packet in the range. */
/* Moves this iterator to the next packet in the range. */
Iterator& operator++() noexcept
{
const auto increment = view.size();
@ -73,7 +73,7 @@ public:
return *this;
}
/** Moves this iterator to the next packet in the range,
/* Moves this iterator to the next packet in the range,
returning the value of the iterator before it was
incremented.
*/
@ -84,7 +84,7 @@ public:
return copy;
}
/** Returns true if this iterator points to the same address
/* Returns true if this iterator points to the same address
as another iterator.
*/
bool operator== (const Iterator& other) const noexcept
@ -92,7 +92,7 @@ public:
return view == other.view;
}
/** Returns false if this iterator points to the same address
/* Returns false if this iterator points to the same address
as another iterator.
*/
bool operator!= (const Iterator& other) const noexcept
@ -100,14 +100,14 @@ public:
return ! operator== (other);
}
/** Returns a reference to a View of the packet currently
/* Returns a reference to a View of the packet currently
pointed-to by this iterator.
The View can be queried for its size and content.
*/
reference operator*() noexcept { return view; }
/** Returns a pointer to a View of the packet currently
/* Returns a pointer to a View of the packet currently
pointed-to by this iterator.
The View can be queried for its size and content.

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Parses a raw stream of uint32_t holding a series of Universal MIDI Packets using
the MIDI 1.0 Protocol, converting to plain (non-UMP) MidiMessages.
@ -34,7 +34,7 @@ namespace universal_midi_packets
class Midi1ToBytestreamTranslator
{
public:
/** Ensures that there is room in the internal buffer for a sysex message of at least
/* Ensures that there is room in the internal buffer for a sysex message of at least
`initialBufferSize` bytes.
*/
explicit Midi1ToBytestreamTranslator (int initialBufferSize)
@ -42,14 +42,14 @@ public:
pendingSysExData.reserve (size_t (initialBufferSize));
}
/** Clears the concatenator. */
/* Clears the concatenator. */
void reset()
{
pendingSysExData.clear();
pendingSysExTime = 0.0;
}
/** Converts a Universal MIDI Packet using the MIDI 1.0 Protocol to
/* Converts a Universal MIDI Packet using the MIDI 1.0 Protocol to
an equivalent MidiMessage. Accumulates SysEx packets into a single
MidiMessage, as appropriate.
@ -91,7 +91,7 @@ public:
}
}
/** Converts from a Universal MIDI Packet to MIDI 1 bytestream format.
/* Converts from a Universal MIDI Packet to MIDI 1 bytestream format.
This is only capable of converting a single Universal MIDI Packet to
an equivalent bytestream MIDI message. This function cannot understand

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Translates a series of MIDI 1 Universal MIDI Packets to corresponding MIDI 2
packets.
@ -36,7 +36,7 @@ class Midi1ToMidi2DefaultTranslator
public:
Midi1ToMidi2DefaultTranslator() = default;
/** Converts MIDI 1 Universal MIDI Packets to corresponding MIDI 2 packets,
/* Converts MIDI 1 Universal MIDI Packets to corresponding MIDI 2 packets,
calling `callback` with each converted packet.
In some cases (such as RPN/NRPN messages) multiple MIDI 1 packets will

View file

@ -25,14 +25,14 @@ namespace juce
namespace universal_midi_packets
{
/** The kinds of MIDI protocol that can be formatted into Universal MIDI Packets. */
/* The kinds of MIDI protocol that can be formatted into Universal MIDI Packets. */
enum class PacketProtocol
{
MIDI_1_0,
MIDI_2_0,
};
/** All kinds of MIDI protocol understood by JUCE. */
/* All kinds of MIDI protocol understood by JUCE. */
enum class MidiProtocol
{
bytestream,

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
A base class for classes which receive Universal MIDI Packets from an input.
@tags{Audio}
@ -34,7 +34,7 @@ struct Receiver
{
virtual ~Receiver() noexcept = default;
/** This will be called each time a new packet is ready for processing. */
/* This will be called each time a new packet is ready for processing. */
virtual void packetReceived (const View& packet, double time) = 0;
};

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
This struct acts as a single-file namespace for Univeral MIDI Packet
functionality related to 7-bit SysEx.
@ -33,7 +33,7 @@ namespace universal_midi_packets
*/
struct SysEx7
{
/** Returns the number of 64-bit packets required to hold a series of
/* Returns the number of 64-bit packets required to hold a series of
SysEx bytes.
The number passed to this function should exclude the leading/trailing
@ -42,30 +42,30 @@ struct SysEx7
*/
static uint32_t getNumPacketsRequiredForDataSize (uint32_t);
/** The different kinds of UMP SysEx-7 message. */
/* The different kinds of UMP SysEx-7 message. */
enum class Kind : uint8_t
{
/** The whole message fits in a single 2-word packet. */
/* The whole message fits in a single 2-word packet. */
complete = 0,
/** The packet begins a SysEx message that will continue in subsequent packets. */
/* The packet begins a SysEx message that will continue in subsequent packets. */
begin = 1,
/** The packet is a continuation of an ongoing SysEx message. */
/* The packet is a continuation of an ongoing SysEx message. */
continuation = 2,
/** The packet terminates an ongoing SysEx message. */
/* The packet terminates an ongoing SysEx message. */
end = 3
};
/** Holds the bytes from a single SysEx-7 packet. */
/* Holds the bytes from a single SysEx-7 packet. */
struct PacketBytes
{
std::array<uint8_t, 6> data;
uint8_t size;
};
/** Extracts the data bytes from a 64-bit data message. */
/* Extracts the data bytes from a 64-bit data message. */
static PacketBytes getDataBytes (const PacketX2& packet);
};

View file

@ -25,20 +25,20 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Helpful types and functions for interacting with Universal MIDI Packets.
@tags{Audio}
*/
struct Utils
{
/** Joins 4 bytes into a single 32-bit word. */
/* Joins 4 bytes into a single 32-bit word. */
static constexpr uint32_t bytesToWord (uint8_t a, uint8_t b, uint8_t c, uint8_t d)
{
return uint32_t (a << 0x18 | b << 0x10 | c << 0x08 | d << 0x00);
}
/** Returns the expected number of 32-bit words in a Universal MIDI Packet, given
/* Returns the expected number of 32-bit words in a Universal MIDI Packet, given
the first word of the packet.
The result will be between 1 and 4 inclusive.
@ -46,7 +46,7 @@ struct Utils
*/
static uint32_t getNumWordsForMessageType (uint32_t);
/**
/*
Helper functions for setting/getting 4-bit ranges inside a 32-bit word.
*/
template <size_t Index>
@ -65,7 +65,7 @@ struct Utils
}
};
/**
/*
Helper functions for setting/getting 8-bit ranges inside a 32-bit word.
*/
template <size_t Index>
@ -84,7 +84,7 @@ struct Utils
}
};
/**
/*
Helper functions for setting/getting 16-bit ranges inside a 32-bit word.
*/
template <size_t Index>

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Points to a single Universal MIDI Packet.
The packet must be well-formed for member functions to work correctly.
@ -43,41 +43,41 @@ namespace universal_midi_packets
class View
{
public:
/** Create an invalid view. */
/* Create an invalid view. */
View() noexcept = default;
/** Create a view of the packet starting at address `d`. */
/* Create a view of the packet starting at address `d`. */
explicit View (const uint32_t* data) noexcept : ptr (data) {}
/** Get a pointer to the first word in the Universal MIDI Packet currently
/* Get a pointer to the first word in the Universal MIDI Packet currently
pointed-to by this view.
*/
const uint32_t* data() const noexcept { return ptr; }
/** Get the number of 32-words (between 1 and 4 inclusive) in the Universal
/* Get the number of 32-words (between 1 and 4 inclusive) in the Universal
MIDI Packet currently pointed-to by this view.
*/
uint32_t size() const noexcept;
/** Get a specific word from this packet.
/* Get a specific word from this packet.
Passing an `index` that is greater than or equal to the result of `size`
will cause undefined behaviour.
*/
const uint32_t& operator[] (size_t index) const noexcept { return ptr[index]; }
/** Get an iterator pointing to the first word in the packet. */
/* Get an iterator pointing to the first word in the packet. */
const uint32_t* begin() const noexcept { return ptr; }
const uint32_t* cbegin() const noexcept { return ptr; }
/** Get an iterator pointing one-past the last word in the packet. */
/* Get an iterator pointing one-past the last word in the packet. */
const uint32_t* end() const noexcept { return ptr + size(); }
const uint32_t* cend() const noexcept { return ptr + size(); }
/** Return true if this view is pointing to the same address as another view. */
/* Return true if this view is pointing to the same address as another view. */
bool operator== (const View& other) const noexcept { return ptr == other.ptr; }
/** Return false if this view is pointing to the same address as another view. */
/* Return false if this view is pointing to the same address as another view. */
bool operator!= (const View& other) const noexcept { return ! operator== (other); }
private:

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Holds a single Universal MIDI Packet.
@tags{Audio}

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
Holds a collection of Universal MIDI Packets.
Unlike MidiBuffer, this collection does not store any additional information
@ -39,7 +39,7 @@ namespace universal_midi_packets
class Packets
{
public:
/** Adds a single packet to the collection.
/* Adds a single packet to the collection.
The View must be valid for this to work. If the view
points to a malformed message, or if the view points to a region
@ -53,24 +53,24 @@ public:
void add (const PacketX3& p) { addImpl (p); }
void add (const PacketX4& p) { addImpl (p); }
/** Pre-allocates space for at least `numWords` 32-bit words in this collection. */
/* Pre-allocates space for at least `numWords` 32-bit words in this collection. */
void reserve (size_t numWords) { storage.reserve (numWords); }
/** Removes all previously-added packets from this collection. */
/* Removes all previously-added packets from this collection. */
void clear() { storage.clear(); }
/** Gets an iterator pointing to the first packet in this collection. */
/* Gets an iterator pointing to the first packet in this collection. */
Iterator cbegin() const noexcept { return Iterator (data(), size()); }
Iterator begin() const noexcept { return cbegin(); }
/** Gets an iterator pointing one-past the last packet in this collection. */
/* Gets an iterator pointing one-past the last packet in this collection. */
Iterator cend() const noexcept { return Iterator (data() + size(), 0); }
Iterator end() const noexcept { return cend(); }
/** Gets a pointer to the contents of the collection as a range of raw 32-bit words. */
/* Gets a pointer to the contents of the collection as a range of raw 32-bit words. */
const uint32_t* data() const noexcept { return storage.data(); }
/** Returns the number of uint32_t words in storage.
/* Returns the number of uint32_t words in storage.
Note that this is likely to be larger than the number of packets
currently being stored, as some packets span multiple words.

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
A base class for classes which convert bytestream midi to other formats.
@tags{Audio}
@ -38,7 +38,7 @@ struct BytestreamInputHandler
virtual void pushMidiData (const void* data, int bytes, double time) = 0;
};
/**
/*
Parses a continuous bytestream and emits complete MidiMessages whenever a full
message is received.
@ -49,7 +49,7 @@ struct BytestreamToBytestreamHandler : public BytestreamInputHandler
BytestreamToBytestreamHandler (MidiInput& i, MidiInputCallback& c)
: input (i), callback (c), concatenator (2048) {}
/**
/*
Provides an `operator()` which can create an input handler for a given
MidiInput.
@ -87,7 +87,7 @@ struct BytestreamToBytestreamHandler : public BytestreamInputHandler
MidiDataConcatenator concatenator;
};
/**
/*
Parses a continuous MIDI 1.0 bytestream, and emits full messages in the requested
UMP format.
@ -98,7 +98,7 @@ struct BytestreamToUMPHandler : public BytestreamInputHandler
BytestreamToUMPHandler (PacketProtocol protocol, Receiver& c)
: recipient (c), dispatcher (protocol, 2048) {}
/**
/*
Provides an `operator()` which can create an input handler for a given
MidiInput.

View file

@ -25,7 +25,7 @@ namespace juce
namespace universal_midi_packets
{
/**
/*
A base class for classes which convert Universal MIDI Packets to other
formats.
@ -39,7 +39,7 @@ struct U32InputHandler
virtual void pushMidiData (const uint32_t* begin, const uint32_t* end, double time) = 0;
};
/**
/*
Parses a continuous stream of U32 words and emits complete MidiMessages whenever a full
message is received.
@ -50,7 +50,7 @@ struct U32ToBytestreamHandler : public U32InputHandler
U32ToBytestreamHandler (MidiInput& i, MidiInputCallback& c)
: input (i), callback (c), dispatcher (2048) {}
/**
/*
Provides an `operator()` which can create an input handler for a given
MidiInput.
@ -91,7 +91,7 @@ struct U32ToBytestreamHandler : public U32InputHandler
ToBytestreamDispatcher dispatcher;
};
/**
/*
Parses a continuous stream of U32 words and emits full messages in the requested
UMP format.
@ -102,7 +102,7 @@ struct U32ToUMPHandler : public U32InputHandler
U32ToUMPHandler (PacketProtocol protocol, Receiver& c)
: recipient (c), converter (protocol) {}
/**
/*
Provides an `operator()` which can create an input handler for a given
MidiInput.