libcm is a C development framework with an emphasis on audio signal processing applications.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232
  1. /// \file cmApBuf.h
  2. /// \brief Thread-safe audio buffer class.
  3. ///
  4. /// This file defines an audio buffer class which handles
  5. /// buffering incoming (recording) and outgoing (playback)
  6. /// samples in a thread-safe manner.
  7. ///
  8. /// Usage example and testing code:
  9. /// See cmApBufTest() and cmAudioSysTest().
  10. /// \snippet cmApBuf.c cmApBufExample
  11. ///
  12. /// Notes on channel flags:
  13. /// Disabled channels: kChFl is cleared
  14. /// cmApBufGet()
  15. /// in - return NULL buffer pointers
  16. /// out - return NULL buffer points
  17. ///
  18. /// cmApBufUpdate()
  19. /// in - incoming samples are set to 0.
  20. /// out - outgoing samples are set to 0.
  21. ///
  22. /// Muted channels: kMuteFl is set
  23. /// cmApBufUpdate()
  24. /// in - incoming samples are set to 0.
  25. /// out - outgoing samples are set to 0.
  26. ///
  27. /// Tone channels: kToneFl is set
  28. /// cmApBufUpdate()
  29. /// in - incoming samples are filled with a 1k sine tone
  30. /// out - outgoing samples are filled with a 1k sine tone
  31. ///
  32. #ifndef cmApBuf_h
  33. #define cmApBuf_h
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37. typedef cmRC_t cmAbRC_t; ///< Result code type
  38. enum
  39. {
  40. kOkAbRC = 0
  41. };
  42. /// Allocate and initialize an audio buffer.
  43. /// devCnt - count of devices this buffer will handle.
  44. /// meterMs - length of the meter buffers in milliseconds (automatically limit to the range:10 to 1000)
  45. cmAbRC_t cmApBufInitialize( unsigned devCnt, unsigned meterMs );
  46. /// Deallocate and release any resource held by an audio buffer allocated via cmApBufInitialize().
  47. cmAbRC_t cmApBufFinalize();
  48. /// Configure a buffer for a given device.
  49. cmAbRC_t cmApBufSetup(
  50. unsigned devIdx, ///< device to setup
  51. double srate, ///< device sample rate (only required for synthesizing the correct test-tone frequency)
  52. unsigned dspFrameCnt, /// dspFrameCnt - count of samples in channel buffers returned via cmApBufGet()
  53. unsigned cycleCnt, ///< number of audio port cycles to store
  54. unsigned inChCnt, ///< input channel count on this device
  55. unsigned inFramesPerCycle, ///< maximum number of incoming sample frames on an audio port cycle
  56. unsigned outChCnt, ///< output channel count on this device
  57. unsigned outFramesPerCycle ///< maximum number of outgoing sample frames in an audio port cycle
  58. );
  59. // Prime the buffer with 'audioCycleCnt' * outFramesPerCycle samples ready to be played
  60. cmAbRC_t cmApBufPrimeOutput( unsigned devIdx, unsigned audioCycleCnt );
  61. /// This function is called asynchronously by the audio device driver to transfer incoming samples to the
  62. /// the buffer and to send outgoing samples to the DAC. This function is
  63. /// intended to be called from the audio port callback function (\see cmApCallbackPtr_t).
  64. /// This function is thread-safe under the condition where the audio device uses
  65. /// different threads for input and output.
  66. ///
  67. /// Enable Flag:
  68. /// Input: If an input channel is disabled then the incoming samples are replaced with zeros.
  69. /// Output: If an output channel is disabled then the packet samples are set to zeros.
  70. ///
  71. /// Tone Flag:
  72. /// Input: If the tone flag is set on an input channel then the incoming samples are set to a sine tone.
  73. /// Output: If the tone flag is set on an output channel then the packet samples are set to a sine tone.
  74. ///
  75. /// The enable flag has higher precedence than the tone flag therefore disabled channels
  76. /// will be set to zero even if the tone flag is set.
  77. cmAbRC_t cmApBufUpdate(
  78. cmApAudioPacket_t* inPktArray, ///< full audio packets from incoming audio (from ADC)
  79. unsigned inPktCnt, ///< count of incoming audio packets
  80. cmApAudioPacket_t* outPktArray, ///< empty audio packet for outgoing audio (to DAC)
  81. unsigned outPktCnt ///< count of outgoing audio packets
  82. );
  83. /// Channel flags
  84. enum
  85. {
  86. kInApFl = 0x01, ///< Identify an input channel
  87. kOutApFl = 0x02, ///< Identify an output channel
  88. kEnableApFl = 0x04, ///< Set to enable a channel, Clear to disable.
  89. kChApFl = 0x08, ///< Used to enable/disable a channel
  90. kMuteApFl = 0x10, ///< Mute this channel
  91. kToneApFl = 0x20, ///< Generate a tone on this channel
  92. kMeterApFl = 0x40, ///< Turn meter's on/off
  93. kPassApFl = 0x80 ///< Pass input channels throught to the output. Must use cmApBufGetIO() to implement this functionality.
  94. };
  95. /// Return the meter window period as set by cmApBufInitialize()
  96. unsigned cmApBufMeterMs();
  97. // Set the meter update period. THis function limits the value to between 10 and 1000.
  98. void cmApBufSetMeterMs( unsigned meterMs );
  99. /// Returns the channel count set via cmApBufSetup().
  100. unsigned cmApBufChannelCount( unsigned devIdx, unsigned flags );
  101. /// Set chIdx to -1 to enable all channels on this device.
  102. /// Set flags to {kInApFl | kOutApFl} | {kChApFl | kToneApFl | kMeterFl} | { kEnableApFl=on | 0=off }
  103. void cmApBufSetFlag( unsigned devIdx, unsigned chIdx, unsigned flags );
  104. /// Return true if the the flags is set.
  105. bool cmApBufIsFlag( unsigned devIdx, unsigned chIdx, unsigned flags );
  106. /// Set chIdx to -1 to enable all channels on this device.
  107. void cmApBufEnableChannel( unsigned devIdx, unsigned chIdx, unsigned flags );
  108. /// Returns true if an input/output channel is enabled on the specified device.
  109. bool cmApBufIsChannelEnabled(unsigned devIdx, unsigned chIdx, unsigned flags );
  110. /// Set the state of the tone generator on the specified channel.
  111. /// Set chIdx to -1 to apply the change to all channels on this device.
  112. /// Set flags to {kInApFl | kOutApFl} | { kEnableApFl=on | 0=off }
  113. void cmApBufEnableTone( unsigned devIdx, unsigned chIdx, unsigned flags );
  114. /// Returns true if an input/output tone is enabled on the specified device.
  115. bool cmApBufIsToneEnabled(unsigned devIdx, unsigned chIdx, unsigned flags );
  116. /// Mute a specified channel.
  117. /// Set chIdx to -1 to apply the change to all channels on this device.
  118. /// Set flags to {kInApFl | kOutApFl} | { kEnableApFl=on | 0=off }
  119. void cmApBufEnableMute( unsigned devIdx, unsigned chIdx, unsigned flags );
  120. /// Returns true if an input/output channel is muted on the specified device.
  121. bool cmApBufIsMuteEnabled(unsigned devIdx, unsigned chIdx, unsigned flags );
  122. /// Set the specified channel to pass through.
  123. /// Set chIdx to -1 to apply the change to all channels on this device.
  124. /// Set flags to {kInApFl | kOutApFl} | { kEnableApFl=on | 0=off }
  125. void cmApBufEnablePass( unsigned devIdx, unsigned chIdx, unsigned flags );
  126. /// Returns true if pass through is enabled on the specified channel.
  127. bool cmApBufIsPassEnabled(unsigned devIdx, unsigned chIdx, unsigned flags );
  128. /// Turn meter data collection on and off.
  129. /// Set chIdx to -1 to apply the change to all channels on this device.
  130. /// Set flags to {kInApFl | kOutApFl} | { kEnableApFl=on | 0=off }
  131. void cmApBufEnableMeter( unsigned devIdx, unsigned chIdx, unsigned flags );
  132. /// Returns true if an input/output tone is enabled on the specified device.
  133. bool cmApBufIsMeterEnabled(unsigned devIdx, unsigned chIdx, unsigned flags );
  134. /// Return the meter value for the requested channel.
  135. /// Set flags to kInApFl | kOutApFl.
  136. cmApSample_t cmApBufMeter(unsigned devIdx, unsigned chIdx, unsigned flags );
  137. /// Set chIdx to -1 to apply the gain to all channels on the specified device.
  138. void cmApBufSetGain( unsigned devIdx, unsigned chIdx, unsigned flags, double gain );
  139. /// Return the current gain seting for the specified channel.
  140. double cmApBufGain( unsigned devIdx, unsigned chIdx, unsigned flags );
  141. /// Get the meter and fault status of the channel input or output channel array of a device.
  142. /// Set 'flags' to { kInApFl | kOutApFl }.
  143. /// The returns value is the count of channels actually written to meterArray.
  144. /// If 'faultCntPtr' is non-NULL then it is set to the faultCnt of the associated devices input or output buffer.
  145. unsigned cmApBufGetStatus( unsigned devIdx, unsigned flags, double* meterArray, unsigned meterCnt, unsigned* faultCntPtr );
  146. /// Do all enabled input/output channels on this device have samples available?
  147. /// 'flags' can be set to either or both kInApFl and kOutApFl
  148. bool cmApBufIsDeviceReady( unsigned devIdx, unsigned flags );
  149. /// This function is called by the application to get full incoming sample buffers and
  150. /// to fill empty outgoing sample buffers.
  151. /// Upon return each element in bufArray[bufChCnt] holds a pointer to a buffer assoicated
  152. /// with an audio channel or to NULL if the channel is disabled.
  153. /// 'flags' can be set to kInApFl or kOutApFl but not both.
  154. /// The buffers pointed to by bufArray[] each contain 'dspFrameCnt' samples. Where
  155. /// 'dspFrameCnt' was set in the earlier call to cmApBufSetup() for this device.
  156. /// (see cmApBufInitialize()).
  157. /// Note that this function just returns audio information it does not
  158. /// change any cmApBuf() internal states.
  159. void cmApBufGet( unsigned devIdx, unsigned flags, cmApSample_t* bufArray[], unsigned bufChCnt );
  160. /// This function replaces calls to cmApBufGet() and implements pass-through and output
  161. /// buffer zeroing:
  162. ///
  163. /// 1) cmApBufGet(in);
  164. /// 2) cmApBufGet(out);
  165. /// 3) Copy through channels marked for 'pass' and set the associated oBufArray[i] channel to NULL.
  166. /// 4) Zero all other enabled output channels.
  167. ///
  168. /// Notes:
  169. /// 1) The oBufArray[] channels that are disabled or marked for pass-through will
  170. /// be set to NULL.
  171. /// 2) The client is required to use this function to implement pass-through internally.
  172. /// 3) This function just returns audio information it does not
  173. /// change any cmApBuf() internal states.
  174. void cmApBufGetIO( unsigned iDevIdx, cmApSample_t* iBufArray[], unsigned iBufChCnt, unsigned oDevIdx, cmApSample_t* oBufArray[], unsigned oBufChCnt );
  175. /// The application calls this function each time it completes processing of a bufArray[]
  176. /// returned from cmApBufGet(). 'flags' can be set to either or both kInApFl and kOutApFl.
  177. /// This function should only be called from the client thread.
  178. void cmApBufAdvance( unsigned devIdx, unsigned flags );
  179. /// Copy all available samples incoming samples from an input device to an output device.
  180. /// The source code for this example is a good example of how an application should use cmApBufGet()
  181. /// and cmApBufAdvance().
  182. void cmApBufInputToOutput( unsigned inDevIdx, unsigned outDevIdx );
  183. /// Print the current buffer state.
  184. void cmApBufReport( cmRpt_t* rpt );
  185. /// Run a buffer usage simulation to test the class. cmAudioPortTest.c calls this function.
  186. void cmApBufTest( cmRpt_t* rpt );
  187. #ifdef __cplusplus
  188. }
  189. #endif
  190. #endif