libcm is a C development framework with an emphasis on audio signal processing applications.
Du kannst nicht mehr als 25 Themen auswählen Themen müssen mit entweder einem Buchstaben oder einer Ziffer beginnen. Sie können Bindestriche („-“) enthalten und bis zu 35 Zeichen lang sein.

cmApBuf.h 11KB

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