gearmulator

Emulation of classic VA synths of the late 90s/2000s that are based on Motorola 56300 family DSPs
Log | Files | Refs | Submodules | README | LICENSE

querying_devices.dox (4501B)

      1 /** @page querying_devices Enumerating and Querying PortAudio Devices
      2 @ingroup tutorial
      3 
      4 @section tut_query1 Querying Devices
      5 
      6 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:
      7 
      8 @code
      9     int numDevices;
     10 
     11     numDevices = Pa_GetDeviceCount();
     12     if( numDevices < 0 )
     13     {
     14         printf( "ERROR: Pa_CountDevices returned 0x%x\n", numDevices );
     15         err = numDevices;
     16         goto error;
     17     }
     18 @endcode
     19 
     20 
     21 If you want to get information about each device, simply loop through as follows:
     22 
     23 @code
     24     const   PaDeviceInfo *deviceInfo;
     25 
     26     for( i=0; i<numDevices; i++ )
     27     {
     28         deviceInfo = Pa_GetDeviceInfo( i );
     29         ...
     30     }
     31 @endcode
     32 
     33 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:
     34 
     35 @code
     36 int 	structVersion
     37 const char * 	name
     38 PaHostApiIndex 	hostApi
     39 int 	maxInputChannels
     40 int 	maxOutputChannels
     41 PaTime 	defaultLowInputLatency
     42 PaTime 	defaultLowOutputLatency
     43 PaTime 	defaultHighInputLatency
     44 PaTime 	defaultHighOutputLatency
     45 double 	defaultSampleRate
     46 @endcode
     47 
     48 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:
     49 
     50 @code
     51     const PaStreamParameters *inputParameters;
     52     const PaStreamParameters *outputParameters;
     53     double desiredSampleRate;
     54     ...
     55     PaError err;
     56 
     57     err = Pa_IsFormatSupported( inputParameters, outputParameters, desiredSampleRate );
     58     if( err == paFormatIsSupported )
     59     {
     60        printf( "Hooray!\n");
     61     }
     62     else
     63     {
     64        printf("Too Bad.\n");
     65     }
     66 @endcode
     67 
     68 Filling in the inputParameters and outputParameters fields is shown in a moment.
     69 
     70 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:
     71 
     72 @code
     73     double srate = ... ;
     74     PaStream *stream;
     75     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
     76     PaStreamParameters outputParameters;
     77     PaStreamParameters inputParameters;
     78 
     79     bzero( &inputParameters, sizeof( inputParameters ) ); //not necessary if you are filling in all the fields
     80     inputParameters.channelCount = inChan;
     81     inputParameters.device = inDevNum;
     82     inputParameters.hostApiSpecificStreamInfo = NULL;
     83     inputParameters.sampleFormat = paFloat32;
     84     inputParameters.suggestedLatency = Pa_GetDeviceInfo(inDevNum)->defaultLowInputLatency ;
     85     inputParameters.hostApiSpecificStreamInfo = NULL; //See you specific host's API docs for info on using this field
     86 
     87 
     88     bzero( &outputParameters, sizeof( outputParameters ) ); //not necessary if you are filling in all the fields
     89     outputParameters.channelCount = outChan;
     90     outputParameters.device = outDevNum;
     91     outputParameters.hostApiSpecificStreamInfo = NULL;
     92     outputParameters.sampleFormat = paFloat32;
     93     outputParameters.suggestedLatency = Pa_GetDeviceInfo(outDevNum)->defaultLowOutputLatency ;
     94     outputParameters.hostApiSpecificStreamInfo = NULL; //See you specific host's API docs for info on using this field
     95 
     96     err = Pa_OpenStream(
     97                     &stream,
     98                     &inputParameters,
     99                     &outputParameters,
    100                     srate,
    101                     framesPerBuffer,
    102                     paNoFlag, //flags that can be used to define dither, clip settings and more
    103                     portAudioCallback, //your callback function
    104                     (void *)this ); //data to be passed to callback. In C++, it is frequently (void *)this
    105     //don't forget to check errors!
    106 @endcode
    107 
    108 
    109 Previous: \ref utility_functions | Next: \ref blocking_read_write
    110 
    111 */