// cmRtSys.h // Implements a real-time audio processing engine. // // The audio system is composed a collection of independent sub-systems. // Each sub-system maintains a thread which runs asynchrounsly // from the application, the MIDI devices, and the audio devices. // To faciliate communication between these components each sub-system maintains // two thread-safe data buffers one for control information and a second // for audio data. // // The audio devices are the primary driver for the system. // Callbacks from the audio devices (See #cmApCallbackPtr_t) // inserts incoming audio samples into the audio // record buffers and extracts samples from the playback buffer. // When sufficient incoming samples and outgoing empty buffer space exists // a sub-system thread is waken up by the callback. This triggers a DSP audio // processing cycle which empties/fills the audio buffers. During a DSP // processing cycle control messages from the application and MIDI are blocked and // buffered. Upon completetion of the DSP cycle a control message // transfer cycles occurs - buffered incoming messages are passed to // the DSP system and messages originating in the DSP system are // buffered by the audio system for later pickup by the application // or MIDI system. // // Note that control messages that arrive when the DSP cycle is not // occurring can pass directly through to the DSP system. // // The DSP system sends messages back to the host by calling // cmRtDspToHostFunc_t provided by cmRtSysCtx_t. These // calls are always made from within an audio system call to // audio or control update within cmRtCallback_t. cmRtDspToHostFunc_t // simply stores the message in a message buffer. The host picks // up the message at some later time when it notices that messages // are waiting via polling cmRtSysIsMsgWaiting(). // // Implementation: \n // The audio sub-systems work by maintaining an internal thread // which blocks on a mutex condition variable. // While the thread is blocked the mutex is unlocked allowing messages // to pass directly through to the DSP procedure via cmRtCallback(). // // Periodic calls from running audio devices update the audio buffer. // When the audio buffer has input samples waiting and output space // available the condition variable is signaled, the mutex is // then automatically locked by the system, and the DSP execution // procedure is called via cmRtCallback(). // // Messages arriving while the mutex is locked are queued and // delivered to the DSP procedure at the end of the DSP execution // procedure. // // Usage example and testing code: // See cmRtSysTest(). // \snippet cmRtSys.c cmRtSysTest #ifndef cmRtSys_h #define cmRtSys_h #ifdef __cplusplus extern "C" { #endif // Audio system result codes enum { kOkRtRC = cmOkRC, kThreadErrRtRC, kMutexErrRtRC, kTsQueueErrRtRC, kMsgEnqueueFailRtRC, kAudioDevSetupErrRtRC, kAudioBufSetupErrRtRC, kAudioDevStartFailRtRC, kAudioDevStopFailRtRC, kBufTooSmallRtRC, kNoMsgWaitingRtRC, kMidiSysFailRtRC, kMsgSerializeFailRtRC, kStateBufFailRtRC, kInvalidArgRtRC, kNotInitRtRC, kTimeOutErrRtRC }; enum { kAsDfltMsgQueueByteCnt = 0xffff, kAsDfltDevFramesPerCycle = 512, kAsDfltDspFramesPerCycle = 64, kAsDfltBufCnt = 3, kAsDfltSrate = 44100, kAsDfltSyncToInputFl = 1, kAsDfltMinMeterMs = 10, kAsDfltMeterMs = 50, kAsDfltMaxMeterMs = 1000 }; typedef cmHandle_t cmRtSysH_t; //< Audio system handle type typedef unsigned cmRtRC_t; //< Audio system result code struct cmRtSysCtx_str; // // DSP system callback function. // // This is the sole point of entry into the DSP system while the audio system is running. // // ctxPtr is pointer to a cmRtSysCtx_t record. // // This function is called under two circumstances: // // 1) To notify the DSP system that the audio input/output buffers need to be serviced. // This is a perioidic request which the DSP system uses as its execution trigger. // cmRtSysCtx_t.audioRateFl is set to true to indicate this type of callback. // // 2) To pass messages from the host application to the DSP system. // The DSP system is asyncronous with the host because it executes in the // audio system thread rather than the host thread. The cmRtSysDeliverMsg() // function synchronizes incoming messages with the internal audio system // thread to prevent thread collisions. // // Notes: // This callback is always made with the internal audio system mutex locked. // // The signal time covered by the callback is from // ctx->begSmpIdx to ctx->begSmpIdx+cfg->dspFramesPerCycle. // // The return value is currently not used. typedef cmRC_t (*cmRtCallback_t)(void* ctxPtr, unsigned msgByteCnt, const void* msgDataPtr ); // Audio device sub-sytem configuration record typedef struct cmRtSysArgs_str { cmRpt_t* rpt; // system console object unsigned inDevIdx; // input audio device unsigned outDevIdx; // output audio device bool syncInputFl; // true/false sync the DSP update callbacks with audio input/output unsigned msgQueueByteCnt; // Size of the internal msg queue used to buffer msgs arriving via cmRtSysDeliverMsg(). unsigned devFramesPerCycle; // (512) Audio device samples per channel per device update buffer. unsigned dspFramesPerCycle; // (64) Audio samples per channel per DSP cycle. unsigned audioBufCnt; // (3) Audio device buffers. double srate; // Audio sample rate. } cmRtSysArgs_t; // Audio sub-system configuration record. // This record is provided by the host to configure the audio system // via cmRtSystemAllocate() or cmRtSystemInitialize(). typedef struct cmRtSysSubSys_str { cmRtSysArgs_t args; // Audio device configuration cmRtCallback_t cbFunc; // DSP system entry point function. void* cbDataPtr; // Host provided data for the DSP system callback. } cmRtSysSubSys_t; // Signature of a callback function provided by the audio system to receive messages // from the DSP system for later dispatch to the host application. // This declaration is used by the DSP system implementation and the audio system. // Note that this function is intended to convey one message broken into multiple parts. // See cmTsQueueEnqueueSegMsg() for the equivalent interface. typedef cmRtRC_t (*cmRtDspToHostFunc_t)(struct cmRtSysCtx_str* p, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt); // Record passed with each call to the DSP callback function cmRtCallback_t typedef struct cmRtSysCtx_str { void* reserved; // used internally by the audio system bool audioRateFl; // true if this is an audio update callback unsigned srcNetNodeId; // Source net node if this is a msg callback originating from a remote network node. unsigned rtSubIdx; // index of the sub-system this DSP process is serving cmRtSysSubSys_t* ss; // ptr to a copy of the cfg recd used to initialize the audio system unsigned begSmpIdx; // gives signal time as a sample count cmRtDspToHostFunc_t dspToHostFunc; // Callback used by the DSP process to send messages to the host // via the audio system. Returns a cmRtRC_t result code. // output (playback) buffers cmSample_t** oChArray; // each ele is a ptr to buffer with cfg.dspFramesPerCycle samples unsigned oChCnt; // count of output channels (ele's in oChArray[]) // input (recording) buffers cmSample_t** iChArray; // each ele is a ptr to buffer with cfg.dspFramesPerCycle samples unsigned iChCnt; // count of input channels (ele's in iChArray[]) } cmRtSysCtx_t; // Audio system configuration record used by cmRtSysAllocate(). typedef struct cmRtSysCfg_str { cmRtSysSubSys_t* ssArray; // sub-system cfg record array unsigned ssCnt; // count of sub-systems unsigned meterMs; // Meter sample period in milliseconds void* clientCbData; // User arg. for clientCbFunc(). cmTsQueueCb_t clientCbFunc; // Called by cmRtSysReceiveMsg() to deliver internally generated msg's to the host. // Set to NULL if msg's will be directly returned by buffers passed to cmRtSysReceiveMsg(). cmUdpNetH_t netH; } cmRtSysCfg_t; extern cmRtSysH_t cmRtSysNullHandle; // Allocate and initialize an audio system as a collection of 'cfgCnt' sub-systems. // Prior to call this function the audio audio ports system must be initalized // (via cmApInitialize()) and the MIDI port system must be initialized // (via cmMpInitialize()). Note also that cmApFinalize() and cmMpFinalize() // cannot be called prior to cmRtSysFree(). // See cmRtSystemTest() for a complete example. cmRtRC_t cmRtSysAllocate( cmRtSysH_t* hp, cmRpt_t* rpt, const cmRtSysCfg_t* cfg ); // Finalize and release any resources held by the audio system. cmRtRC_t cmRtSysFree( cmRtSysH_t* hp ); // Returns true if 'h' is a handle which was successfully allocated by // cmRtSysAllocate(). bool cmRtSysHandleIsValid( cmRtSysH_t h ); // Reinitialize a previously allocated audio system. This function // begins with a call to cmRtSysFinalize(). // Use cmRtSysEnable(h,true) to begin processing audio following this call. cmRtRC_t cmRtSysInitialize( cmRtSysH_t h, const cmRtSysCfg_t* cfg ); // Complements cmRtSysInitialize(). In general there is no need to call this function // since calls to cmRtSysInitialize() and cmRtSysFree() automaticatically call it. cmRtRC_t cmRtSysFinalize( cmRtSysH_t h ); // Returns true if the audio system has been successfully initialized. bool cmRtSysIsInitialized( cmRtSysH_t ); // Returns true if the audio system is enabled. bool cmRtSysIsEnabled( cmRtSysH_t h ); // Enable/disable the audio system. Enabling the starts audio stream // in/out of the system. cmRtRC_t cmRtSysEnable( cmRtSysH_t h, bool enableFl ); // // DSP to Host delivery function // // This function is used to pass messages from a DSP process to the HOST it // is always called from within the real-time thread. cmRtRC_t cmRtSysDspToHostSegMsg( cmRtSysH_t h, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt); cmRtRC_t cmRtSysDspToHost( cmRtSysH_t h, const void* msgDataPtr, unsigned msgByteCnt); // // Host to DSP delivery functions // // Deliver a message from the host application to the DSP process. (host -> DSP); // The message is formed as a concatenation of the bytes in each of the segments // pointed to by 'msgDataPtrArrary[segCnt][msgByteCntArray[segCnt]'. // This is the canonical msg delivery function in so far as the other host->DSP // msg delivery function are written in terms of this function. // The first 4 bytes in the first segment must contain the index of the audio sub-system // which is to receive the message. cmRtRC_t cmRtSysDeliverSegMsg( cmRtSysH_t h, const void* msgDataPtrArray[], unsigned msgByteCntArray[], unsigned msgSegCnt, unsigned srcNetNodeId ); // Deliver a single message from the host to the DSP system. cmRtRC_t cmRtSysDeliverMsg( cmRtSysH_t h, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId ); // Deliver a single message from the host to the DSP system. // Prior to delivery the 'id' is prepended to the message. cmRtRC_t cmRtSysDeliverIdMsg( cmRtSysH_t h, unsigned rtSubIdx, unsigned id, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId ); // // DSP to Host message functions // // Is a msg from the DSP waiting to be picked up by the host? (host <- DSP) // 0 = no msgs are waiting or the msg queue is locked by the DSP process. // >0 = the size of the buffer required to hold the next msg returned via // cmRtSysReceiveMsg(). unsigned cmRtSysIsMsgWaiting( cmRtSysH_t h ); // Copy the next available msg sent from the DSP process to the host into the host supplied msg buffer // pointed to by 'msgBufPtr'. Set 'msgDataPtr' to NULL to receive msg by callback from cmRtSysCfg_t.clientCbFunc. // Returns kBufTooSmallRtRC if msgDataPtr[msgByteCnt] is too small to hold the msg. // Returns kNoMsgWaitingRtRC if no messages are waiting for delivery or the msg queue is locked by the DSP process. // Returns kOkRtRC if a msg was delivered. // Call cmRtSysIsMsgWaiting() prior to calling this function to get // the size of the data buffer required to hold the next message. cmRtRC_t cmRtSysReceiveMsg( cmRtSysH_t h, void* msgDataPtr, unsigned msgByteCnt ); // Fill an audio system status record. void cmRtSysStatus( cmRtSysH_t h, unsigned rtSubIdx, cmRtSysStatus_t* statusPtr ); // Enable cmRtSysStatus_t notifications to be sent periodically to the host. // Set rtSubIdx to cmInvalidIdx to enable/disable all sub-systems. // The notifications occur approximately every cmRtSysCfg_t.meterMs milliseconds. void cmRtSysStatusNotifyEnable( cmRtSysH_t, unsigned rtSubIdx, bool enableFl ); // Return a pointer the context record associated with a sub-system cmRtSysCtx_t* cmRtSysContext( cmRtSysH_t h, unsigned rtSubIdx ); // Return the count of audio sub-systems. // This is the same as the count of cfg recds passed to cmRtSystemInitialize(). unsigned cmRtSysSubSystemCount( cmRtSysH_t h ); // Audio system test and example function. void cmRtSysTest( cmRpt_t* rpt, int argc, const char* argv[] ); #ifdef __cplusplus } #endif #endif