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

utility_functions.dox (2452B)

      1 /** @page utility_functions Utility Functions
      2 @ingroup tutorial
      3 
      4 In addition to the functions described elsewhere in this tutorial, PortAudio provides a number of Utility functions that are useful in a variety of circumstances. 
      5 You'll want to read the portaudio.h reference, which documents the entire V19 API for details, but we'll try to cover the basics here.
      6 
      7 @section tut_util2 Version Information
      8 
      9 PortAudio offers two functions to determine the PortAudio Version. This is most useful when you are using PortAudio as a dynamic library, but it may also be useful at other times.
     10 
     11 @code
     12 int             Pa_GetVersion (void)
     13 const char *    Pa_GetVersionText (void)
     14 @endcode
     15 
     16 @section tut_util3 Error Text
     17 
     18 PortAudio allows you to get error text from an error number.
     19 
     20 @code
     21 const char *    Pa_GetErrorText (PaError errorCode)
     22 @endcode
     23 
     24 @section tut_util4 Stream State
     25 
     26 PortAudio Streams exist in 3 states: Active, Stopped, and Callback Stopped. If a stream is in callback stopped state, you'll need to stop it before you can start it again. If you need to query the state of a PortAudio stream, there are two functions for doing so:
     27 
     28 @code
     29 PaError     Pa_IsStreamStopped (PaStream *stream)
     30 PaError     Pa_IsStreamActive (PaStream *stream)
     31 @endcode
     32 
     33 @section tut_util5 Stream Info
     34 
     35 If you need to retrieve info about a given stream, such as latency, and sample rate info, there's a function for that too:
     36 
     37 @code
     38 const PaStreamInfo *    Pa_GetStreamInfo (PaStream *stream)
     39 @endcode
     40 
     41 @section tut_util6 Stream Time
     42 
     43 If you need to synchronise other activities such as display updates or MIDI output with the PortAudio callback you need to know the current time according to the same timebase used by the stream callback timestamps.
     44 
     45 @code
     46 PaTime  Pa_GetStreamTime (PaStream *stream)
     47 @endcode
     48 
     49 @section tut_util6CPU Usage
     50 
     51 To determine how much CPU is being used by the callback, use these:
     52 
     53 @code
     54 double  Pa_GetStreamCpuLoad (PaStream *stream)
     55 @endcode
     56 
     57 @section tut_util7 Other utilities
     58 
     59 These functions allow you to determine the size of a sample from its format and sleep for a given amount of time. The sleep function should not be used for precise timing or synchronization because it makes few guarantees about the exact length of time it waits. It is most useful for testing.
     60 
     61 @code
     62 PaError Pa_GetSampleSize (PaSampleFormat format)
     63 void    Pa_Sleep (long msec)
     64 @endcode
     65 
     66 
     67 Previous: \ref terminating_portaudio | Next: \ref querying_devices
     68 
     69 */