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.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182
  1. #ifndef cmAudDspIF_h
  2. #define cmAudDspIF_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. // This class provides a two-way interface to the audio DSP system.
  7. // It is designed to work independenty of the physical
  8. // method of communication. For example, when used by
  9. // cmAudDspLocal, it supports in memory transfer of messages
  10. // between the application and the audio-DSP engine.
  11. // Another implementation however could use it to support
  12. // a networked communication scheme to a remote audio-DSP
  13. // system. Note that in either case, however, this class
  14. // resides with, and is linked to, the application, and not
  15. // the engine.
  16. // This API has two basic responsibilities:
  17. //
  18. // 1) Provides a function based interface to the audio DSP system for the
  19. // client application. This is more convenient, and safer, than the lower level
  20. // message based interface provided by cmAudDsp.h.
  21. // The client calls these API functions to send commands to the audio DSP
  22. // system. Internally the cmAdIfxxx functions converts the commands to
  23. // raw message packets and passes them to a transmission service
  24. // via cmAdIfParm_t audioDspFunc().
  25. //
  26. // 2) Acts as the receiver of raw message streams from whatever external
  27. // service (e.g. cmAudDspLocal, cmAudDspUdp) is receiving raw message packets
  28. // from audio DSP system.
  29. //
  30. // This process is driven by periodic calls from the client to
  31. // cmAdIfDispatchMsgToHost().
  32. // cmAdIfDispatchMsgToHost() then generates an internal
  33. // 'kClientMsgPollDuiId' msg which is passed toward the
  34. // cmAudDsp system.
  35. // When the msg encounters a sub-system with queued msgs waiting
  36. // for the client a callback chain ensues which eventually
  37. // calls cmAdIfRecvAudDspMsg() which in turn calls the appropriate
  38. // client provided cmAdIfDispatch_t function (ssInitFunc,statusFunc or uiFunc).
  39. // Note that this entire chain of calls occurs in the client thread
  40. // and in the context of the cmAdIfDispatchMsgToHost() procedure.
  41. enum
  42. {
  43. kOkAiRC = cmOkRC,
  44. kAudDspFailAiRC,
  45. kLHeapFailAiRC,
  46. kUnknownMsgTypeAiRC,
  47. kMsgCorruptAiRC,
  48. kSendFailAiRC,
  49. kQueueFailAiRC,
  50. kNoMsgAiRC,
  51. kJsonFailAiRC,
  52. kDeserialFailAiRC,
  53. kFileSysFailAiRC
  54. };
  55. typedef cmRC_t cmAiRC_t;
  56. typedef cmHandle_t cmAiH_t;
  57. // These functions are provided by the client to receive messages
  58. // from the audio DSP sytem. These functions are only called from the client thread
  59. // from within cmAdIfDispatchMsgToHost().
  60. typedef struct
  61. {
  62. void* cbDataPtr; // data to send as the first arg. to app. callbacks
  63. cmRC_t (*ssInitFunc)( void* cbDataPtr, const cmAudioSysSsInitMsg_t* r, const char* iDevLabel, const char* oDevLabel );
  64. cmRC_t (*statusFunc)( void* cbDataPtr, const cmAudioSysStatus_t* r, const double* iMeterArray, const double* oMeterArray );
  65. cmRC_t (*uiFunc)( void* cbDataPtr, const cmDspUiHdr_t* r );
  66. } cmAdIfDispatch_t;
  67. typedef struct
  68. {
  69. cmAdIfDispatch_t dispatchRecd; // client application callback pointers
  70. cmMsgSendFuncPtr_t audDspFunc; // the cmAdIfXXX functions use the callback to send msgs to the audio DSP system.
  71. void* audDspFuncDataPtr; // data to send with the audio DSP callback function
  72. } cmAdIfParm_t;
  73. extern cmAiH_t cmAiNullHandle;
  74. cmAiRC_t cmAdIfAllocate( cmCtx_t* ctx, cmAiH_t* hp, const cmAdIfParm_t* parms );
  75. cmAiRC_t cmAdIfFree( cmAiH_t* hp );
  76. bool cmAdIfIsValid( cmAiH_t h );
  77. // Receive a msg from the audio DSP system. This is the main point of entry
  78. // for all calls from the audio DSP system to the client.
  79. // This function is provided as a callback to the owner of this cmAudDspIF
  80. // (e.g. cmAudDspLocal, cmAudDspUdpClient) it should never need to be called
  81. // by the client.
  82. cmAiRC_t cmAdIfRecvAudDspMsg( cmAiH_t h, unsigned msgByteCnt, const void* msgDataPtr);
  83. //-------------------------------------------------------------------------
  84. //
  85. // The functions below are used to send commands to the audio DSP system
  86. // from the client application.
  87. //
  88. // Print a hardware report.
  89. cmAiRC_t cmAdIfDeviceReport( cmAiH_t h );
  90. // Select a audio system configuration. This must be done prior to
  91. // sending any other commands.
  92. cmAiRC_t cmAdIfSetAudioSysCfg( cmAiH_t h, unsigned asCfgIdx );
  93. // Select an audio input or output device for a given audio sub-system.
  94. // An audio configuration must have been selected via cmAdIfSetAudioSysCfg()
  95. // prior to calling this function.
  96. cmAiRC_t cmAdIfSetAudioDevice( cmAiH_t h, unsigned asSubIdx, bool inputFl, unsigned devIdx );
  97. // Set the sample rate for a given audio sub-system or the entire audio system.
  98. // Set asSubIdx to cmInvalidIdx to assign the sample rate to all sub-systems
  99. // of the current audio system configuration.
  100. // An audio configuration must have been selected via cmAdIfSetAudioSysCfg()
  101. // prior to calling this function.
  102. cmAiRC_t cmAdIfSetSampleRate( cmAiH_t h, unsigned asSubIdx, double srate );
  103. // Select a DSP program for a given audio sub-system or the entire audio system.
  104. // Set asSubIdx to cmInvalidIdx to load the program on all sub-systems
  105. // of the current audio system configuration.
  106. // An audio configuration must have been selected via cmAdIfSetAudioSysCfg()
  107. // prior to calling this function.
  108. cmAiRC_t cmAdIfLoadProgram( cmAiH_t h, unsigned asSubIdx, unsigned pgmIdx );
  109. // Print a representation (instances and connections) of the loaded program
  110. // to a JSON file.
  111. cmAiRC_t cmAdIfPrintPgm( cmAiH_t h, unsigned asSubIdx, const cmChar_t* fn );
  112. // Start the audio streaming.
  113. // An audio configuration must have been selected via cmAdIfSetAudioSysCfg()
  114. // and a DSP program must have been selected via cmAdIfLoadProgram()
  115. // prior to calling this function.
  116. cmAiRC_t cmAdIfEnableAudio( cmAiH_t h, bool enableFl );
  117. // Enable/disable periodic audio system status notifications.
  118. cmAiRC_t cmAdIfEnableStatusNotify( cmAiH_t h, bool enableFl );
  119. // Send a kUiSelAsId style message to the audio DSP system.
  120. cmAiRC_t cmAdIfSendMsgToAudioDSP(
  121. cmAiH_t h,
  122. unsigned asSubIdx,
  123. unsigned msgTypeId,
  124. unsigned selId,
  125. unsigned flags,
  126. unsigned instId,
  127. unsigned instVarId,
  128. const cmDspValue_t* valPtr );
  129. // The client application must periodically call this function to
  130. // receive pending messages from the audio DSP system. The
  131. // messages are delivered via callbacks provided by cmAdIfDispatch_t.
  132. // This function should only be called from the client thread.
  133. cmAiRC_t cmAdIfDispatchMsgToHost( cmAiH_t h );
  134. /*
  135. Local call chain:
  136. cmAdIfDispatchMsgToHost() -> p->parms.audDspFunc = cmAudDspLocal::_cmAdlAudDspSendFunc()
  137. -> cmAudioDsp::cmAudDspReceiveClientMsg()
  138. -> cmAudioDsp::_cmAudDspClientMsgPoll()
  139. -> cmAudioSys::cmAudioSysReceiveMsg()
  140. -> cmThread::cmTs1p1cDequeueMsg()
  141. -> cmAudioSysCfg_t::clientCbFunc = cmAudDsp::_cmAudioSysToClientCallback()
  142. -> cmAudDsp::cmAd_t::cbFunc = cmAudDspLocal::_cmAudDspLocalCallback()
  143. -> cmAudDspIF::cmAdIfRecvAudDspMsg()
  144. -> cmAudDspIF::_cmAiDispatchMsgToClient()
  145. -> cmAudDspIF::cmAdIfDispatch_t.uiFunc = kcApp::_s_handleUiMsg()
  146. */
  147. #ifdef __cplusplus
  148. }
  149. #endif
  150. #endif