Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions book/src/midi-2-out.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,9 @@ if(auto port = libremidi::midi2::out_default_port())
// Option A: send fixed amount of bytes for most basic cases
midi.send_ump(A, B, C, D); // Overloads exist for 1, 2, 3, 4 uint32_t

// Option B: send a raw byte array.
// This can contain a sequence of UMP messages.
uint32_t bytes[2] = { ... };
midi.send_ump(bytes, sizeof(bytes));
// Option B: send an array of MIDI words. The count is in words, not bytes.
uint32_t words[2] = { ... };
midi.send_ump(words, std::size(words));

// Option C: std::span<uint32_t>
// This allows to pass std::vector, std::array and the likes
Expand All @@ -25,3 +24,10 @@ midi.send_ump(std::span<uint32_t>{ ... your span-compatible data-structure ... }
// The helpers haven't been implemented yet :(
midi.send_ump(libremidi::ump{ /* a message */ });
```

On Windows MIDI Services, a raw output connection batches contiguous, complete
UMPs up to the connection's word limit. Zero NOOP/padding words between packets
are skipped, not zero words inside packets. A truncated packet, a packet larger
than the limit, or a failed transmission stops the send and returns an error.
Earlier batches may already have reached the endpoint; they are never retried.
The hosting side of a virtual port continues to send individual WinRT packets.
1 change: 1 addition & 0 deletions cmake/libremidi.sources.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ target_sources(libremidi PRIVATE
include/libremidi/backends/winmidi/midi_in.hpp
include/libremidi/backends/winmidi/midi_out.hpp
include/libremidi/backends/winmidi/observer.hpp
include/libremidi/backends/winmidi/raw_output.hpp
include/libremidi/backends/winmidi.hpp

include/libremidi/backends/winmm/config.hpp
Expand Down
4 changes: 4 additions & 0 deletions cmake/libremidi.tests.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ target_link_libraries(midiin_test PRIVATE libremidi Catch2::Catch2WithMain)
add_executable(midiout_test tests/unit/midi_out.cpp)
target_link_libraries(midiout_test PRIVATE libremidi Catch2::Catch2WithMain)

add_executable(winmidi_raw_output_test tests/unit/winmidi_raw_output.cpp)
target_link_libraries(winmidi_raw_output_test PRIVATE libremidi Catch2::Catch2WithMain)

add_executable(midifile_read_test tests/unit/midifile_read.cpp)
target_link_libraries(midifile_read_test PRIVATE libremidi Catch2::Catch2WithMain)
target_compile_definitions(midifile_read_test PRIVATE "LIBREMIDI_TEST_CORPUS=\"${CMAKE_CURRENT_SOURCE_DIR}/tests/corpus\"")
Expand Down Expand Up @@ -66,6 +69,7 @@ add_test(NAME conversion_test COMMAND conversion_test)
add_test(NAME error_test COMMAND error_test)
add_test(NAME midiin_test COMMAND midiin_test --allow-running-no-tests)
add_test(NAME midiout_test COMMAND midiout_test --allow-running-no-tests)
add_test(NAME winmidi_raw_output_test COMMAND winmidi_raw_output_test)
add_test(NAME midifile_read_test COMMAND midifile_read_test)
add_test(NAME midifile_write_test COMMAND midifile_write_test)
add_test(NAME midifile_write_tracks_test COMMAND midifile_write_tracks_test)
Expand Down
67 changes: 7 additions & 60 deletions include/libremidi/backends/winmidi/midi_out.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,6 @@ class midi_out_impl final
m_connection = ordinary_connection::acquire(
m_owner.get(configuration.client_name), ep.EndpointDeviceId());
m_endpoint = m_connection->endpoint;
#if LIBREMIDI_WINMIDI_HAS_COM_EXTENSIONS
m_raw_endpoint = m_connection->raw;
#endif

return stdx::error{};
}
Expand Down Expand Up @@ -95,9 +92,6 @@ class midi_out_impl final
{
if (m_connection)
{
#if LIBREMIDI_WINMIDI_HAS_COM_EXTENSIONS
m_raw_endpoint = nullptr;
#endif
m_endpoint = nullptr;
m_connection.reset();
return stdx::error{};
Expand All @@ -118,39 +112,6 @@ class midi_out_impl final
return stdx::error{};
}

std::errc write_raw(const uint32_t* ump, int64_t bytes)
{
#if LIBREMIDI_WINMIDI_HAS_COM_EXTENSIONS
HRESULT ret{};
switch (bytes / 4)
{
case 1:
assert(m_raw_endpoint->ValidateBufferHasOnlyCompleteUmps(1, ump));
ret = m_raw_endpoint->SendMidiMessagesRaw(0, 1, ump);
break;
case 2:
assert(m_raw_endpoint->ValidateBufferHasOnlyCompleteUmps(2, ump));
ret = m_raw_endpoint->SendMidiMessagesRaw(0, 2, ump);
break;
case 3:
assert(m_raw_endpoint->ValidateBufferHasOnlyCompleteUmps(3, ump));
ret = m_raw_endpoint->SendMidiMessagesRaw(0, 3, ump);
break;
case 4:
assert(m_raw_endpoint->ValidateBufferHasOnlyCompleteUmps(4, ump));
ret = m_raw_endpoint->SendMidiMessagesRaw(0, 4, ump);
break;
default:
return std::errc::bad_message;
}
if(ret < 0)
return std::errc::io_error;
return std::errc{};
#else
return write(ump, bytes);
#endif
}

std::errc write(const uint32_t* ump, int64_t bytes)
{
MidiSendMessageResults ret{};
Expand Down Expand Up @@ -179,35 +140,21 @@ class midi_out_impl final

stdx::error send_ump(const uint32_t* message, size_t size) override
{
#if LIBREMIDI_WINMIDI_HAS_VIRTUAL_DEVICE
if(m_virtual)
{
// Virtual port does not support raw API per
// https://github.com/celtera/libremidi/issues/194#issuecomment-4156127901

return segment_ump_stream(message, size,
[this](const uint32_t* ump, int64_t bytes) -> std::errc {
return write(ump, bytes);
}, []() { });
}
else
#if LIBREMIDI_WINMIDI_HAS_COM_EXTENSIONS
// The virtual-device host uses the WinRT plugin path, not a raw connection.
if (m_connection)
return m_connection->send({message, size});
#endif
{
return segment_ump_stream(message, size,
[this](const uint32_t* ump, int64_t bytes) -> std::errc {
return write_raw(ump, bytes);
}, []() { });
}
return segment_ump_stream(message, size, [this](const uint32_t* ump, int64_t bytes) {
return write(ump, bytes);
}, [] { });
}

private:
session_handle m_owner;
std::shared_ptr<ordinary_connection> m_connection;
MidiSession m_session{nullptr}; // private virtual-device connection only
MidiEndpointConnection m_endpoint{nullptr};
#if LIBREMIDI_WINMIDI_HAS_COM_EXTENSIONS
winrt::impl::com_ref<IMidiEndpointConnectionRaw> m_raw_endpoint{};
#endif
#if LIBREMIDI_WINMIDI_HAS_VIRTUAL_DEVICE
midi2v::MidiVirtualDevice m_virtual{nullptr};
#endif
Expand Down
53 changes: 53 additions & 0 deletions include/libremidi/backends/winmidi/raw_output.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#pragma once
#include <libremidi/cmidi2.hpp>
#include <libremidi/error.hpp>

#include <span>

NAMESPACE_LIBREMIDI::winmidi
{
// Both values are obtained at open, never on the send path. The endpoint is borrowed.
struct raw_output
{
uint32_t max_words{};
uint64_t send_immediately{};

stdx::error send(auto& endpoint, std::span<const uint32_t> words) const
{
while (!words.empty())
{
// Like segment_ump_stream, omit NOOP/padding only at a packet boundary.
if (words.front() == 0)
{
words = words.subspan(1);
continue;
}

uint32_t count = 0;
while (count < words.size() && words[count] != 0)
{
const uint32_t n = cmidi2_ump_get_num_bytes(words[count]) / sizeof(uint32_t);
if (n > words.size() - count)
{
if (count == 0)
return std::errc::bad_message;
break;
}
if (n > max_words - count)
{
if (count == 0)
return std::errc::message_size;
break;
}
count += n;
}

// We have already validated the length of each UMP while collecting this prefix.
if (endpoint.SendMidiMessagesRaw(send_immediately, count, words.data()) < 0)
return std::errc::io_error;
words = words.subspan(count);
}
return {};
}
};
}
16 changes: 15 additions & 1 deletion include/libremidi/backends/winmidi/session.hpp
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#pragma once
#include <libremidi/backends/winmidi/connection_pool.hpp>
#include <libremidi/backends/winmidi/helpers.hpp>
#include <libremidi/backends/winmidi/raw_output.hpp>
#include <libremidi/detail/midi_stream_decoder.hpp>
#include <libremidi/detail/ump_stream.hpp>

Expand Down Expand Up @@ -230,10 +231,18 @@ class ordinary_connection
CloseThreadpoolWork(retire);
}

#if LIBREMIDI_WINMIDI_HAS_COM_EXTENSIONS
winrt::com_ptr<IMidiEndpointConnectionRaw> raw;
raw_output output;
#endif

public:
MidiEndpointConnection endpoint{nullptr};
#if LIBREMIDI_WINMIDI_HAS_COM_EXTENSIONS
winrt::com_ptr<IMidiEndpointConnectionRaw> raw;
stdx::error send(std::span<const uint32_t> words) const
{
return output.send(*raw.get(), words);
}
#endif

static std::shared_ptr<ordinary_connection> acquire(
Expand Down Expand Up @@ -268,6 +277,11 @@ class ordinary_connection
attached = true;
}
if (!c->endpoint.Open()) throw winrt::hresult_error{E_FAIL};
#if LIBREMIDI_WINMIDI_HAS_COM_EXTENSIONS
c->output = {
c->raw->GetSupportedMaxMidiWordsPerTransmission(),
MidiClock::TimestampConstantSendImmediately()};
#endif
return c;
});
if (!connection) throw winrt::hresult_error{HRESULT_FROM_WIN32(ERROR_BUSY)};
Expand Down
108 changes: 108 additions & 0 deletions tests/unit/winmidi_raw_output.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
#include "../include_catch.hpp"

#include <libremidi/backends/winmidi/raw_output.hpp>

#include <algorithm>
#include <vector>

namespace
{
struct recording_endpoint
{
struct call
{
uint64_t timestamp;
uint32_t count;
const uint32_t* words;
bool operator==(const call&) const = default;
};
std::vector<call> calls;
size_t fail_on_call{};

int32_t SendMidiMessagesRaw(uint64_t timestamp, uint32_t count, const uint32_t* words)
{
calls.push_back({timestamp, count, words});
return calls.size() == fail_on_call ? -1 : 0;
}
};
}

TEST_CASE("Raw sends use maximal whole-packet prefixes", "[winmidi][raw_output]")
{
// Widths: NOOP, 1, 2, 3, NOOP, 4, 1, NOOP. Zero payload words are not padding.
const uint32_t words[]{0, 0x2590407f, 0x45904000, 0, 0xb0000000, 0, 0,
0, 0x50000000, 0, 0, 0, 0x10f80000, 0};
recording_endpoint endpoint;
const libremidi::winmidi::raw_output output{5, 42};
REQUIRE(output.send(endpoint, words) == stdx::error{});
const std::vector<recording_endpoint::call> expected{
{42, 3, words + 1}, {42, 3, words + 4}, {42, 5, words + 8}};
REQUIRE(endpoint.calls == expected);
}

TEST_CASE("Raw send errors never split a packet or retry a send", "[winmidi][raw_output]")
{
recording_endpoint endpoint;
const uint32_t words[]{0x2590407f, 0x50000000, 0, 0, 0, 0x10f80000};
SECTION("A truncated tail is reported after the complete prefix")
{
const libremidi::winmidi::raw_output output{8, 0};
REQUIRE(output.send(endpoint, {words, 4}) == stdx::error{std::errc::bad_message});
REQUIRE(endpoint.calls == std::vector<recording_endpoint::call>{{0, 1, words}});
}
SECTION("A packet larger than the limit is never sent")
{
const libremidi::winmidi::raw_output output{3, 0};
REQUIRE(output.send(endpoint, words) == stdx::error{std::errc::message_size});
REQUIRE(endpoint.calls == std::vector<recording_endpoint::call>{{0, 1, words}});
}
SECTION("Zero capacity cannot send even a single word")
{
const libremidi::winmidi::raw_output output{0, 0};
REQUIRE(output.send(endpoint, words) == stdx::error{std::errc::message_size});
REQUIRE(endpoint.calls.empty());
}
SECTION("Empty or all-padding streams need no transmission")
{
const uint32_t padding[4]{};
const libremidi::winmidi::raw_output output{4, 0};
REQUIRE(output.send(endpoint, {}) == stdx::error{});
REQUIRE(output.send(endpoint, padding) == stdx::error{});
REQUIRE(endpoint.calls.empty());
}
SECTION("A failed second transmission prevents the third")
{
const libremidi::winmidi::raw_output output{4, 0};
endpoint.fail_on_call = 2;
REQUIRE(output.send(endpoint, words) == stdx::error{std::errc::io_error});
const std::vector<recording_endpoint::call> expected{{0, 1, words}, {0, 4, words + 1}};
REQUIRE(endpoint.calls == expected);
}
}

TEST_CASE("64 KiB SysEx7 uses the negotiated capacity", "[winmidi][raw_output]")
{
constexpr uint32_t data_bytes = 65536;
constexpr uint32_t packets = (data_bytes + 5) / 6;
std::vector<uint32_t> words(packets * 2);
for (uint32_t i = 0; i < packets; ++i)
{
const bool last = i + 1 == packets;
const uint32_t status = i == 0 ? 1 : last ? 3 : 2;
const uint32_t bytes = last ? data_bytes - i * 6 : 6;
words[2 * i] = 0x35000000 | (status << 20) | (bytes << 16);
}

recording_endpoint endpoint;
const libremidi::winmidi::raw_output output{127, 0};
REQUIRE(output.send(endpoint, words) == stdx::error{});
REQUIRE(endpoint.calls.size() == 174);
size_t offset = 0;
for (const auto& call : endpoint.calls)
{
REQUIRE(call.words == words.data() + offset);
REQUIRE(call.count == std::min<size_t>(126, words.size() - offset));
offset += call.count;
}
REQUIRE(offset == words.size());
}
Loading