libcm is a C development framework with an emphasis on audio signal processing applications.
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

cmRtSys.h 15KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336
  1. //( { file_desc:"Improved real-time audio processing engine." kw:[rtsys] }
  2. //
  3. // The audio system is composed a collection of independent sub-systems.
  4. // Each sub-system maintains a thread which runs asynchrounsly
  5. // from the application, the MIDI devices, and the audio devices.
  6. // To faciliate communication between these components each sub-system maintains
  7. // two thread-safe data buffers one for control information and a second
  8. // for audio data.
  9. //
  10. // The audio devices are the primary driver for the system.
  11. // Callbacks from the audio devices (See #cmApCallbackPtr_t)
  12. // inserts incoming audio samples into the audio
  13. // record buffers and extracts samples from the playback buffer.
  14. // When sufficient incoming samples and outgoing empty buffer space exists
  15. // a sub-system thread is waken up by the callback. This triggers a DSP audio
  16. // processing cycle which empties/fills the audio buffers. During a DSP
  17. // processing cycle control messages from the application and MIDI are blocked and
  18. // buffered. Upon completetion of the DSP cycle a control message
  19. // transfer cycles occurs - buffered incoming messages are passed to
  20. // the DSP system and messages originating in the DSP system are
  21. // buffered by the audio system for later pickup by the application
  22. // or MIDI system.
  23. //
  24. // Note that control messages that arrive when the DSP cycle is not
  25. // occurring can pass directly through to the DSP system.
  26. //
  27. // The DSP system sends messages back to the host by calling
  28. // cmRtDspToHostFunc_t provided by cmRtSysCtx_t. These
  29. // calls are always made from within an audio system call to
  30. // audio or control update within cmRtCallback_t. cmRtDspToHostFunc_t
  31. // simply stores the message in a message buffer. The host picks
  32. // up the message at some later time when it notices that messages
  33. // are waiting via polling cmRtSysIsMsgWaiting().
  34. //
  35. // Implementation: \n
  36. // The audio sub-systems work by maintaining an internal thread
  37. // which blocks on a mutex condition variable.
  38. // While the thread is blocked the mutex is unlocked allowing messages
  39. // to pass directly through to the DSP procedure via cmRtCallback().
  40. //
  41. // Periodic calls from running audio devices update the audio buffer.
  42. // When the audio buffer has input samples waiting and output space
  43. // available the condition variable is signaled, the mutex is
  44. // then automatically locked by the system, and the DSP execution
  45. // procedure is called via cmRtCallback().
  46. //
  47. // Messages arriving while the mutex is locked are queued and
  48. // delivered to the DSP procedure at the end of the DSP execution
  49. // procedure.
  50. //)
  51. #ifndef cmRtSys_h
  52. #define cmRtSys_h
  53. #ifdef __cplusplus
  54. extern "C" {
  55. #endif
  56. //(
  57. // Audio system result codes
  58. enum
  59. {
  60. kOkRtRC = cmOkRC,
  61. kThreadErrRtRC,
  62. kMutexErrRtRC,
  63. kTsQueueErrRtRC,
  64. kMsgEnqueueFailRtRC,
  65. kAudioDevSetupErrRtRC,
  66. kAudioBufSetupErrRtRC,
  67. kAudioDevStartFailRtRC,
  68. kAudioDevStopFailRtRC,
  69. kBufTooSmallRtRC,
  70. kNoMsgWaitingRtRC,
  71. kMidiSysFailRtRC,
  72. kMsgSerializeFailRtRC,
  73. kStateBufFailRtRC,
  74. kInvalidArgRtRC,
  75. kNotInitRtRC,
  76. kTimeOutErrRtRC,
  77. kNetErrRtRC
  78. };
  79. enum
  80. {
  81. kAsDfltMsgQueueByteCnt = 0xffff,
  82. kAsDfltDevFramesPerCycle = 512,
  83. kAsDfltDspFramesPerCycle = 64,
  84. kAsDfltBufCnt = 3,
  85. kAsDfltSrate = 44100,
  86. kAsDfltSyncToInputFl = 1,
  87. kAsDfltMinMeterMs = 10,
  88. kAsDfltMeterMs = 50,
  89. kAsDfltMaxMeterMs = 1000
  90. };
  91. typedef cmHandle_t cmRtSysH_t; //< Audio system handle type
  92. typedef unsigned cmRtRC_t; //< Audio system result code
  93. struct cmRtSysCtx_str;
  94. //
  95. // DSP system callback function.
  96. //
  97. // This is the sole point of entry into the DSP system while the audio system is running.
  98. //
  99. // ctxPtr is pointer to a cmRtSysCtx_t record.
  100. //
  101. // This function is called under two circumstances:
  102. //
  103. // 1) To notify the DSP system that the audio input/output buffers need to be serviced.
  104. // This is a perioidic request which the DSP system uses as its execution trigger.
  105. // cmRtSysCtx_t.audioRateFl is set to true to indicate this type of callback.
  106. //
  107. // 2) To pass messages from the host application to the DSP system.
  108. // The DSP system is asyncronous with the host because it executes in the
  109. // audio system thread rather than the host thread. The cmRtSysDeliverMsg()
  110. // function synchronizes incoming messages with the internal audio system
  111. // thread to prevent thread collisions.
  112. //
  113. // Notes:
  114. // This callback is always made with the internal audio system mutex locked.
  115. //
  116. // The signal time covered by the callback is from
  117. // ctx->begSmpIdx to ctx->begSmpIdx+cfg->dspFramesPerCycle.
  118. //
  119. // The return value is currently not used.
  120. typedef cmRC_t (*cmRtCallback_t)(void* ctxPtr, unsigned msgByteCnt, const void* msgDataPtr );
  121. // Network nodes
  122. typedef struct
  123. {
  124. const cmChar_t* label; // Remote node label or NULL if this is the local node.
  125. const cmChar_t* ipAddr; // IP address in xxx.xxx.xxx.xxx form or NULL for 'localhost'.
  126. cmUdpPort_t ipPort; // IP port
  127. } cmRtSysNetNode_t;
  128. // Local endpoints.
  129. typedef struct
  130. {
  131. const cmChar_t* label; // Local endpoint label
  132. unsigned id; // Local endpoint id
  133. } cmRtSysNetEndpt_t;
  134. // Audio device sub-sytem configuration record
  135. typedef struct cmRtSysArgs_str
  136. {
  137. cmRpt_t* rpt; // system console object
  138. unsigned inDevIdx; // input audio device
  139. unsigned outDevIdx; // output audio device
  140. bool syncInputFl; // true/false sync the DSP update callbacks with audio input/output
  141. unsigned msgQueueByteCnt; // Size of the internal msg queue used to buffer msgs arriving via cmRtSysDeliverMsg().
  142. unsigned devFramesPerCycle; // (512) Audio device samples per channel per device update buffer.
  143. unsigned dspFramesPerCycle; // (64) Audio samples per channel per DSP cycle.
  144. unsigned audioBufCnt; // (3) Audio device buffers.
  145. double srate; // Audio sample rate.
  146. int srateMult;
  147. } cmRtSysArgs_t;
  148. // Audio sub-system configuration record.
  149. // This record is provided by the host to configure the audio system
  150. // via cmRtSystemAllocate() or cmRtSystemInitialize().
  151. typedef struct cmRtSysSubSys_str
  152. {
  153. cmRtSysArgs_t args; // Audio device configuration
  154. cmRtCallback_t cbFunc; // DSP system entry point function.
  155. void* cbDataPtr; // Host provided data for the DSP system callback.
  156. const cmChar_t* bcastAddr; // Network broadcast address.
  157. const cmChar_t* localNodeLabel; // Network local node address.
  158. const cmChar_t* localIpAddr; // Network local IP address (default:NULL to use any available address)
  159. cmUdpPort_t localIpPort; // Network local socket port address
  160. cmRtSysNetEndpt_t* endptArray; // Local end points
  161. unsigned endptCnt; // Count of local endpoints.
  162. } cmRtSysSubSys_t;
  163. // Signature of a callback function provided by the audio system to receive messages
  164. // from the DSP system for later dispatch to the host application.
  165. // This declaration is used by the DSP system implementation and the audio system.
  166. // Note that this function is intended to convey one message broken into multiple parts.
  167. // See cmTsQueueEnqueueSegMsg() for the equivalent interface.
  168. typedef cmRtRC_t (*cmRtDspToHostFunc_t)(struct cmRtSysCtx_str* p, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt);
  169. // Record passed with each call to the DSP callback function cmRtCallback_t
  170. typedef struct cmRtSysCtx_str
  171. {
  172. void* reserved; // used internally by the audio system
  173. bool audioRateFl; // true if this is an audio update callback
  174. unsigned srcNetNodeId; // Source net node if this is a msg callback originating from a remote network node.
  175. unsigned rtSubIdx; // index of the sub-system this DSP process is serving
  176. cmRtSysSubSys_t* ss; // ptr to a copy of the cfg recd used to initialize the audio system
  177. unsigned begSmpIdx; // gives signal time as a sample count
  178. cmRtDspToHostFunc_t dspToHostFunc; // Callback used by the DSP process to send messages to the host
  179. // via the audio system. Returns a cmRtRC_t result code.
  180. // output (playback) buffers
  181. cmSample_t** oChArray; // each ele is a ptr to buffer with cfg.dspFramesPerCycle samples
  182. unsigned oChCnt; // count of output channels (ele's in oChArray[])
  183. cmTimeSpec_t oTimeStamp;
  184. // input (recording) buffers
  185. cmSample_t** iChArray; // each ele is a ptr to buffer with cfg.dspFramesPerCycle samples
  186. unsigned iChCnt; // count of input channels (ele's in iChArray[])
  187. cmTimeSpec_t iTimeStamp;
  188. } cmRtSysCtx_t;
  189. extern cmRtSysH_t cmRtSysNullHandle;
  190. // Allocate and initialize an audio system as a collection of 'cfgCnt' sub-systems.
  191. // Prior to call this function the audio audio ports system must be initalized
  192. // (via cmApInitialize()) and the MIDI port system must be initialized
  193. // (via cmMpInitialize()). Note also that cmApFinalize() and cmMpFinalize()
  194. // cannot be called prior to cmRtSysFree().
  195. // See cmRtSystemTest() for a complete example.
  196. cmRtRC_t cmRtSysAllocate( cmRtSysH_t* hp, cmCtx_t* ctx );
  197. // Finalize and release any resources held by the audio system.
  198. cmRtRC_t cmRtSysFree( cmRtSysH_t* hp );
  199. // Returns true if 'h' is a handle which was successfully allocated by
  200. // cmRtSysAllocate().
  201. bool cmRtSysHandleIsValid( cmRtSysH_t h );
  202. // clientCbFunc is Called by cmRtSysReceiveMsg() to deliver internally generated msg's to the host.
  203. // Set to NULL if msg's will be directly returned by buffers passed to cmRtSysReceiveMsg().
  204. cmRtRC_t cmRtSysBeginCfg( cmRtSysH_t h, cmTsQueueCb_t clientCbFunc, void* clientCbArg, unsigned meterMs, unsigned ssCnt );
  205. // Reinitialize a previously allocated audio system. This function
  206. // begins with a call to cmRtSysFinalize().
  207. // Use cmRtSysEnable(h,true) to begin processing audio following this call.
  208. cmRtRC_t cmRtSysCfg( cmRtSysH_t h, const cmRtSysSubSys_t* ss, unsigned rtSubIdx );
  209. cmRtRC_t cmRtSysEndCfg( cmRtSysH_t h );
  210. // Complements cmRtSysInitialize(). In general there is no need to call this function
  211. // since calls to cmRtSysInitialize() and cmRtSysFree() automaticatically call it.
  212. cmRtRC_t cmRtSysFinalize( cmRtSysH_t h );
  213. // Returns true if the audio system has been successfully initialized.
  214. bool cmRtSysIsInitialized( cmRtSysH_t );
  215. // Returns true if the audio system is enabled.
  216. bool cmRtSysIsEnabled( cmRtSysH_t h );
  217. // Enable/disable the audio system. Enabling the starts audio stream
  218. // in/out of the system.
  219. cmRtRC_t cmRtSysEnable( cmRtSysH_t h, bool enableFl );
  220. //
  221. // DSP to Host delivery function
  222. //
  223. // This function is used to pass messages from a DSP process to the HOST it
  224. // is always called from within the real-time thread.
  225. cmRtRC_t cmRtSysDspToHostSegMsg( cmRtSysH_t h, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt);
  226. cmRtRC_t cmRtSysDspToHost( cmRtSysH_t h, const void* msgDataPtr, unsigned msgByteCnt);
  227. //
  228. // Host to DSP delivery functions
  229. //
  230. // Deliver a message from the host application to the DSP process. (host -> DSP);
  231. // The message is formed as a concatenation of the bytes in each of the segments
  232. // pointed to by 'msgDataPtrArrary[segCnt][msgByteCntArray[segCnt]'.
  233. // This is the canonical msg delivery function in so far as the other host->DSP
  234. // msg delivery function are written in terms of this function.
  235. // The first 4 bytes in the first segment must contain the index of the audio sub-system
  236. // which is to receive the message.
  237. cmRtRC_t cmRtSysDeliverSegMsg( cmRtSysH_t h, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt, unsigned srcNetNodeId );
  238. // Deliver a single message from the host to the DSP system.
  239. cmRtRC_t cmRtSysDeliverMsg( cmRtSysH_t h, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId );
  240. // Deliver a single message from the host to the DSP system.
  241. // Prior to delivery the 'id' is prepended to the message.
  242. cmRtRC_t cmRtSysDeliverIdMsg( cmRtSysH_t h, unsigned rtSubIdx, unsigned id, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId );
  243. //
  244. // DSP to Host message functions
  245. //
  246. // Is a msg from the DSP waiting to be picked up by the host? (host <- DSP)
  247. // 0 = no msgs are waiting or the msg queue is locked by the DSP process.
  248. // >0 = the size of the buffer required to hold the next msg returned via
  249. // cmRtSysReceiveMsg().
  250. unsigned cmRtSysIsMsgWaiting( cmRtSysH_t h );
  251. // Copy the next available msg sent from the DSP process to the host into the host supplied msg buffer
  252. // pointed to by 'msgBufPtr'. Set 'msgDataPtr' to NULL to receive msg by callback from cmRtSysCfg_t.clientCbFunc.
  253. // Returns kBufTooSmallRtRC if msgDataPtr[msgByteCnt] is too small to hold the msg.
  254. // Returns kNoMsgWaitingRtRC if no messages are waiting for delivery or the msg queue is locked by the DSP process.
  255. // Returns kOkRtRC if a msg was delivered.
  256. // Call cmRtSysIsMsgWaiting() prior to calling this function to get
  257. // the size of the data buffer required to hold the next message.
  258. cmRtRC_t cmRtSysReceiveMsg( cmRtSysH_t h, void* msgDataPtr, unsigned msgByteCnt );
  259. // Fill an audio system status record.
  260. void cmRtSysStatus( cmRtSysH_t h, unsigned rtSubIdx, cmRtSysStatus_t* statusPtr );
  261. // Enable cmRtSysStatus_t notifications to be sent periodically to the host.
  262. // Set rtSubIdx to cmInvalidIdx to enable/disable all sub-systems.
  263. // The notifications occur approximately every cmRtSysCfg_t.meterMs milliseconds.
  264. void cmRtSysStatusNotifyEnable( cmRtSysH_t, unsigned rtSubIdx, bool enableFl );
  265. // Return a pointer the context record associated with a sub-system
  266. cmRtSysCtx_t* cmRtSysContext( cmRtSysH_t h, unsigned rtSubIdx );
  267. // Enable non-block mode. In this mode audio I/O is disabled
  268. // and the DSP callback is made every noBlockSleepMs milliseconds.
  269. cmRtRC_t cmRtSysEnableNoBlockMode( cmRtSysH_t h, unsigned rtSubIdx, bool enaFl, unsigned noBlockSleepMs );
  270. // Return the count of audio sub-systems.
  271. // This is the same as the count of cfg recds passed to cmRtSystemInitialize().
  272. unsigned cmRtSysSubSystemCount( cmRtSysH_t h );
  273. // Audio system test and example function.
  274. void cmRtSysTest( cmCtx_t* ctx, int argc, const char* argv[] );
  275. bool cmRtSysNetIsInitialized( cmRtSysH_t h );
  276. cmRtRC_t cmRtSysNetDoSync( cmRtSysH_t h );
  277. cmRtRC_t cmRtSysNetReport( cmRtSysH_t h );
  278. cmRtRC_t cmRtSysNetReportSyncEnable( cmRtSysH_t h, bool enableFl );
  279. cmRtRC_t cmRtSysNetGetHandle( cmRtSysH_t h, unsigned rtSubIdx, cmRtNetH_t* hp );
  280. //)
  281. #ifdef __cplusplus
  282. }
  283. #endif
  284. #endif