summaryrefslogtreecommitdiff
path: root/3rdparty/portaudio/doc/src/tutorial/querying_devices.dox
diff options
context:
space:
mode:
authorsanine <sanine.not@pm.me>2022-08-27 23:52:56 -0500
committersanine <sanine.not@pm.me>2022-08-27 23:52:56 -0500
commita4dd0ad63c00f4dee3b86dfd3075d1d61b2b3180 (patch)
tree13bd5bfa15e6fea2a12f176bae79adf9c6fd0933 /3rdparty/portaudio/doc/src/tutorial/querying_devices.dox
parentbde3e4f1bb7b8f8abca0884a7d994ee1c17a66b1 (diff)
add plibsys
Diffstat (limited to '3rdparty/portaudio/doc/src/tutorial/querying_devices.dox')
-rw-r--r--3rdparty/portaudio/doc/src/tutorial/querying_devices.dox111
1 files changed, 111 insertions, 0 deletions
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