Update of /cvsroot/audacity/lib-src/portmidi
In directory 23jxhf1.ch3.sourceforge.com:/tmp/cvs-serv11472/lib-src/portmidi
Added Files:
CHANGELOG.txt Doxyfile license.txt portmidi-VC9.vcproj
portmidi.vcproj portmusic_logo.png README.txt
Log Message:
Added the 'portmidi' library (used for MIDI playback) to the repository.
Edited AudioIO.cpp to allow for MIDI playback (all changes are wrapped within
EXPERIMENTAL_MIDI_OUT).
Edited MidiIOprefs.cpp to allow changing MIDI devices via the MIDI preferences
panel.
Other various MIDI-related bug fixes in portmidi, portsmf, and libscorealign.
--- NEW FILE: Doxyfile ---
# Doxyfile 1.5.5
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project
#
# All text after a hash (#) is considered a comment and will be ignored
# The format is:
# TAG = value [value, ...]
# For lists items can also be appended using:
# TAG += value [value, ...]
# Values that contain spaces should be placed between quotes (" ")
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
# This tag specifies the encoding used for all characters in the config file
# that follow. The default is UTF-8 which is also the encoding used for all
# text before the first occurrence of this tag. Doxygen uses libiconv (or the
[...1433 lines suppressed...]
# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
# generate a legend page explaining the meaning of the various boxes and
# arrows in the dot generated graphs.
GENERATE_LEGEND = YES
# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
# remove the intermediate dot files that are used to generate
# the various graphs.
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::additions related to the search engine
#---------------------------------------------------------------------------
# The SEARCHENGINE tag specifies whether or not a search engine should be
# used. If set to NO the values of all tags below this one will be ignored.
SEARCHENGINE = NO
--- NEW FILE: CHANGELOG.txt ---
/* CHANGELOG FOR PORTMIDI
*
* 02Jan09 Roger Dannenberg
* - Created Java interface and wrote PmDefaults application to set
* values for Pm_GetDefaultInputDeviceID() and
* Pm_GetDefaultOutputDeviceID(). Other fixes.
*
* 19Jun08 Roger Dannenberg and Austin Sung
* - Removed USE_DLL_FOR_CLEANUP -- Windows 2000 through Vista seem to be
* fixed now, and can recover if MIDI ports are left open
* - Various other minor patches
*
* 17Jan07 Roger Dannenberg
* - Lots more help for Common Lisp user in pm_cl
* - Minor fix to eliminate a compiler warning
* - Went back to single library in OS X for both portmidi and porttime
*
* 16Jan07 Roger Dannenberg
* - OOPS! fixed bug where short messages all had zero data
* - Makefile.osx static library build now makes universal (i386 + ppc)
* binaries
*
* 15Jan07 Roger Dannenberg
* - multiple rewrites of sysex handling code to take care of
* error-handling, embedded messages, message filtering,
* driver bugs, and host limitations.
* - fixed windows to use dwBufferLength rather than
* dwBytesRecorded for long buffer output (fix by Nigel Brown)
* - Win32 MME code always appends an extra zero to long buffer
* output to work around a problem with earlier versions of Midi Yoke
* - Added mm, a command line Midi Monitor to pm_test suite
* - Revised copyright notice to match PortAudio/MIT license (requests
* are moved out of the license proper and into a separate paragraph)
*
* 18Oct06 Roger Dannenberg
* - replace FIFO in pmutil with Light Pipe-based multiprocessor-safe alg.
* - replace FIFO in portmidi.c with PmQueue from pmutil
*
* 07Oct06 cpr & Roger Dannenberg
* - overhaul of CoreMIDI input to handle running status and multiple
* - messages per packet, with additional error detection
* - added Leigh Smith and Rick Taube support for Common Lisp and
* - dynamic link libraries in OSX
* - initialize static global seq = NULL in pmlinuxalsa.c
*
* 05Sep06 Sebastien Frippiat
* - check if (ALSA) seq exists before closing it in pm_linuxalsa_term()
*
* 05Sep06 Andreas Micheler and Cecilio
* - fixed memory leak by freeing someo objects in pm_winmm_term()
* - and another leak by freeing descriptors in Pm_Terminate()
*
* 23Aug06 RBD
* - various minor fixes
*
* 04Nov05 Olivier Tristan
* - changes to OS X to properly retrieve real device name on CoreMidi
*
* 19Jul05 Roger Dannenberg
* - included pmBufferMaxSize in Pm_GetErrorText()
*
* 23Mar05 Torgier Strand Henriksen
* - cleaner termination of porttime thread under Linux
*
* 15Nov04 Ben Allison
* - sysex output now uses one buffer/message and reallocates buffer
* - if needed
* - filters expanded for many message types and channels
* - detailed changes are as follows:
* ------------- in pmwinmm.c --------------
* - new #define symbol: OUTPUT_BYTES_PER_BUFFER
* - change SYSEX_BYTES_PER_BUFFER to 1024
* - added MIDIHDR_BUFFER_LENGTH(x) to correctly count midihdr buffer length
* - change MIDIHDR_SIZE(x) to (MIDIHDR_BUFFER_LENGTH(x) + sizeof(MIDIHDR))
* - change allocate_buffer to use new MIDIHDR_BUFFER_LENGTH macro
* - new macros for MIDIHDR_SYSEX_SIZE and MIDIHDR_SYSEX_BUFFER_LENGTH
* - similar to above, but counts appropriately for sysex messages
* - added the following members to midiwinmm_struct for sysex data:
* - LPMIDIHDR *sysex_buffers; ** pool of buffers for sysex data **
* - int num_sysex_buffers; ** how many sysex buffers **
* - int next_sysex_buffer; ** index of next sysexbuffer to send **
* - HANDLE sysex_buffer_signal; ** to wait for free sysex buffer **
* - duplicated allocate_buffer, alocate_buffers and get_free_output_buffer
* - into equivalent sysex_buffer form
* - changed winmm_in_open to initialize new midiwinmm_struct members and
* - to use the new allocate_sysex_buffer() function instead of
* - allocate_buffer()
* - changed winmm_out_open to initialize new members, create sysex buffer
* - signal, and allocate 2 sysex buffers
* - changed winmm_out_delete to free sysex buffers and shut down the sysex
* - buffer signal
* - create new function resize_sysex_buffer which resizes m->hdr to the
* - passed size, and corrects the midiwinmm_struct accordingly.
* - changed winmm_write_byte to use new resize_sysex_buffer function,
* - if resize fails, write current buffer to output and continue
* - changed winmm_out_callback to use buffer_signal or sysex_buffer_signal
* - depending on which buffer was finished
* ------------- in portmidi.h --------------
* - added pmBufferMaxSize to PmError to indicate that the buffer would be
* - too large for the underlying API
* - added additional filters
* - added prototype, documentation, and helper macro for Pm_SetChannelMask
* ------------- in portmidi.c --------------
* - added pm_status_filtered() and pm_realtime_filtered() functions to
* separate filtering logic from buffer logic in pm_read_short
* - added Pm_SetChannelMask function
* - added pm_channel_filtered() function
* ------------- in pminternal.h --------------
* - added member to PortMidiStream for channel mask
*
* 25May04 RBD
* - removed support for MIDI THRU
* - moved filtering from Pm_Read to pm_enqueue to avoid buffer ovfl
* - extensive work on Mac OS X port, especially sysex and error handling
*
* 18May04 RBD
* - removed side-effects from assert() calls. Now you can disable assert().
* - no longer check pm_hosterror everywhere, fixing a bug where an open
* failure could cause a write not to work on a previously opened port
* until you call Pm_GetHostErrorText().
* 16May04 RBD and Chris Roberts
* - Some documentation wordsmithing in portmidi.h
* - Dynamically allocate port descriptor structures
* - Fixed parameter error in midiInPrepareBuffer and midiInAddBuffer.
*
* 09Oct03 RBD
* - Changed Thru handling. Now the client does all the work and the client
* must poll or read to keep thru messages flowing.
*
* 31May03 RBD
* - Fixed various bugs.
* - Added linux ALSA support with help from Clemens Ladisch
* - Added Mac OS X support, implemented by Jon Parise, updated and
* integrated by Andrew Zeldis and Zico Kolter
* - Added latency program to build histogram of system latency using PortTime.
*
* 30Jun02 RBD Extensive rewrite of sysex handling. It works now.
* Extensive reworking of error reporting and error text -- no
* longer use dictionary call to delete data; instead, Pm_Open
* and Pm_Close clean up before returning an error code, and
* error text is saved in a system-independent location.
* Wrote sysex.c to test sysex message handling.
*
* 15Jun02 BCT changes:
* - Added pmHostError text handling.
* - For robustness, check PortMidi stream args not NULL.
* - Re-C-ANSI-fied code (changed many C++ comments to C style)
* - Reorganized code in pmwinmm according to input/output functionality (made
* cleanup handling easier to reason about)
* - Fixed Pm_Write calls (portmidi.h says these should not return length but
Pm_Error)
* - Cleaned up memory handling (now system specific data deleted via
dictionary
* call in PortMidi, allows client to query host errors).
* - Added explicit asserts to verify various aspects of pmwinmm
implementation behaves as
* logic implies it should. Specifically: verified callback routines not
reentrant and
* all verified status for all unchecked Win32 MMedia API calls perform
successfully
* - Moved portmidi initialization and clean-up routines into DLL to fix Win32
MMedia API
* bug (i.e. if devices not explicitly closed, must reboot to debug
application further).
* With this change, clients no longer need explicitly call Pm_Initialize,
Pm_Terminate, or
* explicitly Pm_Close open devices when using WinMM version of PortMidi.
*
* 23Jan02 RBD Fixed bug in pmwinmm.c thru handling
*
* 21Jan02 RBD Added tests in Pm_OpenInput() and Pm_OpenOutput() to prevent
* opening an input as output and vice versa.
* Added comments and documentation.
* Implemented Pm_Terminate().
*
*/
--- NEW FILE: portmusic_logo.png ---
(This appears to be a binary file; contents omitted.)
--- NEW FILE: portmidi.vcproj ---
<?xml version="1.0" encoding="Windows-1252"?>
<VisualStudioProject
ProjectType="Visual C++"
Version="9.00"
Name="portmidi"
ProjectGUID="{33E3B196-B9F4-4D0A-85E1-31C7BBD4967A}"
TargetFrameworkVersion="131072"
>
<Platforms>
<Platform
Name="Win32"
/>
</Platforms>
<ToolFiles>
</ToolFiles>
<Configurations>
<Configuration
Name="Debug|Win32"
OutputDirectory="$(SolutionDir)$(ConfigurationName)"
IntermediateDirectory="$(ConfigurationName)"
ConfigurationType="4"
InheritedPropertySheets="$(VCInstallDir)VCProjectDefaults\UpgradeFromVC60.vsprops"
UseOfMFC="0"
ATLMinimizesCRunTimeLibraryUsage="false"
CharacterSet="2"
>
<Tool
Name="VCPreBuildEventTool"
/>
<Tool
Name="VCCustomBuildTool"
/>
<Tool
Name="VCXMLDataGeneratorTool"
/>
<Tool
Name="VCWebServiceProxyGeneratorTool"
/>
<Tool
Name="VCMIDLTool"
/>
<Tool
Name="VCCLCompilerTool"
Optimization="0"
AdditionalIncludeDirectories="pm_common,porttime,pm_win"
PreprocessorDefinitions="WIN32;_DEBUG;_LIB;DEBUG;PM_CHECK_ERRORS"
StringPooling="true"
MinimalRebuild="false"
BasicRuntimeChecks="3"
RuntimeLibrary="3"
EnableFunctionLevelLinking="true"
PrecompiledHeaderFile=""
AssemblerListingLocation=""
ObjectFile="$(IntDir)\"
ProgramDataBaseFileName="$(IntDir)\vc90.pdb"
WarningLevel="3"
SuppressStartupBanner="true"
DebugInformationFormat="4"
CompileAs="0"
DisableSpecificWarnings="4996"
/>
<Tool
Name="VCManagedResourceCompilerTool"
/>
<Tool
Name="VCResourceCompilerTool"
PreprocessorDefinitions="_DEBUG"
Culture="1033"
/>
<Tool
Name="VCPreLinkEventTool"
/>
<Tool
Name="VCLibrarianTool"
OutputFile="$(OutDir)\$(ProjectName).lib"
SuppressStartupBanner="true"
/>
<Tool
Name="VCALinkTool"
/>
<Tool
Name="VCXDCMakeTool"
/>
<Tool
Name="VCBscMakeTool"
SuppressStartupBanner="true"
OutputFile="$(OutDir)/$(ProjectName).bsc"
/>
<Tool
Name="VCFxCopTool"
/>
<Tool
Name="VCPostBuildEventTool"
/>
</Configuration>
<Configuration
Name="Release|Win32"
OutputDirectory="$(SolutionDir)$(ConfigurationName)"
IntermediateDirectory="$(ConfigurationName)"
ConfigurationType="4"
InheritedPropertySheets="$(VCInstallDir)VCProjectDefaults\UpgradeFromVC60.vsprops"
UseOfMFC="0"
ATLMinimizesCRunTimeLibraryUsage="false"
CharacterSet="2"
WholeProgramOptimization="1"
>
<Tool
Name="VCPreBuildEventTool"
/>
<Tool
Name="VCCustomBuildTool"
/>
<Tool
Name="VCXMLDataGeneratorTool"
/>
<Tool
Name="VCWebServiceProxyGeneratorTool"
/>
<Tool
Name="VCMIDLTool"
/>
<Tool
Name="VCCLCompilerTool"
Optimization="2"
InlineFunctionExpansion="0"
AdditionalIncludeDirectories="pm_common,porttime,pm_win"
PreprocessorDefinitions="WIN32;_LIB"
StringPooling="true"
RuntimeLibrary="2"
EnableFunctionLevelLinking="true"
PrecompiledHeaderFile=""
AssemblerListingLocation=""
ObjectFile="$(IntDir)\"
ProgramDataBaseFileName="$(IntDir)\vc90.pdb"
WarningLevel="3"
SuppressStartupBanner="true"
CompileAs="0"
/>
<Tool
Name="VCManagedResourceCompilerTool"
/>
<Tool
Name="VCResourceCompilerTool"
PreprocessorDefinitions="NDEBUG"
Culture="1033"
/>
<Tool
Name="VCPreLinkEventTool"
/>
<Tool
Name="VCLibrarianTool"
OutputFile="$(OutDir)\$(ProjectName).lib"
SuppressStartupBanner="true"
/>
<Tool
Name="VCALinkTool"
/>
<Tool
Name="VCXDCMakeTool"
/>
<Tool
Name="VCBscMakeTool"
SuppressStartupBanner="true"
OutputFile=".\pm_win\Release/portmidi.bsc"
/>
<Tool
Name="VCFxCopTool"
/>
<Tool
Name="VCPostBuildEventTool"
/>
</Configuration>
</Configurations>
<References>
</References>
<Files>
<Filter
Name="Source Files"
Filter="cpp;c;cxx;rc;def;r;odl;idl;hpj;bat"
>
<File
RelativePath="pm_common\pmutil.c"
>
<FileConfiguration
Name="Debug|Win32"
>
<Tool
Name="VCCLCompilerTool"
AdditionalIncludeDirectories=""
PreprocessorDefinitions=""
/>
</FileConfiguration>
<FileConfiguration
Name="Release|Win32"
>
<Tool
Name="VCCLCompilerTool"
AdditionalIncludeDirectories=""
PreprocessorDefinitions=""
/>
</FileConfiguration>
</File>
<File
RelativePath="pm_win\pmwin.c"
>
<FileConfiguration
Name="Debug|Win32"
>
<Tool
Name="VCCLCompilerTool"
AdditionalIncludeDirectories=""
PreprocessorDefinitions=""
/>
</FileConfiguration>
<FileConfiguration
Name="Release|Win32"
>
<Tool
Name="VCCLCompilerTool"
AdditionalIncludeDirectories=""
PreprocessorDefinitions=""
/>
</FileConfiguration>
</File>
<File
RelativePath="pm_win\pmwinmm.c"
>
<FileConfiguration
Name="Debug|Win32"
>
<Tool
Name="VCCLCompilerTool"
AdditionalIncludeDirectories=""
PreprocessorDefinitions=""
/>
</FileConfiguration>
<FileConfiguration
Name="Release|Win32"
>
<Tool
Name="VCCLCompilerTool"
AdditionalIncludeDirectories=""
PreprocessorDefinitions=""
/>
</FileConfiguration>
</File>
<File
RelativePath="pm_common\portmidi.c"
>
<FileConfiguration
Name="Debug|Win32"
>
<Tool
Name="VCCLCompilerTool"
AdditionalIncludeDirectories=""
PreprocessorDefinitions=""
/>
</FileConfiguration>
<FileConfiguration
Name="Release|Win32"
>
<Tool
Name="VCCLCompilerTool"
AdditionalIncludeDirectories=""
PreprocessorDefinitions=""
/>
</FileConfiguration>
</File>
<File
RelativePath=".\porttime\porttime.c"
>
</File>
<File
RelativePath=".\porttime\ptwinmm.c"
>
</File>
</Filter>
<Filter
Name="Header Files"
Filter="h;hpp;hxx;hm;inl"
>
<File
RelativePath="pm_common\pminternal.h"
>
</File>
<File
RelativePath="pm_common\pmutil.h"
>
</File>
<File
RelativePath="pm_win\pmwinmm.h"
>
</File>
<File
RelativePath="pm_common\portmidi.h"
>
</File>
<File
RelativePath=".\porttime\porttime.h"
>
</File>
</Filter>
</Files>
<Globals>
</Globals>
</VisualStudioProject>
--- NEW FILE: portmidi-VC9.vcproj ---
<?xml version="1.0" encoding="Windows-1252"?>
<VisualStudioProject
ProjectType="Visual C++"
Version="9.00"
Name="PortMidi"
ProjectGUID="{33E3B196-B9F4-4D0A-85E1-31C7BBD4967A}"
TargetFrameworkVersion="131072"
>
<Platforms>
<Platform
Name="Win32"
/>
</Platforms>
<ToolFiles>
</ToolFiles>
<Configurations>
<Configuration
Name="Debug VC9|Win32"
OutputDirectory=".\pm_win\Debug VC9"
IntermediateDirectory=".\pm_win\Debug VC9"
ConfigurationType="4"
InheritedPropertySheets="$(VCInstallDir)VCProjectDefaults\UpgradeFromVC60.vsprops"
UseOfMFC="0"
ATLMinimizesCRunTimeLibraryUsage="false"
CharacterSet="2"
>
<Tool
Name="VCPreBuildEventTool"
/>
<Tool
Name="VCCustomBuildTool"
/>
<Tool
Name="VCXMLDataGeneratorTool"
/>
<Tool
Name="VCWebServiceProxyGeneratorTool"
/>
<Tool
Name="VCMIDLTool"
/>
<Tool
Name="VCCLCompilerTool"
Optimization="0"
AdditionalIncludeDirectories="pm_common,porttime,pm_win"
PreprocessorDefinitions="_LIB;DEBUG;PM_CHECK_ERRORS;WIN32;_DEBUG"
MinimalRebuild="true"
BasicRuntimeChecks="3"
RuntimeLibrary="1"
PrecompiledHeaderFile=".\$(OutDir)\portmidi.pch"
AssemblerListingLocation=".\$(OutDir)\"
ObjectFile=".\$(OutDir)\"
ProgramDataBaseFileName=".\$(OutDir)\"
WarningLevel="3"
SuppressStartupBanner="true"
DebugInformationFormat="4"
/>
<Tool
Name="VCManagedResourceCompilerTool"
/>
<Tool
Name="VCResourceCompilerTool"
PreprocessorDefinitions="_DEBUG"
Culture="1033"
/>
<Tool
Name="VCPreLinkEventTool"
/>
<Tool
Name="VCLibrarianTool"
OutputFile=".\$(OutDir)\portmidi.lib"
SuppressStartupBanner="true"
/>
<Tool
Name="VCALinkTool"
/>
<Tool
Name="VCXDCMakeTool"
/>
<Tool
Name="VCBscMakeTool"
SuppressStartupBanner="true"
OutputFile=".\$(OutDir)\portmidi.bsc"
/>
<Tool
Name="VCFxCopTool"
/>
<Tool
Name="VCPostBuildEventTool"
/>
</Configuration>
<Configuration
Name="Release VC9|Win32"
OutputDirectory=".\pm_win\Release VC9"
IntermediateDirectory=".\pm_win\Release VC9"
ConfigurationType="4"
InheritedPropertySheets="$(VCInstallDir)VCProjectDefaults\UpgradeFromVC60.vsprops"
UseOfMFC="0"
ATLMinimizesCRunTimeLibraryUsage="false"
CharacterSet="2"
>
<Tool
Name="VCPreBuildEventTool"
/>
<Tool
Name="VCCustomBuildTool"
/>
<Tool
Name="VCXMLDataGeneratorTool"
/>
<Tool
Name="VCWebServiceProxyGeneratorTool"
/>
<Tool
Name="VCMIDLTool"
/>
<Tool
Name="VCCLCompilerTool"
Optimization="2"
InlineFunctionExpansion="1"
AdditionalIncludeDirectories="pm_common,porttime,pm_win"
PreprocessorDefinitions="WIN32;_LIB"
StringPooling="true"
RuntimeLibrary="0"
EnableFunctionLevelLinking="true"
PrecompiledHeaderFile=".\$(OutDir)\portmidi.pch"
AssemblerListingLocation=".\$(OutDir)\"
ObjectFile=".\$(OutDir)\"
ProgramDataBaseFileName=".\$(OutDir)\"
WarningLevel="3"
SuppressStartupBanner="true"
/>
<Tool
Name="VCManagedResourceCompilerTool"
/>
<Tool
Name="VCResourceCompilerTool"
PreprocessorDefinitions="NDEBUG"
Culture="1033"
/>
<Tool
Name="VCPreLinkEventTool"
/>
<Tool
Name="VCLibrarianTool"
OutputFile=".\$(OutDir)\portmidi.lib"
SuppressStartupBanner="true"
/>
<Tool
Name="VCALinkTool"
/>
<Tool
Name="VCXDCMakeTool"
/>
<Tool
Name="VCBscMakeTool"
SuppressStartupBanner="true"
OutputFile=".\$(OutDir)\portmidi.bsc"
/>
<Tool
Name="VCFxCopTool"
/>
<Tool
Name="VCPostBuildEventTool"
/>
</Configuration>
</Configurations>
<References>
</References>
<Files>
<File
RelativePath=".\pm_common\pminternal.h"
>
</File>
<File
RelativePath=".\pm_common\pmutil.c"
>
</File>
<File
RelativePath=".\pm_common\pmutil.h"
>
</File>
<File
RelativePath=".\pm_win\pmwin.c"
>
</File>
<File
RelativePath=".\pm_win\pmwinmm.c"
>
</File>
<File
RelativePath=".\pm_win\pmwinmm.h"
>
</File>
<File
RelativePath=".\pm_common\portmidi.c"
>
</File>
<File
RelativePath=".\pm_common\portmidi.h"
>
</File>
</Files>
<Globals>
</Globals>
</VisualStudioProject>
--- NEW FILE: license.txt ---
/*
* PortMidi Portable Real-Time MIDI Library
*
* license.txt -- a copy of the PortMidi copyright notice and license
information
*
* Latest version available at: http://sourceforge.net/projects/portmedia
*
* Copyright (c) 1999-2000 Ross Bencina and Phil Burk
* Copyright (c) 2001-2009 Roger B. Dannenberg
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files
* (the "Software"), to deal in the Software without restriction,
* including without limitation the rights to use, copy, modify, merge,
* publish, distribute, sublicense, and/or sell copies of the Software,
* and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
* ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
* CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
/*
* The text above constitutes the entire PortMidi license; however,
* the PortMusic community also makes the following non-binding requests:
*
* Any person wishing to distribute modifications to the Software is
* requested to send the modifications to the original developer so that
* they can be incorporated into the canonical version. It is also
* requested that these non-binding requests be included along with the
* license above.
*/
--- NEW FILE: README.txt ---
README for PortMidi
Roger B. Dannenberg
VERSION: please use "svn info" to get info.
Documentation for PortMidi is found in pm_common/portmidi.h.
Additional documentation:
- 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
- Common Lisp: see pm_cl/README_CL.txt
---------- 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.
------------------------------------------------------------------------------
_______________________________________________
Audacity-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/audacity-cvs
![[Audacity-cvs] lib-src/portmidi CHANGELOG.txt, NONE, 1.1 Doxyfile, NONE, 1.1 license.txt, NONE, 1.1 portmidi-VC9.vcproj, NONE, 1.1 portmidi.vcproj, NONE, 1.1 portmusic_logo.png, NONE, 1.1 README.txt, NONE, 1.1](/search?l=audacity-cvs@lists.sourceforge.net&q=subject:%22%5C%5BAudacity%5C-cvs%5C%5D+lib%5C-src%5C%2Fportmidi+CHANGELOG.txt%2C+NONE%2C+1.1+Doxyfile%2C%09NONE%2C+1.1+license.txt%2C+NONE%2C+1.1+portmidi%5C-VC9.vcproj%2C+NONE%2C%091.1+portmidi.vcproj%2C+NONE%2C+1.1+portmusic_logo.png%2C+NONE%2C%091.1+README.txt%2C+NONE%2C+1.1%22&o=newest){kind=link}
