Commit 81fc0fe6 authored by Miller Puckette's avatar Miller Puckette
Browse files

oops, see next

parent 3ef9d1ba
Portable header file to contain:
/*
* PortAudio Portable Real-Time Audio Library
* PortAudio API Header File
* Latest version available at: http://www.audiomulch.com/portaudio/
*
* Copyright (c) 1999-2000 Ross Bencina and Phil Burk
*
* 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.
*
* 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.
*
* 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.
*
*/
Implementation files to contain:
/*
* PortAudio Portable Real-Time Audio Library
* Latest version at: http://www.audiomulch.com/portaudio/
* <platform> Implementation
* Copyright (c) 1999-2000 <author(s)>
*
* 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.
*
* 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.
*
* 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.
*
*/
\ No newline at end of file
README for PortAudio
Implementations for PC DirectSound and Mac SoundManager
/*
* PortAudio Portable Real-Time Audio Library
* Latest Version at: http://www.portaudio.com//
*
* Copyright (c) 1999-2000 Phil Burk and Ross Bencina
*
* 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.
*
* 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.
*
* 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.
*
*/
PortAudio is a portable audio I/O library designed for cross-platform
support of audio. It uses a callback mechanism to request audio processing.
Audio can be generated in various formats, including 32 bit floating point,
and will be converted to the native format internally.
Documentation:
See "pa_common/portaudio.h" for API spec.
See docs folder for a tutorial.
Also see http://www.portaudio.com/docs/
And see "pa_tests/patest_saw.c" for an example.
For information on compiling programs with PortAudio, please see the
tutorial at:
http://www.portaudio.com/docs/pa_tutorial.html
Important Files and Folders:
pa_common/ = platform independant code
pa_common/portaudio.h = header file for PortAudio API. Specifies API.
pa_common/pa_lib.c = host independant code for all implementations.
pablio = simple blocking read/write interface
Platform Implementations
pa_asio = ASIO for Windows and Macintosh
pa_beos = BeOS
pa_mac_sm = Macintosh Sound Manager for OS 8,9 and Carbon
pa_mac_core = Macintosh Core Audio for OS X
pa_sgi = Silicon Graphics AL
pa_unix_oss = OSS implementation for various Unixes
pa_win_ds = Windows Direct Sound
pa_win_wmme = Windows MME (most widely supported)
Test Programs
pa_tests/pa_fuzz.c = guitar fuzz box
pa_tests/pa_devs.c = print a list of available devices
pa_tests/pa_minlat.c = determine minimum latency for your machine
pa_tests/paqa_devs.c = self test that opens all devices
pa_tests/paqa_errs.c = test error detection and reporting
pa_tests/patest_clip.c = hear a sine wave clipped and unclipped
pa_tests/patest_dither.c = hear effects of dithering (extremely subtle)
pa_tests/patest_pink.c = fun with pink noise
pa_tests/patest_record.c = record and playback some audio
pa_tests/patest_maxsines.c = how many sine waves can we play? Tests Pa_GetCPULoad().
pa_tests/patest_sine.c = output a sine wave in a simple PA app
pa_tests/patest_sync.c = test syncronization of audio and video
pa_tests/patest_wire.c = pass input to output, wire simulator
STATUS:
MME, DirectSound and ASIO versions are more-or-less working. See FIXMEs @todos
and the proposals matrix at portaudio.com for further status.
The pa_tests directory contains tests. pa_tests/README.txt notes which tests
currently build.
The PaUtil support code is finished enough for other implementations to be
ported. No changes are expected to be made to the definition of the PaUtil
functions.
Note that it's not yet 100% clear how the current support functions
will interact with blocking read/write streams.
BUILD INSTRUCTIONS
to build tests/patest_sine.c you will need to compile and link the following
files (MME)
pa_common\pa_process.c
pa_common\pa_skeleton.c
pa_common\pa_stream.c
pa_common\pa_trace.c
pa_common\pa_converters.c
pa_common\pa_cpuload.c
pa_common\pa_dither.c
pa_common\pa_front.c
pa_common\pa_allocation.h
pa_win\pa_win_util.c
pa_win\pa_win_hostapis.c
pa_win_wmme\pa_win_wmme.c
see below for a description of these files.
FILES:
portaudio.h
public api header file
pa_front.c
implements the interface defined in portaudio.h. manages multiple host apis.
validates function parameters before calling through to host apis. tracks
open streams and closes them at Pa_Terminate().
pa_util.h
declares utility functions for use my implementations. including utility
functions which must be implemented separately for each platform.
pa_hostapi.h
hostapi representation structure used to interface between pa_front.c
and implementations
pa_stream.c/h
stream interface and representation structures and helper functions
used to interface between pa_front.c and implementations
pa_cpuload.c/h
source and header for cpu load calculation facility
pa_trace.c/h
source and header for debug trace log facility
pa_converters.c/h
sample buffer conversion facility
pa_dither.c/h
dither noise generator
pa_process.c/h
callback buffer processing facility including interleave and block adaption
pa_allocation.c/h
allocation context for tracking groups of allocations
pa_skeleton.c
an skeleton implementation showing how the common code can be used.
pa_win_util.c
Win32 implementation of platform specific PaUtil functions (memory allocation,
usec clock, Pa_Sleep().) The file will be used with all Win32 host APIs.
pa_win_hostapis.c
contains the paHostApiInitializers array and an implementation of
Pa_GetDefaultHostApi() for win32 builds.
pa_win_wmme.c
Win32 host api implementation for the windows multimedia extensions audio API.
pa_win_wmme.h
public header file containing interfaces to mme-specific functions and the
deviceInfo data structure.
CODING GUIDELINES:
naming conventions:
#defines begin with PA_
#defines local to a file end with _
global utility variables begin with paUtil
global utility types begin with PaUtil (including function types)
global utility functions begin with PaUtil_
static variables end with _
static constants begin with const and end with _
static funtions have no special prefix/suffix
In general, implementations should declare all of their members static,
except for their initializer which should be exported. All exported names
should be preceeded by Pa<MN>_ where MN is the module name, for example
the windows mme initializer should be named PaWinWmme_Initialize().
Every host api should define an initializer which returns an error code
and a PaHostApiInterface*. The initializer should only return an error other
than paNoError if it encounters an unexpected and fatal error (memory allocation
error for example). In general, there may be conditions under which it returns
a NULL interface pointer and also returns paNoError. For example, if the ASIO
implementation detects that ASIO is not installed, it should return a
NULL interface, and paNoError.
Platform-specific shared functions should begin with Pa<PN>_ where PN is the
platform name. eg. PaWin_ for windows, PaUnix_ for unix.
The above two conventions should also be followed whenever it is necessary to
share functions accross multiple source files.
Two utilities for debug messages are provided. The PA_DEBUG macro defined in
pa_implementation.h provides a simple way to print debug messages to stderr.
Due to real-time performance issues, PA_DEBUG may not be suitable for use
within the portaudio processing callback, or in other threads. In such cases
the event tracing facility provided in pa_trace.h may be more appropriate.
If PA_LOG_API_CALLS is defined, all calls to the public PortAudio API
will be logged to stderr along with parameter and return values.
TODO:
(this list is totally out of date)
finish coding converter functions in pa_converters.c (anyone?)
implement block adaption in pa_process.c (phil?)
fix all current tests to work with new code. this should mostly involve
changing PortAudioStream to PaStream, and GetDefaultDeviceID to GetDefaultDevice etc.
write some new tests to exercise the multi-api functions
write (doxygen) documentation for pa_trace (phil?)
remove unused typeids from PaHostAPITypeID
create a global configuration file which documents which PA_ defines can be
used for configuration
need a coding standard for comment formatting
migrate directx (phil)
migrate asio (ross?, stephane?)
see top of pa_win_wmme.c for MME todo items (ross)
write style guide document (ross)
DESIGN ISSUES:
(this list is totally out of date)
consider removing Pa_ConvertHostApiDeviceIndexToGlobalDeviceIndex() from the API
switch to new latency parameter mechanism now (?)
question: if input or outputDriverInfo structures are passed for a different
hostApi from the one being called, do we return an error or just ignore
them? (i think return error)
consider renaming PortAudioCallback to PaStreamCallback
consider renaming PaError, PaResult
ASSORTED DISORGANISED NOTES:
NOTE:
pa_lib.c performs the following validations for Pa_OpenStream() which we do not currently do:
- checks the device info to make sure that the device supports the requested sample rate,
it may also change the sample rate to the "closest available" sample rate if it
is within a particular error margin
rationale for breaking up internalPortAudioStream:
each implementation has its own requirements and behavior, and should be
able to choose the best way to operate without being limited by the
constraints imposed by a common infrastructure. in other words the
implementations should be able to pick and choose services from the
common infrastructure. currently identified services include:
- cpu load tracking
- buffering and conversion service (same code works for input and output)
- should support buffer multiplexing (non-integer length input and output buffers)
- in-place conversion where possible (only for callback, read/write always copies)
- should manage allocation of temporary buffers if necessary
- instrumentation (should be able to be disabled): callback count, framesProcessed
- common data: magic, streamInterface, callback, userdata
- conversion functions:
- should handle temp buffer allocation
- dithering (random number state per-stream)
- buffer size mismatches
- with new buffer slip rules, temp buffers may always be needed
- we should aim for in-place conversion wherever possible
- does phil's code support in-place conversion? (yes)
- dicuss relationship between user and host buffer sizes
- completely independent.. individual implementations may constrain
host buffer sizes if necessary
- discuss device capabilities:
- i'd like to be able to request certain information:
- channel count for example
ASIO-README.txt
This document contains information to help you compile PortAudio with
ASIO support. If you find any omissions or errors in this document
please notify Ross Bencina <rossb@audiomulch.com>.
Building PortAudio with ASIO support
------------------------------------
To build PortAudio with ASIO support you need to compile and link with
pa_asio.c, and files from the ASIO SDK (see below), along with the common
files from pa_common/ and platform specific files from pa_win/ (for Win32)
or pa_mac/ (for Macintosh).
If you are compiling with a non-Microsoft compiler on windows, also
compile and link with iasiothiscallresolver.cpp (see below for
an explanation).
For some platforms (MingW, possibly Mac), you may simply
be able to type:
./configure --with-host_os=mingw --with-winapi=asio [--with-asiodir=/usr/local/asiosdk2]
make
./configure --with-host_os=darwin --with-winapi=asio [--with-asiodir=/usr/local/asiosdk2]
make
and life will be good.
Obtaining the ASIO SDK
----------------------
In order to build PortAudio with ASIO support, you need to download
the ASIO SDK (version 2.0) from Steinberg. Steinberg makes the ASIO
SDK available to anyone free of charge, however they do not permit its
source code to be distributed.
NOTE: In some cases the ASIO SDK may require patching, see below
for further details.
http://www.steinberg.net/en/ps/support/3rdparty/asio_sdk/
If the above link is broken search Google for:
"download steinberg ASIO SDK"
Building the ASIO SDK on Macintosh
----------------------------------
To build the ASIO SDK on Macintosh you need to compile and link with the
following files from the ASIO SDK:
host/asiodrivers.cpp
host/mac/asioshlib.cpp
host/mac/codefragements.cpp
Building the ASIO SDK on Windows
--------------------------------
To build the ASIO SDK on Windows you need to compile and link with the
following files from the ASIO SDK:
asio_sdk\common\asio.cpp
asio_sdk\host\asiodrivers.cpp
asio_sdk\host\pc\asiolist.cpp
You may also need to adjust your include paths to support inclusion of
header files from the above directories.
The ASIO SDK depends on the following COM API functions:
CoInitialize, CoUninitialize, CoCreateInstance, CLSIDFromString
For compilation with MinGW you will need to link with -lole32, for
Borland link with Import32.lib.
Non-Microsoft (MSVC) Compilers on Windows including Borland and GCC
-------------------------------------------------------------------
Steinberg did not specify a calling convention in the IASIO interface
definition. This causes the Microsoft compiler to use the proprietary
thiscall convention which is not compatible with other compilers, such
as compilers from Borland (BCC and C++Builder) and GNU (gcc).
Steinberg's ASIO SDK will compile but crash on initialization if
compiled with a non-Microsoft compiler on Windows.
PortAudio solves this problem using the iasiothiscallresolver library
which is included in the distribution. When building ASIO support for
non-Microsoft compilers, be sure to compile and link with
iasiothiscallresolver.cpp. Note that iasiothiscallresolver includes
conditional directives which cause it to have no effect if it is
compiled with a Microsoft compiler, or on the Macintosh.
If you use configure and make (see above), this should be handled
automatically for you.
For further information about the IASIO thiscall problem see this page:
http://www.audiomulch.com/~rossb/code/calliasio
Macintosh ASIO SDK Bug Patch
----------------------------
There is a bug in the ASIO SDK that causes the Macintosh version to
often fail during initialization. Below is a patch that you can apply.
In codefragments.cpp replace getFrontProcessDirectory function with
the following one (GetFrontProcess replaced by GetCurrentProcess).
bool CodeFragments::getFrontProcessDirectory(void *specs)
{
FSSpec *fss = (FSSpec *)specs;
ProcessInfoRec pif;
ProcessSerialNumber psn;
memset(&psn,0,(long)sizeof(ProcessSerialNumber));
// if(GetFrontProcess(&psn) == noErr) // wrong !!!
if(GetCurrentProcess(&psn) == noErr) // correct !!!
{
pif.processName = 0;
pif.processAppSpec = fss;
pif.processInfoLength = sizeof(ProcessInfoRec);
if(GetProcessInformation(&psn, &pif) == noErr)
return true;
}
return false;
}
---
/ASIO-README.txt/1.1.2.4/Fri Sep 19 08:46:15 2003//Tv19-devel
/Callback_adaptation_.pdf/1.1.1.1/Tue Jan 22 00:51:53 2002/-kb/Tv19-devel
/Pa_ASIO.pdf/1.1.1.1/Tue Jan 22 00:51:56 2002/-kb/Tv19-devel
/iasiothiscallresolver.cpp/1.1.2.4/Sat Jul 10 03:27:41 2004//Tv19-devel
/iasiothiscallresolver.h/1.1.2.3/Mon Jul 12 13:35:05 2004//Tv19-devel
/pa_asio.cpp/1.7.2.68/Mon Dec 5 04:55:28 2005//Tv19-devel
/pa_asio.h/1.1.2.7/Sat Jan 1 19:35:33 2005//Tv19-devel
D
:pserver:anonymous@www.portaudio.com:/home/cvs
This diff is collapsed.
// ****************************************************************************
// File: IASIOThiscallResolver.h
// Description: The IASIOThiscallResolver class implements the IASIO
// interface and acts as a proxy to the real IASIO interface by
// calling through its vptr table using the thiscall calling
// convention. To put it another way, we interpose
// IASIOThiscallResolver between ASIO SDK code and the driver.
// This is necessary because most non-Microsoft compilers don't
// implement the thiscall calling convention used by IASIO.
//
// iasiothiscallresolver.cpp contains the background of this
// problem plus a technical description of the vptr
// manipulations.
//
// In order to use this mechanism one simply has to add
// iasiothiscallresolver.cpp to the list of files to compile
// and #include <iasiothiscallresolver.h>
//
// Note that this #include must come after the other ASIO SDK
// #includes, for example:
//
// #include <windows.h>
// #include <asiosys.h>
// #include <asio.h>
// #include <asiodrivers.h>
// #include <iasiothiscallresolver.h>
//
// Actually the important thing is to #include
// <iasiothiscallresolver.h> after <asio.h>. We have
// incorporated a test to enforce this ordering.
//
// The code transparently takes care of the interposition by
// using macro substitution to intercept calls to ASIOInit()
// and ASIOExit(). We save the original ASIO global
// "theAsioDriver" in our "that" variable, and then set
// "theAsioDriver" to equal our IASIOThiscallResolver instance.
//
// Whilst this method of resolving the thiscall problem requires
// the addition of #include <iasiothiscallresolver.h> to client
// code it has the advantage that it does not break the terms
// of the ASIO licence by publishing it. We are NOT modifying
// any Steinberg code here, we are merely implementing the IASIO
// interface in the same way that we would need to do if we
// wished to provide an open source ASIO driver.
//
// For compilation with MinGW -lole32 needs to be added to the
// linker options. For BORLAND, linking with Import32.lib is
// sufficient.
//
// The dependencies are with: CoInitialize, CoUninitialize,
// CoCreateInstance, CLSIDFromString - used by asiolist.cpp
// and are required on Windows whether ThiscallResolver is used
// or not.
//
// Searching for the above strings in the root library path
// of your compiler should enable the correct libraries to be
// identified if they aren't immediately obvious.
//
// Note that the current implementation of IASIOThiscallResolver
// is not COM compliant - it does not correctly implement the
// IUnknown interface. Implementing it is not necessary because
// it is not called by parts of the ASIO SDK which call through
// theAsioDriver ptr. The IUnknown methods are implemented as
// assert(false) to ensure that the code fails if they are
// ever called.
// Restrictions: None. Public Domain & Open Source distribute freely
// You may use IASIOThiscallResolver commercially as well as
// privately.
// You the user assume the responsibility for the use of the
// files, binary or text, and there is no guarantee or warranty,
// expressed or implied, including but not limited to the
// implied warranties of merchantability and fitness for a
// particular purpose. You assume all responsibility and agree
// to hold no entity, copyright holder or distributors liable
// for any loss of data or inaccurate representations of data
// as a result of using IASIOThiscallResolver.
// Version: 1.4 Added separate macro CALL_THISCALL_1_DOUBLE from
// Andrew Baldwin, and volatile for whole gcc asm blocks,
// both for compatibility with newer gcc versions. Cleaned up
// Borland asm to use one less register.
// 1.3 Switched to including assert.h for better compatibility.
// Wrapped entire .h and .cpp contents with a check for
// _MSC_VER to provide better compatibility with MS compilers.
// Changed Singleton implementation to use static instance
// instead of freestore allocated instance. Removed ASIOExit
// macro as it is no longer needed.
// 1.2 Removed semicolons from ASIOInit and ASIOExit macros to
// allow them to be embedded in expressions (if statements).
// Cleaned up some comments. Removed combase.c dependency (it
// doesn't compile with BCB anyway) by stubbing IUnknown.
// 1.1 Incorporated comments from Ross Bencina including things
// such as changing name from ThiscallResolver to
// IASIOThiscallResolver, tidying up the constructor, fixing
// a bug in IASIOThiscallResolver::ASIOExit() and improving
// portability through the use of conditional compilation
// 1.0 Initial working version.
// Created: 6/09/2003
// Authors: Fraser Adams
// Ross Bencina
// Rene G. Ceballos
// Martin Fay
// Antti Silvast
// Andrew Baldwin
//
// ****************************************************************************