From 90d5b8b4a064420d74678654e94ea4755b377f21 Mon Sep 17 00:00:00 2001 From: Hans-Christoph Steiner Date: Thu, 15 Dec 2005 00:57:02 +0000 Subject: checking in missing files on behalf of Miller (cleared it with him first). The files are from portmidi17nov04.zip svn path=/trunk/; revision=4216 --- pd/portmidi/pm_win/README_WIN.txt | 183 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 pd/portmidi/pm_win/README_WIN.txt (limited to 'pd/portmidi/pm_win/README_WIN.txt') diff --git a/pd/portmidi/pm_win/README_WIN.txt b/pd/portmidi/pm_win/README_WIN.txt new file mode 100644 index 00000000..df120e96 --- /dev/null +++ b/pd/portmidi/pm_win/README_WIN.txt @@ -0,0 +1,183 @@ +File: PortMidi Win32 Readme +Author: Belinda Thom, June 16 2002 +Revised by: Roger Dannenberg, June 2002, May 2004 + +============================================================================= +USING PORTMIDI: +============================================================================= + +PortMidi has been created using a DLL because the Win32 MMedia API doesn't +handle midiInput properly in the debugger. Specifically, it doesn't clean up +after itself if the user (i.e. you, a PortMidi application) hasn't explicitly +closed all open midi input devices. This lack of cleanup can lead to much +pain and agony, including the blue-screen-of-death. This situation becomes +increasingly unacceptable when you are debugging your code, so a portMidi DLL +seemed to be the most elegant solution. + +Using Microsoft Visual C++ project files (provided with PortMidi), there +are two configurations of the PortMidi library. The Debug version is +intended for debugging, especially in a console application. The Debug +version enables some extra error checking and outputs some text as well +as a prompt to type ENTER so that you don't lose any debugging text when +the program exits. You can turn off this extra debugging info by taking +out the compile-time definition for DEBUG. This debugging version also +defines PM_CHECK_ERRORS, which forces a check for error return codes from +every call to PortMidi. You can disable this checking (especially if you +want to handle error codes in your own way) by removing PM_CHECK_ERRORS +from the predefined symbols list in the Settings dialog box. + +PortMidi is designed to run without a console and should work perfectly +well within a graphical user interface application. The Release version +is both optimized and lacking the debugging printout code of the Debug +version. + +Read the portmidi.h file for PortMidi API details on using the PortMidi API. +See <...>\pm_dll_test\test.c or <...>\multithread\test.c for usage examples. + +============================================================================= +TO INSTALL PORTMIDI: +============================================================================= +1) download portmidi.zip + +2) unzip portmidi.zip into directory: <...>\portmidi + +============================================================================= +TO COMPILE PORTMIDI: +============================================================================= + +3) go to this directory + +4) click on the portmidi.dsw workspace + +5) the following projects exist within this workspace: + - portmidi (the PortMidi library) + - pm_dll (the dll library used to close midi ports on program exit) + - porttime (a small portable library implementing timer facilities) + - test (simple midi I/O testing) + - multithread (an example illustrating low-latency MIDI processing + using a dedicated low-latency thread) + - sysex (simple sysex message I/O testing) + - latency (uses porttime to measure system latency) + +6) verify that all project settings are for Win32 Debug release: + - hit Alt-F7 + - highlight all three projects in left part of Project Settings window; + - "Settings For" should say "Win32 Debug" + +7) set pm_dll as the active project (e.g. Project->Select Active Project) + +8) use Build->Batch Build ... to build everything in the project + +9) The settings for these projects were distributed in the zip file, so + compile should just work. + +10) IMPORTANT! PortMidi uses a DLL, pm_dll.dll, but there is no simple way + to set up projects to use pm_dll. THEREFORE, you need to copy DLLs + as follows (you can do this with <...>\portmidi\pm_win\copy-dll.bat): + copy <...>\portmidi\pm_win\Debug\pm_dll.dll to: + <...>\portmidi\pm_test\latencyDebug\pm_dll.dll + <...>\portmidi\pm_test\midithreadDebug\pm_dll.dll + <...>\portmidi\pm_test\sysexDebug\pm_dll.dll + <...>\portmidi\pm_test\testDebug\pm_dll.dll + <...>\portmidi\pm_test\midithruDebug\pm_dll.dll + and copy <...>\portmidi\pm_win\Release\pm_dll.dll to: + <...>\portmidi\pm_test\latencyRelease\pm_dll.dll + <...>\portmidi\pm_test\midithreadRelease\pm_dll.dll + <...>\portmidi\pm_test\sysexRelease\pm_dll.dll + <...>\portmidi\pm_test\testRelease\pm_dll.dll + <...>\portmidi\pm_test\midithruRelease\pm_dll.dll + each time you rebuild the pm_dll project, these copies must be redone! + + Since Windows will look in the executable directory for DLLs, we + recommend that you always install a copy of pm_dll.dll (either the + debug version or the release version) in the same directory as the + application using PortMidi. The release DLL is about 40KB. This will + ensure that the application uses the correct DLL. + +11) run test project; use the menu that shows up from the command prompt to + test that portMidi works on your system. tests include: + - verify midi output works + - verify midi input works + - verify midi input w/midi thru works + +12) run other projects if you wish: sysex, latency, and midithread + +============================================================================ +TO CREATE YOUR OWN PORTMIDI CLIENT APPLICATION: +============================================================================ + +NOTE: this section needs to be reviewed and tested. My suggestion would +be to copy the test project file (test.dsp) and modify it. -RBD + +The easiest way is to start a new project w/in the portMidi workspace: + +1) To open new project: + - File->New->Projects + - Location: <...>\portmidi\ + - check Add to current workspace + - select Win32 Console Application (recommended for now) + - do *NOT* select the "make dependency" box (you will explicitly do this + in the next step) + - Click OK + - Select "An Empty Project" and click Finish + +2) Now this project will be the active project. Make it explicitly depend + on PortMidi dll: + - Project->Dependencies + - Click pm_dll + +3) Important! in order to be able to use portMidi DLL from your new project + and set breakpoints, copy following files from <...>\pm_dll\Debug into + <...>\\Debug directory: + pm_dll.lib + pm_dll.dll + each time you rebuild pm_dll, these copies must be redone! + +4) add whatever files you wish to add to your new project, using portMidi + calls as desired (see USING PORTMIDI at top of this readme) + +5) when you include portMidi files, do so like this: + - #include "..\pm_dll\portmidi.h" + - etc. + +6) build and run your project + +============================================================================ +DESIGN NOTES +============================================================================ + +The DLL is used so that PortMidi can (usually) close open devices when the +program terminates. Failure to close input devices under WinNT, Win2K, and +probably later systems causes the OS to crash. + +This is accomplished with a .LIB/.DLL pair, linking to the .LIB +in order to access functions in the .DLL. + +PortMidi for Win32 exists as a simple library, +with Win32-specific code in pmwin.c and MM-specific code in pmwinmm.c. +pmwin.c uses a DLL in pmdll.c to call Pm_Terminate() when the program +exits to make sure that all MIDI ports are closed. + +Orderly cleanup after errors are encountered is based on a fixed order of +steps and state changes to reflect each step. Here's the order: + +To open input: + initialize return value to NULL + - allocate the PmInternal strucure (representation of PortMidiStream) + return value is (non-null) PmInternal structure + - allocate midi buffer + set buffer field of PmInternal structure + - call system-dependent open code + - allocate midiwinmm_type for winmm dependent data + set descriptor field of PmInternal structure + - open device + set handle field of midiwinmm_type structure + - allocate buffer 1 for sysex + buffer is added to input port + - allocate buffer 2 for sysex + buffer is added to input port + - return + - return + + + -- cgit v1.2.1