From a4dd0ad63c00f4dee3b86dfd3075d1d61b2b3180 Mon Sep 17 00:00:00 2001
From: sanine <sanine.not@pm.me>
Date: Sat, 27 Aug 2022 23:52:56 -0500
Subject: add plibsys

---
 .../doc/src/tutorial/querying_devices.dox          | 111 +++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 3rdparty/portaudio/doc/src/tutorial/querying_devices.dox

(limited to '3rdparty/portaudio/doc/src/tutorial/querying_devices.dox')

diff --git a/3rdparty/portaudio/doc/src/tutorial/querying_devices.dox b/3rdparty/portaudio/doc/src/tutorial/querying_devices.dox
new file mode 100644
index 0000000..1eac41a
--- /dev/null
+++ b/3rdparty/portaudio/doc/src/tutorial/querying_devices.dox
@@ -0,0 +1,111 @@
+/** @page querying_devices Enumerating and Querying PortAudio Devices
+@ingroup tutorial
+
+@section tut_query1 Querying Devices
+
+It is often fine to use the default device as we did previously in this tutorial, but there are times when you'll want to explicitly choose the device from a list of available devices on the system. To see a working example of this, check out pa_devs.c in the tests/ directory of the PortAudio source code. To do so, you'll need to first initialize PortAudio and Query for the number of Devices:
+
+@code
+    int numDevices;
+
+    numDevices = Pa_GetDeviceCount();
+    if( numDevices < 0 )
+    {
+        printf( "ERROR: Pa_CountDevices returned 0x%x\n", numDevices );
+        err = numDevices;
+        goto error;
+    }
+@endcode
+
+
+If you want to get information about each device, simply loop through as follows:
+
+@code
+    const   PaDeviceInfo *deviceInfo;
+
+    for( i=0; i<numDevices; i++ )
+    {
+        deviceInfo = Pa_GetDeviceInfo( i );
+        ...
+    }
+@endcode
+
+The Pa_DeviceInfo structure contains a wealth of information such as the name of the devices, the default latency associated with the devices and more. The structure has the following fields:
+
+@code
+int 	structVersion
+const char * 	name
+PaHostApiIndex 	hostApi
+int 	maxInputChannels
+int 	maxOutputChannels
+PaTime 	defaultLowInputLatency
+PaTime 	defaultLowOutputLatency
+PaTime 	defaultHighInputLatency
+PaTime 	defaultHighOutputLatency
+double 	defaultSampleRate
+@endcode
+
+You may notice that you can't determine, from this information alone, whether or not a particular sample rate is supported. This is because some devices support ranges of sample rates, others support, a list of sample rates, and still others support some sample rates and number of channels combinations but not others. To get around this, PortAudio offers a function for testing a particular device with a given format:
+
+@code
+    const PaStreamParameters *inputParameters;
+    const PaStreamParameters *outputParameters;
+    double desiredSampleRate;
+    ...
+    PaError err;
+
+    err = Pa_IsFormatSupported( inputParameters, outputParameters, desiredSampleRate );
+    if( err == paFormatIsSupported )
+    {
+       printf( "Hooray!\n");
+    }
+    else
+    {
+       printf("Too Bad.\n");
+    }
+@endcode
+
+Filling in the inputParameters and outputParameters fields is shown in a moment.
+
+Once you've found a configuration you like, or one you'd like to go ahead and try, you can open the stream by filling in the PaStreamParameters structures, and calling Pa_OpenStream:
+
+@code
+    double srate = ... ;
+    PaStream *stream;
+    unsigned long framesPerBuffer = ... ; //could be paFramesPerBufferUnspecified, in which case PortAudio will do its best to manage it for you, but, on some platforms, the framesPerBuffer will change in each call to the callback
+    PaStreamParameters outputParameters;
+    PaStreamParameters inputParameters;
+
+    bzero( &inputParameters, sizeof( inputParameters ) ); //not necessary if you are filling in all the fields
+    inputParameters.channelCount = inChan;
+    inputParameters.device = inDevNum;
+    inputParameters.hostApiSpecificStreamInfo = NULL;
+    inputParameters.sampleFormat = paFloat32;
+    inputParameters.suggestedLatency = Pa_GetDeviceInfo(inDevNum)->defaultLowInputLatency ;
+    inputParameters.hostApiSpecificStreamInfo = NULL; //See you specific host's API docs for info on using this field
+
+
+    bzero( &outputParameters, sizeof( outputParameters ) ); //not necessary if you are filling in all the fields
+    outputParameters.channelCount = outChan;
+    outputParameters.device = outDevNum;
+    outputParameters.hostApiSpecificStreamInfo = NULL;
+    outputParameters.sampleFormat = paFloat32;
+    outputParameters.suggestedLatency = Pa_GetDeviceInfo(outDevNum)->defaultLowOutputLatency ;
+    outputParameters.hostApiSpecificStreamInfo = NULL; //See you specific host's API docs for info on using this field
+
+    err = Pa_OpenStream(
+                    &stream,
+                    &inputParameters,
+                    &outputParameters,
+                    srate,
+                    framesPerBuffer,
+                    paNoFlag, //flags that can be used to define dither, clip settings and more
+                    portAudioCallback, //your callback function
+                    (void *)this ); //data to be passed to callback. In C++, it is frequently (void *)this
+    //don't forget to check errors!
+@endcode
+
+
+Previous: \ref utility_functions | Next: \ref blocking_read_write
+
+*/
\ No newline at end of file
-- 
cgit v1.2.1