README.txt (3724B)
1 README for PortMidi 2 3 Roger B. Dannenberg 4 5 VERSION: please use "svn info" to get info. 6 7 Documentation for PortMidi is found in pm_common/portmidi.h. 8 9 Additional documentation: 10 - Windows: see pm_win/README_WIN.txt and pm_win/debugging_dlls.txt 11 - Linux: see pm_linux/README_LINUX.txt 12 - Mac OSX: see pm_mac/README_MAC.txt 13 - Common Lisp: see pm_cl/README_CL.txt 14 - Eclipse: see portmidi_cdt.zip (this was contributed as is; the dlls here 15 are now -- Sep 09 -- out of date. What is really needed is a script 16 to generate this release automatically so we can maintain it.) 17 - C-Sharp: see pm_csharp.zip (also contributed as is) 18 19 ---------- some notes on the design of PortMidi ---------- 20 21 POINTERS VS DEVICE NUMBERS 22 23 When you open a MIDI port, PortMidi allocates a structure to 24 maintain the state of the open device. Since every device is 25 also listed in a table, you might think it would be simpler to 26 use the table index rather than a pointer to identify a device. 27 This would also help with error checking (it's hard to make 28 sure a pointer is valid). PortMidi's design parallels that of 29 PortAudio. 30 31 ERROR HANDLING 32 33 Error handling turned out to be much more complicated than expected. 34 PortMidi functions return error codes that the caller can check. 35 In addition, errors may occur asynchronously due to MIDI input. 36 However, for Windows, there are virtually no errors that can 37 occur if the code is correct and not passing bogus values. One 38 exception is an error that the system is out of memory, but my 39 guess is that one is unlikely to recover gracefully from that. 40 Therefore, all errors in callbacks are guarded by assert(), which 41 means not guarded at all in release configurations. 42 43 Ordinarily, the caller checks for an error code. If the error is 44 system-dependent, pmHostError is returned and the caller can 45 call Pm_GetHostErrorText to get a text description of the error. 46 47 Host error codes are system-specific and are recorded in the 48 system-specific data allocated for each open MIDI port. 49 However, if an error occurs on open or close, 50 we cannot store the error with the device because there will be 51 no device data (assuming PortMidi cleans up after devices that 52 are not open). For open and close, we will convert the error 53 to text, copy it to a global string, and set pm_hosterror, a 54 global flag. 55 56 Similarly, whenever a Read or Write operation returns pmHostError, 57 the corresponding error string is copied to a global string 58 and pm_hosterror is set. This makes getting error strings 59 simple and uniform, although it does cost a string copy and some 60 overhead even if the user does not want to look at the error data. 61 62 The system-specific Read, Write, Poll, etc. implementations should 63 check for asynchronous errors and return immediately if one is 64 found so that these get reported. This happens in the Mac OS X 65 code, where lots of things are happening in callbacks, but again, 66 in Windows, there are no error codes recorded in callbacks. 67 68 DEBUGGING 69 70 If you are building a console application for research, we suggest 71 compiling with the option PM_CHECK_ERRORS. This will insert a 72 check for error return values at the end of each PortMidi 73 function. If an error is encountered, a text message is printed 74 using printf(), the user is asked to type ENTER, and then exit(-1) 75 is called to clean up and terminate the program. 76 77 You should not use PM_CHECK_ERRORS if printf() does not work 78 (e.g. this is not a console application under Windows, or there 79 is no visible console on some other OS), and you should not use 80 PM_CHECK_ERRORS if you intend to recover from errors rather than 81 abruptly terminate the program. 82 83 The Windows version (and perhaps others) also offers a DEBUG 84 compile-time option. See README_WIN.txt.