diff options
Diffstat (limited to '3rdparty/portaudio/doc/src/tutorial')
10 files changed, 131 insertions, 33 deletions
diff --git a/3rdparty/portaudio/doc/src/tutorial/compile_cmake.dox b/3rdparty/portaudio/doc/src/tutorial/compile_cmake.dox index ddf5eae610d..8db400e7686 100644 --- a/3rdparty/portaudio/doc/src/tutorial/compile_cmake.dox +++ b/3rdparty/portaudio/doc/src/tutorial/compile_cmake.dox @@ -1,29 +1,57 @@ -/** @page compile_cmake Creating MSVC Build Files via CMake +/** @page compile_cmake PortAudio on Windows, OS X or Linux via. CMake @ingroup tutorial -This is a simple "How-to" for creating build files for Microsoft Visual C++ via CMake and the CMakeLists.txt file +@section cmake_building Building PortAudio stand-alone on Windows, OS X or Linux -1. Install CMake if you haven't got it already ([http://www.cmake.org], minimum version required is 2.8). +CMake can be used to generate Visual Studio solutions on Windows, Makefiles (on Linux and OS X) and build metadata for other build systems for PortAudio. You should obtain a recent version of CMake from [http://www.cmake.org] if you do not have one already. If you are unfamiliar with CMake, this section will provide some information on using CMake to build PortAudio. -2. If you want ASIO support you need to D/L the ASIO2 SDK from Steinberg, and place it according to \ref compile_windows_asio_msvc +On Linux, CMake serves a very similar purpose to an autotools "configure" script - except it can generate build metadata apart from Makefiles. The equivalent of the following on POSIX'y systems: -3. Run the CMake GUI application and browse to <b>source files</b> directory and <b>build</b> directory: - a. The <b>source files</b> directory (<i>"Where is the source code"</i>) is where the portaudio CMakeLists.txt file is located. - b. The <b>build</b> directory (<i>"Where to build the binaries"</i>) is pretty much anywhere you like. A common practice though is to have the build directory located <b>outside</b> the - source files tree (a so called "out-of-source build") + build_path> {portaudio path}/configure --prefix=/install_location + build_path> make + build_path> make install -4. Click <i>Configure</i>. This will prompt you to select which build files to generate. <b>Note</b> Only Microsoft Visual C++ build files currently supported! +Would be: -5. In the CMake option list, enable the PORTAUDIO_xxx options you need, then click <i>Configure</i> again (Note that after this there are no options marked with red color) + build_path> cmake {portaudio path} -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/install_location + build_path> make + build_path> make install -6. Click <i>Generate</i> and you'll now (hopefully) have your VS build files in your previously defined <b>build</b> directory. +The "-G" option specifies the type of build metadata which will be generated. You can obtain a list of supported build metadata formats by invoking (on any platform): -Both ASIO and DirectX SDK are automatically searched for by the CMake script, so if you have DirectX SDK installed and have placed the ASIO2 SDK according to point 2 above, you should be able to build portaudio with !DirectSound and ASIO support. + cmake -G -Should you later on decide to change a portaudio option, just jump in at step 5 above (MSVC will then prompt you to reload projects/solutions/workspace) +"make install" should install the same set of files that are installed using the usual configure script included with PortAudio along with a few extra files (similar to pkg-config metadata files) which make it easier for other CMake projects to use the installed libraries. ---- Robert Bielik +On Windows, you can use CMake to generate Visual Studio project files which can be used to create the PortAudio libraries. The following serves as an example (and should be done from a directory outside the PortAudio tree) which will create Visual Studio 2015 project files targeting a 64-bit build: -Back to the Tutorial: \ref tutorial_start + C:\PABUILD> cmake {portaudio path} -G "Visual Studio 14 2015 Win64" + +After executing the above, you can either open the generated solution with Visual Studio or use CMake to invoke the build process. The following shows an example of how to build a release configuration (assuming the above command was executed previously in the same directory): + + C:\PABUILD> cmake --build . --config Release + +If you want ASIO support you need to obtain the ASIO2 SDK from Steinberg and place it according to \ref compile_windows_asio_msvc. Both ASIO and the DirectX SDK are automatically searched for by the CMake script - if they are found, they will be enabled by default. + +@section cmake_using Using PortAudio in your CMake project + +PortAudio defines the following CMake targets: + + - "portaudio_static" for a static library and + - "portaudio" for a dynamic library + +If you installed PortAudio as described above in \ref cmake_building and the install prefix you used (CMAKE_INSTALL_PREFIX) is in your system PATH or CMAKE_MODULE_PATH CMake variable, you should be able to use: + + find_package(portaudio) + +To define the "portaudio_static" and "portaudio" targets in your CMake project. + +If you do not want to install portaudio into your system but would rather just have it get built as part of your own project (which may be particularly convenient on Windows), you may also use: + + add_subdirectory("path to PortAudio location" "some binary directory" EXCLUDE_FROM_ALL) + +EXCLUDE_FROM_ALL is not strictly necessary, but will ensure that targets which you don't use in your project won't get built. + +Back to \ref tutorial_start */
\ No newline at end of file diff --git a/3rdparty/portaudio/doc/src/tutorial/compile_linux.dox b/3rdparty/portaudio/doc/src/tutorial/compile_linux.dox index e227d759a36..2c993ca83ef 100644 --- a/3rdparty/portaudio/doc/src/tutorial/compile_linux.dox +++ b/3rdparty/portaudio/doc/src/tutorial/compile_linux.dox @@ -47,7 +47,7 @@ On some systems you may need to use: cp /usr/local/lib/libportaudio.a /YOUR/PROJECT/DIR @endcode -You may also need to copy portaudio.h, located in the include/ directory of PortAudio into your project. Note that you will usually need to link with the approriate libraries that you used, such as ALSA and JACK, as well as with librt and libpthread. For example: +You may also need to copy portaudio.h, located in the include/ directory of PortAudio into your project. Note that you will usually need to link with the appropriate libraries that you used, such as ALSA and JACK, as well as with librt and libpthread. For example: @code gcc main.c libportaudio.a -lrt -lm -lasound -ljack -pthread -o YOUR_BINARY diff --git a/3rdparty/portaudio/doc/src/tutorial/compile_mac_coreaudio.dox b/3rdparty/portaudio/doc/src/tutorial/compile_mac_coreaudio.dox index e16ce33dbd0..3f4de903786 100644 --- a/3rdparty/portaudio/doc/src/tutorial/compile_mac_coreaudio.dox +++ b/3rdparty/portaudio/doc/src/tutorial/compile_mac_coreaudio.dox @@ -3,11 +3,11 @@ @section comp_mac_ca_1 Requirements -* OS X 10.4 or later. PortAudio v19 currently only compiles and runs on OS X version 10.4 or later. Because of its heavy reliance on memory barriers, it's not clear how easy it would be to back-port PortAudio to OS X version 10.3. Leopard support requires the 2007 snapshot or later. +* OS X 10.6 or later. PortAudio v19.7 currently only compiles and runs on OS X version 10.6 or later. * Apple's Xcode and its related tools installed in the default location. There is no Xcode project for PortAudio. -* Mac 10.4 SDK. Look for "/Developer/SDKs/MacOSX10.4u.sdk" folder on your system. It may be installed with XCode. If not then you can download it from Apple Developer Connection. http://connect.apple.com/ +* Mac 10.6 SDK. Look for "/Developer/SDKs/MacOSX10.6.sdk" folder on your system. It may be installed with XCode. If not then you can download it from Apple Developer Connection. http://connect.apple.com/ @section comp_mac_ca_2 Building @@ -29,7 +29,7 @@ There are a variety of other options for building PortAudio. The default describ @subsection comp_mac_ca_3.1 Building Non-Universal Libraries -By default, PortAudio is built as a universal binary. This includes 64-bit versions if you are compiling on 10.5, Leopard. If you want a "thin", or single architecture library, you have two options: +By default, PortAudio is built as a universal binary. This includes 64-bit versions if you are compiling on 10.6, Snow Leopard. If you want a "thin", or single architecture library, you have two options: * build a non-universal library using configure options. * use lipo(1) on whatever part of the library you plan to use. @@ -44,11 +44,11 @@ To build a non-universal library for the host architecture, simply use the <i>-- ./configure --disable-mac-universal && make @endcode -The <i>--disable-mac-universal</i> option may also be used in conjunction with environment variables to give you more control over the universal binary build process. For example, to build a universal binary for the i386 and ppc architectures using the 10.4u sdk (which is the default on 10.4, but not 10.5), you might specify this configure command line: +The <i>--disable-mac-universal</i> option may also be used in conjunction with environment variables to give you more control over the universal binary build process. For example, to build a universal binary for the i386 and ppc architectures using the 10.6 sdk, you might specify this configure command line: @code - CFLAGS="-O2 -g -Wall -arch i386 -arch ppc -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.3" \ - LDFLAGS="-arch i386 -arch ppc -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.3" \ + CFLAGS="-O2 -g -Wall -arch i386 -arch ppc -isysroot /Developer/SDKs/MacOSX10.6.sdk -mmacosx-version-min=10.6" \ + LDFLAGS="-arch i386 -arch ppc -isysroot /Developer/SDKs/MacOSX10.6.sdk -mmacosx-version-min=10.6" \ ./configure --disable-mac-universal --disable-dependency-tracking @endcode @@ -99,7 +99,7 @@ You will need to add the following frameworks to your XCode project: - AudioToolbox.framework - AudioUnit.framework - CoreServices.framework - - Carbon.framework + - CoreFoundation.framework @section comp_mac_ca_5 Using the Library in Other Projects diff --git a/3rdparty/portaudio/doc/src/tutorial/compile_windows.dox b/3rdparty/portaudio/doc/src/tutorial/compile_windows.dox index 22589398489..bcb6eccf31e 100644 --- a/3rdparty/portaudio/doc/src/tutorial/compile_windows.dox +++ b/3rdparty/portaudio/doc/src/tutorial/compile_windows.dox @@ -1,17 +1,19 @@ /** @page compile_windows Building PortAudio for Windows using Microsoft Visual Studio @ingroup tutorial +<i><b>NOTE:</b>This page is for building PortAudio using the legacy MSVC project files located in the msvc// directory. You can also use the cmake build system.</i> + Below is a list of steps to build PortAudio into a dll and lib file. The resulting dll file may contain all five current win32 PortAudio APIs: MME, DirectSound, WASAPI, WDM/KS and ASIO, depending on the preprocessor definitions set in step 9 below. PortAudio can be compiled using Visual C++ Express Edition which is available free from Microsoft. If you do not already have a C++ development environment, simply download and install. These instructions have been observed to succeed using Visual Studio 2010 as well. 1) Building PortAudio with DirectSound support requires the files <i>dsound.h</i> and <i>dsconf.h</i>. Download and install the DirectX SDK from http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=3021d52b-514e-41d3-ad02-438a3ba730ba to obtain these files. If you installed the DirectX SDK then the DirectSound libraries and header files should be found automatically by Visual Studio/Visual C++. If you get an error saying dsound.h or dsconf.h is missing, you will need to add an extra include path to the Visual Studio project file referencing the DirectX includes directory. -2) For ASIO support, download the ASIO SDK from Steinberg at http://www.steinberg.net/en/company/developer.html . The SDK is free, but you will need to set up a developer account with Steinberg. To use the Visual Studio projects mentioned below, copy the entire ASIOSDK2 folder into src\\hostapi\\asio\\. Rename it from ASIOSDK2 to ASIOSDK. To build without ASIO (or other host API) see the "Building without ASIO support" section below. +2) To build without ASIO (or other host API) see the "Building without ASIO support" section below. To build with ASIO support, download the ASIO SDK from Steinberg at http://www.steinberg.net/en/company/developer.html . The SDK is free, but you will need to set up a developer account with Steinberg. To use the Visual Studio projects mentioned below, copy the entire ASIOSDK2 folder into src\\hostapi\\asio\\. Rename it from ASIOSDK2 to ASIOSDK. Note: There's an array deletion bug in some versions of the ASIO SDK on Windows. To work around this issue you will need to patch the ASIO SDK. Please see src/host/asio/ASIO-README.txt for the fix. 3) If you have Visual Studio 6.0, 7.0(VC.NET/2001) or 7.1(VC.2003), open portaudio.dsp and convert if needed. -4) If you have Visual Studio 2005, Visual C++ 2008 Express Edition or Visual Studio 2010, open the portaudio.sln file located in build\\msvc\\. Doing so will open Visual Studio or Visual C++. Click "Finish" if a conversion wizard appears. The sln file contains four configurations: Win32 and Win64 in both Release and Debug variants. +4) If you have Visual Studio 2005, Visual C++ 2008 Express Edition or Visual Studio 2010, open the portaudio.sln file located in msvc\\. Doing so will open Visual Studio or Visual C++. Click "Finish" if a conversion wizard appears. The sln file contains four configurations: Win32 and Win64 in both Release and Debug variants. @section comp_win1 For Visual Studio 2005, Visual C++ 2008 Express Edition or Visual Studio 2010 @@ -58,7 +60,7 @@ For each of these, the value of 0 indicates that support for this API should not As when setting Preprocessor definitions, building is a per-configuration per-platform process. Follow these instructions for each configuration/platform combination that you're interested in. -10) From the Build menu click Build -> Build solution. For 32-bit compilations, the dll file created by this process (portaudio_x86.dll) can be found in the directory build\\msvc\\Win32\\Release. For 64-bit compilations, the dll file is called portaudio_x64.dll, and is found in the directory build\\msvc\\x64\\Release. +10) From the Build menu click Build -> Build solution. For 32-bit compilations, the dll file created by this process (portaudio_x86.dll) can be found in the directory msvc\\Win32\\Release. For 64-bit compilations, the dll file is called portaudio_x64.dll, and is found in the directory msvc\\x64\\Release. 11) Now, any project that requires portaudio can be linked with portaudio_x86.lib (or _x64) and include the relevant headers (portaudio.h, and/or pa_asio.h , pa_x86_plain_converters.h) You may want to add/remove some DLL entry points. At the time of writing the following 6 entries are not part of the official PortAudio API defined in portaudio.h: @@ -94,6 +96,17 @@ Project Properties -> Configuration Properties -> C/C++ -> Preprocessor -> Prepr 4) Remove PaAsio_* entry points from portaudio.def +@section comp_win5 List of Windows audio APIs + +WASAPI: recommended by Microsoft. Supported since Windows Vista (includes 7/8/10+). + +ASIO: Low latency API intended for pro audio users; this requires the user to install ASIO drivers. + +WMME, DirectSound: Legacy APIs for greater backward compatibility + +WDM/KS: Low level direct-to-driver API. + + ----- David Viens, davidv@plogue.com diff --git a/3rdparty/portaudio/doc/src/tutorial/compile_windows_asio_msvc.dox b/3rdparty/portaudio/doc/src/tutorial/compile_windows_asio_msvc.dox index cf3a0e59474..eeae8221cb8 100644 --- a/3rdparty/portaudio/doc/src/tutorial/compile_windows_asio_msvc.dox +++ b/3rdparty/portaudio/doc/src/tutorial/compile_windows_asio_msvc.dox @@ -3,6 +3,8 @@ @section comp_win_asiomsvc1 Portaudio Windows ASIO with MSVC +<i><b>NOTE:</b>This page is for building PortAudio using the legacy MSVC project files located in the msvc// directory. You can also use the cmake build system.</i> + This tutorial describes how to build PortAudio with ASIO support using MSVC *from scratch*, without an existing Visual Studio project. For instructions for building PortAudio (including ASIO support) using the bundled Visual Studio project file see the compiling instructions for \ref compile_windows. ASIO is a low latency audio API from Steinberg. To compile an ASIO @@ -54,6 +56,7 @@ pa_stream.c (portaudio\src\common) pa_trace.c (portaudio\src\common) pa_win_hostapis.c (portaudio\src\os\win) pa_win_util.c (portaudio\src\os\win) +pa_win_version.c (portaudio\src\os\win) pa_win_coinitialize.c (portaudio\src\os\win) pa_win_waveformat.c (portaudio\src\os\win) pa_x86_plain_converters.c (portaudio\src\os\win) @@ -87,6 +90,8 @@ You'll need to make sure the relative paths are correct for the particular direc Some source code in the ASIO SDK is not compatible with the Win32 API UNICODE mode (The ASIO SDK expects the non-Unicode Win32 API). Therefore you need to make sure your project is set to not use Unicode. You do this by setting the project Character Set to "Use Multi-Byte Character Set" (NOT "Use Unicode Character Set"). In VS2010 the Character Set option can be found at Configuration Properties > General > Character Set. (An alternative to setting the project to non-Unicode is to patch asiolist.cpp to work when UNICODE is defined: put #undef UNICODE at the top of the file before windows.h is included.) +Note: There's an array deletion bug in some versions of the ASIO SDK on Windows. To work around this issue you will need to patch the ASIO SDK. Please see src/host/asio/ASIO-README.txt for the fix. + You should now be able to build any of the test executables in the portaudio\\examples directory. We suggest that you start with paex_saw.c because it's one of the simplest example files. diff --git a/3rdparty/portaudio/doc/src/tutorial/compile_windows_mingw-w64.dox b/3rdparty/portaudio/doc/src/tutorial/compile_windows_mingw-w64.dox new file mode 100644 index 00000000000..6328c59130a --- /dev/null +++ b/3rdparty/portaudio/doc/src/tutorial/compile_windows_mingw-w64.dox @@ -0,0 +1,44 @@ +/** @page compile_windows_mingw-w64 Building PortAudio for Windows with MinGW-w64 +@ingroup tutorial + +@section comp_mingw-w64_1 PortAudio for Windows with MinGW-w64 + +MinGW-w64 is a port of Linux toolchains (gcc, clang) to Windows. It comes packaged with Msys2 in its preferred configuration. Msys2 provides a Linux environment and the package manager pacman. +Install MinGW-w64 from https://www.msys2.org/. Follow the instructions on this page. + +Brief excursion: there are many toolchain variants in Msys2, and you must use the same toolchain to compile all projects together. In this tutorial, we will use the msvcrt-gcc toolchain, simply because it's already present on all Windows versions. Readers may eventually want to switch to the ucrt-gcc toolchain later, for their Windows 10+ builds, although there is hardly any benefit to doing so. A list of available toolchains is at https://www.msys2.org/docs/environments/. + +In addition, you have a choice of Windows audio APIs; see the bottom of \ref compile_windows for a list. + +You can either use msys2's precompiled PortAudio or compile PortAudio yourself. To install msys2's precompiled PortAudio, see the next section. To compile PortAudio on your own, skip to the next next section. + +@section comp_mingw-w64_2 Pre-compiled package + +Open your msys2 shell and run "pacman -S mingw-w64-x86_64-portaudio". This will get you a default build of PortAudio. I believe it comes with DirectSound, WASAPI, WD/MKS, WD/MKS_DEVICE_INFO, and WMME. Note the "-x86_64" in the middle of the package name. When you install msys2 packages, you specify the toolchain name in the middle, and "-x86_64" chooses the msvcrt-gcc toolchain. + +@section comp_mingw-w64_3 Compiling from scratch + +We will build with WASAPI only, with no fallback APIs, simply as an example. In the msys2 shell, navigate into your folder of PortAudio. Run: + +@code +pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja +mkdir build +cd build +cmake -G Ninja .. -DCMAKE_BUILD_TYPE=Release -DPA_USE_DS=0 -DPA_USE_WDMKS=0 -DPA_USE_WDMKS_DEVICE_INFO=0 -DPA_USE_WMME=0 +cmake --build . +@endcode + +To test if it is working, you can run the sawtooth example (warning, it is very loud!): + +@code +gcc ../examples/paex_saw.c -I../src/common -lportaudio +./a.exe +@endcode + +You can enable the desired fallback APIs again by deleting the terms like "-DPA_USE_WMME=0" in the cmake command. When releasing your application to the public, make sure to copy libportaudio.dll (in the build folder) into your own application's folder. (You'll also need to ship a copy of MinGW-w64's various shared libraries; you can figure out which ones using Microsoft's Process Explorer, and seeing which dlls are accessed from your msys64 folder.) + +Or, compile statically to avoid the issue of dll copies. + +Back to the Tutorial: \ref tutorial_start + +*/ diff --git a/3rdparty/portaudio/doc/src/tutorial/compile_windows_mingw.dox b/3rdparty/portaudio/doc/src/tutorial/compile_windows_mingw.dox index d521b7b8088..26d0a17b1ec 100644 --- a/3rdparty/portaudio/doc/src/tutorial/compile_windows_mingw.dox +++ b/3rdparty/portaudio/doc/src/tutorial/compile_windows_mingw.dox @@ -3,7 +3,11 @@ @section comp_mingw1 Portaudio for Windows With MinGW -<strong>This document contains old or out-of-date information. Please see a draft of new MinGW information on our Wiki: <a href="https://app.assembla.com/spaces/portaudio/wiki/Notes_about_building_PortAudio_with_MinGW">PortAudio Wiki: Notes about building PortAudio with MinGW</a></strong> +<strong>This document contains old or out-of-date information. Please see +a draft of new MinGW information on our +Wiki: <a href="https://github.com/PortAudio/portaudio/wiki/Notes_about_building_PortAudio_with_MinGW"> +PortAudio Wiki: Notes about building PortAudio with MinGW</a></strong> +If you are new to MinGW, consider MinGW-64: \ref compile_windows_mingw-w64. It is a newer project. = MinGW/MSYS = @@ -50,4 +54,4 @@ To update your copy or check out a fresh copy of the source Back to the Tutorial: \ref tutorial_start -*/
\ No newline at end of file +*/ diff --git a/3rdparty/portaudio/doc/src/tutorial/start_stop_abort.dox b/3rdparty/portaudio/doc/src/tutorial/start_stop_abort.dox index 6d4f777523d..0ddb4605bd8 100644 --- a/3rdparty/portaudio/doc/src/tutorial/start_stop_abort.dox +++ b/3rdparty/portaudio/doc/src/tutorial/start_stop_abort.dox @@ -10,7 +10,7 @@ PortAudio will not start playing back audio until you start the stream. After ca if( err != paNoError ) goto error; @endcode -You can communicate with your callback routine through the data structure you passed in on the open call, or through global variables, or using other interprocess communication techniques, but please be aware that your callback function may be called at interrupt time when your foreground process is least expecting it. So avoid sharing complex data structures that are easily corrupted like double linked lists, and avoid using locks such as mutexs as this may cause your callback function to block and therefore drop audio. Such techniques may even cause deadlock on some platforms. +You can communicate with your callback routine through the data structure you passed in on the open call, or through global variables, or using other interprocess communication techniques, but please be aware that your callback function may be called at interrupt time when your foreground process is least expecting it. So avoid sharing complex data structures that are easily corrupted like double linked lists, and avoid using locks such as mutexes as this may cause your callback function to block and therefore drop audio. Such techniques may even cause deadlock on some platforms. PortAudio will continue to call your callback and process audio until you stop the stream. This can be done in one of several ways, but, before we do so, we'll want to see that some of our audio gets processed by sleeping for a few seconds. This is easy to do with Pa_Sleep(), which is used by many of the examples in the patests/ directory for exactly this purpose. Note that, for a variety of reasons, you can not rely on this function for accurate scheduling, so your stream may not run for exactly the same amount of time as you expect, but it's good enough for our example. diff --git a/3rdparty/portaudio/doc/src/tutorial/tutorial_start.dox b/3rdparty/portaudio/doc/src/tutorial/tutorial_start.dox index d6b5e69fce3..aa4a1b9fd8f 100644 --- a/3rdparty/portaudio/doc/src/tutorial/tutorial_start.dox +++ b/3rdparty/portaudio/doc/src/tutorial/tutorial_start.dox @@ -13,14 +13,16 @@ Once you've downloaded PortAudio you'll need to compile it, which of course, dep - Windows - \ref compile_windows + - \ref compile_windows_mingw-w64 - \ref compile_windows_mingw - \ref compile_windows_asio_msvc - - \ref compile_cmake - Mac OS X - \ref compile_mac_coreaudio - POSIX - \ref compile_linux +You can also use CMake to generate project files for PortAudio on Windows, OS X or Linux or include PortAudio easily in your own CMake project. See \ref compile_cmake. + Many platforms with GCC/make can use the simple ./configure && make combination and simply use the resulting libraries in their code. @section tut_start3 Programming with PortAudio @@ -36,7 +38,9 @@ Below are the steps to writing a PortAudio application using the callback techni In addition to this "Callback" architecture, V19 also supports a "Blocking I/O" model which uses read and write calls which may be more familiar to non-audio programmers. Note that at this time, not all APIs support this functionality. -In this tutorial, we'll show how to use the callback architecture to play a sawtooth wave. Much of the tutorial is taken from the file paex_saw.c, which is part of the PortAudio distribution. When you're done with this tutorial, you'll be armed with the basic knowledge you need to write an audio program. If you need more sample code, look in the "examples" and "test" directory of the PortAudio distribution. Another great source of info is the portaudio.h Doxygen page, which documents the entire V19 API. Also see the page for <a href="http://www.assembla.com/spaces/portaudio/wiki/Tips">tips on programming PortAudio</a> on the PortAudio wiki. +In this tutorial, we'll show how to use the callback architecture to play a sawtooth wave. Much of the tutorial is taken from the file paex_saw.c, which is part of the PortAudio distribution. When you're done with this tutorial, you'll be armed with the basic knowledge you need to write an audio program. If you need more sample code, look in the "examples" and "test" directory of the PortAudio distribution. Another great source of info is the portaudio.h Doxygen page, which documents the entire V19 API. +Also see the page for <a href="https://github.com/PortAudio/portaudio/wiki/Tips">tips on programming PortAudio</a> +on the PortAudio wiki. @section tut_start4 Programming Tutorial Contents @@ -55,4 +59,4 @@ Once you have a basic understanding of how to use PortAudio, you might be intere Next: \ref writing_a_callback -*/
\ No newline at end of file +*/ diff --git a/3rdparty/portaudio/doc/src/tutorial/writing_a_callback.dox b/3rdparty/portaudio/doc/src/tutorial/writing_a_callback.dox index 7c2f8d3ea15..f7d71b198b3 100644 --- a/3rdparty/portaudio/doc/src/tutorial/writing_a_callback.dox +++ b/3rdparty/portaudio/doc/src/tutorial/writing_a_callback.dox @@ -10,7 +10,7 @@ The next task is to write your own "callback" function. The "callback" is a func Before we begin, it's important to realize that the callback is a delicate place. This is because some systems perform the callback in a special thread, or interrupt handler, and it is rarely treated the same as the rest of your code. For most modern systems, you won't be able to cause crashes by making disallowed calls in the callback, but if you want your code to produce glitch-free audio, you will have to make sure you avoid function calls that may take an unbounded amount of time to execute. Exactly what these are depend on your platform but almost certainly include the following: memory allocation/deallocation, I/O (including file I/O as well as console I/O, such as printf()), context switching (such as exec() or -yield()), mutex operations, or anything else that might rely on the OS. If you think short critical sections are safe please go read about priority inversion. Windows amd Mac OS schedulers have no real-time safe priority inversion prevention. Other platforms require special mutex flags. In addition, it is not safe to call any PortAudio API functions in the callback except as explicitly permitted in the documentation. +yield()), mutex operations, or anything else that might rely on the OS. If you think short critical sections are safe please go read about priority inversion. Windows and Mac OS schedulers have no real-time safe priority inversion prevention. Other platforms require special mutex flags. In addition, it is not safe to call any PortAudio API functions in the callback except as explicitly permitted in the documentation. Your callback function must return an int and accept the exact parameters specified in this typedef: |