1 files changed, 88 insertions, 0 deletions
diff --git a/portmidi/README.txt b/portmidi/README.txt
new file mode 100755
index 0000000..e09aa2e
--- /dev/null
+++ b/portmidi/README.txt
@@ -0,0 +1,88 @@
+README for PortMidi
+
+Roger B. Dannenberg
+
+Documentation for PortMidi is found in pm_common/portmidi.h.
+Documentation in HTML is available at portmidi.github.io/portmidi_docs/
+
+Additional documentation:
+  - README.md (overview, how to build, what's new)
+  - Windows: see pm_win/README_WIN.txt and pm_win/debugging_dlls.txt
+  - Linux: see pm_linux/README_LINUX.txt
+  - Mac OSX: see pm_mac/README_MAC.txt
+  - Other Languages: look for other repos at github.com/PortMidi,
+        and search README.md for pointers to other projects.
+
+---------- some notes on the design of PortMidi ----------
+
+POINTERS VS DEVICE NUMBERS
+
+When you open a MIDI port, PortMidi allocates a structure to
+maintain the state of the open device. Since every device is
+also listed in a table, you might think it would be simpler to
+use the table index rather than a pointer to identify a device.
+This would also help with error checking (it's hard to make
+sure a pointer is valid). PortMidi's design parallels that of
+PortAudio.
+
+ERROR HANDLING
+
+Error handling turned out to be much more complicated than expected.
+PortMidi functions return error codes that the caller can check.
+In addition, errors may occur asynchronously due to MIDI input.
+However, for Windows, there are virtually no errors that can
+occur if the code is correct and not passing bogus values. One
+exception is an error that the system is out of memory, but my
+guess is that one is unlikely to recover gracefully from that.
+Therefore, all errors in callbacks are guarded by assert(), which
+means not guarded at all in release configurations.
+
+Ordinarily, the caller checks for an error code. If the error is
+system-dependent, pmHostError is returned and the caller can
+call Pm_GetHostErrorText to get a text description of the error.
+
+Host error codes are system-specific and are recorded in the
+system-specific data allocated for each open MIDI port.
+However, if an error occurs on open or close,
+we cannot store the error with the device because there will be
+no device data (assuming PortMidi cleans up after devices that
+are not open). For open and close, we will convert the error
+to text, copy it to a global string, and set pm_hosterror, a
+global flag.
+
+Similarly, whenever a Read or Write operation returns pmHostError,
+the corresponding error string is copied to a global string
+and pm_hosterror is set. This makes getting error strings
+simple and uniform, although it does cost a string copy and some
+overhead even if the user does not want to look at the error data.
+
+The system-specific Read, Write, Poll, etc. implementations should
+check for asynchronous errors and return immediately if one is
+found so that these get reported. This happens in the Mac OS X
+code, where lots of things are happening in callbacks, but again,
+in Windows, there are no error codes recorded in callbacks.
+
+DEBUGGING
+
+If you are building a console application for research, we suggest
+compiling with the option PM_CHECK_ERRORS. This will insert a
+check for error return values at the end of each PortMidi
+function. If an error is encountered, a text message is printed
+using printf(), the user is asked to type ENTER, and then exit(-1)
+is called to clean up and terminate the program.
+
+You should not use PM_CHECK_ERRORS if printf() does not work
+(e.g. this is not a console application under Windows, or there
+is no visible console on some other OS), and you should not use
+PM_CHECK_ERRORS if you intend to recover from errors rather than
+abruptly terminate the program.
+
+The Windows version (and perhaps others) also offers a DEBUG
+compile-time option. See README_WIN.txt.
+
+RELEASE
+
+To make a new release, update VERSION variable in CMakeLists.txt.
+
+Update CHANGELOG.txt. What's new?
+