libcm is a C development framework with an emphasis on audio signal processing applications.
Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.

cmAudioSys.h 14KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305
  1. // cmAudioSys.h
  2. // Implements a real-time audio processing engine.
  3. //
  4. // The audio system is composed a collection of independent sub-systems.
  5. // Each sub-system maintains a thread which runs asynchrounsly
  6. // from the application, the MIDI devices, and the audio devices.
  7. // To faciliate communication between these components each sub-system maintains
  8. // two thread-safe data buffers one for control information and a second
  9. // for audio data.
  10. //
  11. // The audio devices are the primary driver for the system.
  12. // Callbacks from the audio devices (See #cmApCallbackPtr_t)
  13. // inserts incoming audio samples into the audio
  14. // record buffers and extracts samples from the playback buffer.
  15. // When sufficient incoming samples and outgoing empty buffer space exists
  16. // a sub-system thread is waken up by the callback. This triggers a DSP audio
  17. // processing cycle which empties/fills the audio buffers. During a DSP
  18. // processing cycle control messages from the application and MIDI are blocked and
  19. // buffered. Upon completetion of the DSP cycle a control message
  20. // transfer cycles occurs - buffered incoming messages are passed to
  21. // the DSP system and messages originating in the DSP system are
  22. // buffered by the audio system for later pickup by the application
  23. // or MIDI system.
  24. //
  25. // Note that control messages that arrive when the DSP cycle is not
  26. // occurring can pass directly through to the DSP system.
  27. //
  28. // The DSP system sends messages back to the host by calling
  29. // cmAsDspToHostFunc_t provided by cmAudioSysCtx_t. These
  30. // calls are always made from within an audio system call to
  31. // audio or control update within cmAsCallback_t. cmAsDspToHostFunc_t
  32. // simply stores the message in a message buffer. The host picks
  33. // up the message at some later time when it notices that messages
  34. // are waiting via polling cmAudioSysIsMsgWaiting().
  35. //
  36. // Implementation: \n
  37. // The audio sub-systems work by maintaining an internal thread
  38. // which blocks on a mutex condition variable.
  39. // While the thread is blocked the mutex is unlocked allowing messages
  40. // to pass directly through to the DSP procedure via cmAsCallback().
  41. //
  42. // Periodic calls from running audio devices update the audio buffer.
  43. // When the audio buffer has input samples waiting and output space
  44. // available the condition variable is signaled, the mutex is
  45. // then automatically locked by the system, and the DSP execution
  46. // procedure is called via cmAsCallback().
  47. //
  48. // Messages arriving while the mutex is locked are queued and
  49. // delivered to the DSP procedure at the end of the DSP execution
  50. // procedure.
  51. //
  52. // Usage example and testing code:
  53. // See cmAudioSysTest().
  54. // \snippet cmAudioSys.c cmAudioSysTest
  55. #ifndef cmAudioSys_h
  56. #define cmAudioSys_h
  57. #ifdef __cplusplus
  58. extern "C" {
  59. #endif
  60. // Audio system result codes
  61. enum
  62. {
  63. kOkAsRC = cmOkRC,
  64. kThreadErrAsRC,
  65. kMutexErrAsRC,
  66. kTsQueueErrAsRC,
  67. kMsgEnqueueFailAsRC,
  68. kAudioDevSetupErrAsRC,
  69. kAudioBufSetupErrAsRC,
  70. kAudioDevStartFailAsRC,
  71. kAudioDevStopFailAsRC,
  72. kBufTooSmallAsRC,
  73. kNoMsgWaitingAsRC,
  74. kMidiSysFailAsRC,
  75. kMsgSerializeFailAsRC,
  76. kStateBufFailAsRC,
  77. kInvalidArgAsRC,
  78. kNotInitAsRC
  79. };
  80. enum
  81. {
  82. kAsDfltMsgQueueByteCnt = 0xffff,
  83. kAsDfltDevFramesPerCycle = 512,
  84. kAsDfltDspFramesPerCycle = 64,
  85. kAsDfltBufCnt = 3,
  86. kAsDfltSrate = 44100,
  87. kAsDfltSyncToInputFl = 1,
  88. kAsDfltMinMeterMs = 10,
  89. kAsDfltMeterMs = 50,
  90. kAsDfltMaxMeterMs = 1000
  91. };
  92. typedef cmHandle_t cmAudioSysH_t; //< Audio system handle type
  93. typedef unsigned cmAsRC_t; //< Audio system result code
  94. struct cmAudioSysCtx_str;
  95. //
  96. // DSP system callback function.
  97. //
  98. // This is the sole point of entry into the DSP system while the audio system is running.
  99. //
  100. // ctxPtr is pointer to a cmAudioSysCtx_t record.
  101. //
  102. // This function is called under two circumstances:
  103. //
  104. // 1) To notify the DSP system that the audio input/output buffers need to be serviced.
  105. // This is a perioidic request which the DSP system uses as its execution trigger.
  106. // cmAudioSysCtx_t.audioRateFl is set to true to indicate this type of callback.
  107. //
  108. // 2) To pass messages from the host application to the DSP system.
  109. // The DSP system is asyncronous with the host because it executes in the
  110. // audio system thread rather than the host thread. The cmAudioSysDeliverMsg()
  111. // function synchronizes incoming messages with the internal audio system
  112. // thread to prevent thread collisions.
  113. //
  114. // Notes:
  115. // This callback is always made with the internal audio system mutex locked.
  116. //
  117. // The signal time covered by the callback is from
  118. // ctx->begSmpIdx to ctx->begSmpIdx+cfg->dspFramesPerCycle.
  119. //
  120. // The return value is currently not used.
  121. typedef cmRC_t (*cmAsCallback_t)(void* ctxPtr, unsigned msgByteCnt, const void* msgDataPtr );
  122. // Audio device sub-sytem configuration record
  123. typedef struct cmAudioSysArgs_str
  124. {
  125. cmRpt_t* rpt; // system console object
  126. unsigned inDevIdx; // input audio device
  127. unsigned outDevIdx; // output audio device
  128. bool syncInputFl; // true/false sync the DSP update callbacks with audio input/output
  129. unsigned msgQueueByteCnt; // Size of the internal msg queue used to buffer msgs arriving via cmAudioSysDeliverMsg().
  130. unsigned devFramesPerCycle; // (512) Audio device samples per channel per device update buffer.
  131. unsigned dspFramesPerCycle; // (64) Audio samples per channel per DSP cycle.
  132. unsigned audioBufCnt; // (3) Audio device buffers.
  133. double srate; // Audio sample rate.
  134. } cmAudioSysArgs_t;
  135. // Audio sub-system configuration record.
  136. // This record is provided by the host to configure the audio system
  137. // via cmAudioSystemAllocate() or cmAudioSystemInitialize().
  138. typedef struct cmAudioSysSubSys_str
  139. {
  140. cmAudioSysArgs_t args; // Audio device configuration
  141. cmAsCallback_t cbFunc; // DSP system entry point function.
  142. void* cbDataPtr; // Host provided data for the DSP system callback.
  143. } cmAudioSysSubSys_t;
  144. // Signature of a callback function provided by the audio system to receive messages
  145. // from the DSP system for later dispatch to the host application.
  146. // This declaration is used by the DSP system implementation and the audio system.
  147. // Note that this function is intended to convey one message broken into multiple parts.
  148. // See cmTsQueueEnqueueSegMsg() for the equivalent interface.
  149. typedef cmAsRC_t (*cmAsDspToHostFunc_t)(struct cmAudioSysCtx_str* p, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt);
  150. // Record passed with each call to the DSP callback function cmAsCallback_t
  151. typedef struct cmAudioSysCtx_str
  152. {
  153. void* reserved; // used internally by the audio system
  154. bool audioRateFl; // true if this is an audio update callback
  155. unsigned srcNetNodeId; // Source net node if this is a msg callback originating from a remote network node.
  156. unsigned asSubIdx; // index of the sub-system this DSP process is serving
  157. cmAudioSysSubSys_t* ss; // ptr to a copy of the cfg recd used to initialize the audio system
  158. unsigned begSmpIdx; // gives signal time as a sample count
  159. cmAsDspToHostFunc_t dspToHostFunc; // Callback used by the DSP process to send messages to the host
  160. // via the audio system. Returns a cmAsRC_t result code.
  161. // output (playback) buffers
  162. cmSample_t** oChArray; // each ele is a ptr to buffer with cfg.dspFramesPerCycle samples
  163. unsigned oChCnt; // count of output channels (ele's in oChArray[])
  164. cmTimeSpec_t oTimeStamp;
  165. // input (recording) buffers
  166. cmSample_t** iChArray; // each ele is a ptr to buffer with cfg.dspFramesPerCycle samples
  167. unsigned iChCnt; // count of input channels (ele's in iChArray[])
  168. cmTimeSpec_t iTimeStamp;
  169. } cmAudioSysCtx_t;
  170. // Audio system configuration record used by cmAudioSysAllocate().
  171. typedef struct cmAudioSysCfg_str
  172. {
  173. cmAudioSysSubSys_t* ssArray; // sub-system cfg record array
  174. unsigned ssCnt; // count of sub-systems
  175. unsigned meterMs; // Meter sample period in milliseconds
  176. void* clientCbData; // User arg. for clientCbFunc().
  177. cmTsQueueCb_t clientCbFunc; // Called by cmAudioSysReceiveMsg() to deliver internally generated msg's to the host.
  178. // Set to NULL if msg's will be directly returned by buffers passed to cmAudioSysReceiveMsg().
  179. cmUdpNetH_t netH;
  180. } cmAudioSysCfg_t;
  181. extern cmAudioSysH_t cmAudioSysNullHandle;
  182. // Allocate and initialize an audio system as a collection of 'cfgCnt' sub-systems.
  183. // Prior to call this function the audio audio ports system must be initalized
  184. // (via cmApInitialize()) and the MIDI port system must be initialized
  185. // (via cmMpInitialize()). Note also that cmApFinalize() and cmMpFinalize()
  186. // cannot be called prior to cmAudioSysFree().
  187. // See cmAudioSystemTest() for a complete example.
  188. cmAsRC_t cmAudioSysAllocate( cmAudioSysH_t* hp, cmRpt_t* rpt, const cmAudioSysCfg_t* cfg );
  189. // Finalize and release any resources held by the audio system.
  190. cmAsRC_t cmAudioSysFree( cmAudioSysH_t* hp );
  191. // Returns true if 'h' is a handle which was successfully allocated by
  192. // cmAudioSysAllocate().
  193. bool cmAudioSysHandleIsValid( cmAudioSysH_t h );
  194. // Reinitialize a previously allocated audio system. This function
  195. // begins with a call to cmAudioSysFinalize().
  196. // Use cmAudioSysEnable(h,true) to begin processing audio following this call.
  197. cmAsRC_t cmAudioSysInitialize( cmAudioSysH_t h, const cmAudioSysCfg_t* cfg );
  198. // Complements cmAudioSysInitialize(). In general there is no need to call this function
  199. // since calls to cmAudioSysInitialize() and cmAudioSysFree() automaticatically call it.
  200. cmAsRC_t cmAudioSysFinalize( cmAudioSysH_t h );
  201. // Returns true if the audio system has been successfully initialized.
  202. bool cmAudioSysIsInitialized( cmAudioSysH_t );
  203. // Returns true if the audio system is enabled.
  204. bool cmAudioSysIsEnabled( cmAudioSysH_t h );
  205. // Enable/disable the audio system. Enabling the starts audio stream
  206. // in/out of the system.
  207. cmAsRC_t cmAudioSysEnable( cmAudioSysH_t h, bool enableFl );
  208. //
  209. // Host to DSP delivery functions
  210. //
  211. // Deliver a message from the host application to the DSP process. (host -> DSP);
  212. // The message is formed as a concatenation of the bytes in each of the segments
  213. // pointed to by 'msgDataPtrArrary[segCnt][msgByteCntArray[segCnt]'.
  214. // This is the canonical msg delivery function in so far as the other host->DSP
  215. // msg delivery function are written in terms of this function.
  216. // The first 4 bytes in the first segment must contain the index of the audio sub-system
  217. // which is to receive the message.
  218. cmAsRC_t cmAudioSysDeliverSegMsg( cmAudioSysH_t h, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt, unsigned srcNetNodeId );
  219. // Deliver a single message from the host to the DSP system.
  220. cmAsRC_t cmAudioSysDeliverMsg( cmAudioSysH_t h, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId );
  221. // Deliver a single message from the host to the DSP system.
  222. // Prior to delivery the 'id' is prepended to the message.
  223. cmAsRC_t cmAudioSysDeliverIdMsg( cmAudioSysH_t h, unsigned asSubIdx, unsigned id, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId );
  224. //
  225. // DSP to Host message functions
  226. //
  227. // Is a msg from the DSP waiting to be picked up by the host? (host <- DSP)
  228. // 0 = no msgs are waiting or the msg queue is locked by the DSP process.
  229. // >0 = the size of the buffer required to hold the next msg returned via
  230. // cmAudioSysReceiveMsg().
  231. unsigned cmAudioSysIsMsgWaiting( cmAudioSysH_t h );
  232. // Copy the next available msg sent from the DSP process to the host into the host supplied msg buffer
  233. // pointed to by 'msgBufPtr'. Set 'msgDataPtr' to NULL to receive msg by callback from cmAudioSysCfg_t.clientCbFunc.
  234. // Returns kBufTooSmallAsRC if msgDataPtr[msgByteCnt] is too small to hold the msg.
  235. // Returns kNoMsgWaitingAsRC if no messages are waiting for delivery or the msg queue is locked by the DSP process.
  236. // Returns kOkAsRC if a msg was delivered.
  237. // Call cmAudioSysIsMsgWaiting() prior to calling this function to get
  238. // the size of the data buffer required to hold the next message.
  239. cmAsRC_t cmAudioSysReceiveMsg( cmAudioSysH_t h, void* msgDataPtr, unsigned msgByteCnt );
  240. // Fill an audio system status record.
  241. void cmAudioSysStatus( cmAudioSysH_t h, unsigned asSubIdx, cmAudioSysStatus_t* statusPtr );
  242. // Enable cmAudioSysStatus_t notifications to be sent periodically to the host.
  243. // Set asSubIdx to cmInvalidIdx to enable/disable all sub-systems.
  244. // The notifications occur approximately every cmAudioSysCfg_t.meterMs milliseconds.
  245. void cmAudioSysStatusNotifyEnable( cmAudioSysH_t, unsigned asSubIdx, bool enableFl );
  246. // Return a pointer the context record associated with a sub-system
  247. cmAudioSysCtx_t* cmAudioSysContext( cmAudioSysH_t h, unsigned asSubIdx );
  248. // Return the count of audio sub-systems.
  249. // This is the same as the count of cfg recds passed to cmAudioSystemInitialize().
  250. unsigned cmAudioSysSubSystemCount( cmAudioSysH_t h );
  251. // Audio system test and example function.
  252. void cmAudioSysTest( cmRpt_t* rpt, int argc, const char* argv[] );
  253. #ifdef __cplusplus
  254. }
  255. #endif
  256. #endif