From 40a899bd6ee536eae093337bf2d0dcc8db4e46f1 Mon Sep 17 00:00:00 2001 From: Mitja Felicijan Date: Mon, 7 Oct 2024 19:30:56 +0200 Subject: Moved example code examples folder --- portmidi/README.txt | 88 ----------------------------------------------------- 1 file changed, 88 deletions(-) delete mode 100755 portmidi/README.txt (limited to 'portmidi/README.txt') diff --git a/portmidi/README.txt b/portmidi/README.txt deleted file mode 100755 index e09aa2e..0000000 --- a/portmidi/README.txt +++ /dev/null @@ -1,88 +0,0 @@ -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? - -- cgit v1.2.3