cmRtSys.h/c and cmRtSysMsg.h: Replacement for cmAudioSys.h/c. Initial Commit.

cmUiRtSysMstr.h/c: Renamed from cmUiAudioSys.h/c.

Makefile.am

 cmHDR += src/libcm/cmAudioFile.h src/libcm/cmAudioFileMgr.h src/libcm/cmMsgProtocol.h src/libcm/cmAudioSys.h src/libcm/cmAudioPortFile.h src/libcm/cmAudioFileDev.h 
 cmSRC += src/libcm/cmAudioFile.c src/libcm/cmAudioFileMgr.c src/libcm/cmMsgProtocol.c src/libcm/cmAudioSys.c src/libcm/cmAudioPortFile.c src/libcm/cmAudioFileDev.c
 
-cmHDR += src/libcm/cmDevCfg.h src/libcm/cmUi.h src/libcm/cmUiDrvr.h src/libcm/cmUiAudioSysMstr.h
-cmSRC += src/libcm/cmDevCfg.c src/libcm/cmUi.c src/libcm/cmUiDrvr.c src/libcm/cmUiAudioSysMstr.c
+cmHDR += src/libcm/cmRtSys.h src/libcm/cmUiRtSysMstr.h src/libcm/cmRtSysMsg.h 
+cmHDR += src/libcm/cmRtSys.c src/libcm/cmUiRtSysMstr.c
+
+cmHDR += src/libcm/cmDevCfg.h src/libcm/cmUi.h src/libcm/cmUiDrvr.h 
+cmSRC += src/libcm/cmDevCfg.c src/libcm/cmUi.c src/libcm/cmUiDrvr.c
 
 cmHDR += src/libcm/cmFrameFile.h src/libcm/cmFeatFile.h src/libcm/cmCsv.h src/libcm/cmAudLabelFile.h src/libcm/cmTagFile.h
 cmSRC += src/libcm/cmFrameFile.c src/libcm/cmFeatFile.c src/libcm/cmCsv.c src/libcm/cmAudLabelFile.c src/libcm/cmTagFile.c

cmRtSys.h

+// 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

cmRtSysMsg.h

+#ifndef cmRtSysMsg_h
+#define cmRtSysMsg_h
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+  /// Reserved DSP message selector id's (second field of all host<->audio system messages)
+  enum
+  {
+    kMidiMsgArraySelRtId = 1000,
+    kMidiSysExSelRtId,
+    kUiDrvrSelRtId,    // cmUiDriverArg_t message to/from the UI driver
+    kUiSelRtId,      // cmUiDriverArg-t message from the UI mgr to a client 
+    kUiMstrSelRtId,  // indicates a cmDspUiHdr_t msg containing master control information for the audio system
+    kStatusSelRtId,  // indicates the msg is of type cmRtSysStatus_t
+    kNetSyncSelRtId,   // sent with a cmDspNetMsg_t object  
+  };
+
+  typedef struct
+  {
+    unsigned rtSubIdx;
+    unsigned selId;  // Message selector id See kXXXSelRtId above
+  } cmRtSysMsgHdr_t;
+
+  // All of the UI messages that create a UI control contain an array of integers
+  // as in the 'value' field. The array contains the id's associated with
+  // the different programmable paramters which are part of the control.
+  // For example a slider control has minimum,maximum, step size, and value 
+  // parameters. The location in the array is hard coded according to the
+  // parameters meaning but the actual value of the id is left up to the 
+  // engine. This allows the engine to use whatever values work best for
+  // it on a per instance basis. 
+
+
+  // Header record for all messages between the host and the DSP controllers.
+  typedef struct
+  {
+    cmRtSysMsgHdr_t hdr;
+    unsigned     devIdx;
+    unsigned     chIdx;
+    bool         inFl;
+    unsigned     ctlId;
+    double       value;
+  } cmRtSysMstr_t;
+
+
+
+  /// Control id's used to identify the control type of master contols.
+  enum
+  {
+    kSliderUiRtId = 0,
+    kMeterUiRtId  = 1,
+    kMuteUiRtId   = 2,
+    kToneUiRtId   = 3,
+    kPassUiRtId   = 4
+  };
+
+
+  /// Audio sub-system status record - this message can be transmitted to the host at
+  /// periodic intervals.  See cmRtSysStatusNotifyEnable().
+  /// When transmitted to the host this record acts as the message header.
+  /// This header is followed by two arrays of doubles containing the input and output meter values
+  /// associated with the input and output audio devices.
+  /// Message Layout: [ rtSubIdx kStatusSelId cmRtSysStatus_t iMeterArray[iMeterCnt] oMeterArray[oMeterCnt] ]
+  typedef struct
+  {
+    cmRtSysMsgHdr_t hdr;
+
+    unsigned updateCnt;    ///< count of callbacks from the audio devices.
+    unsigned wakeupCnt;    ///< count of times the audio system thread has woken up after the cond. var has been signaled by the audio update thread.
+    unsigned msgCbCnt;     ///< count of msgs delivered via cmRtCallback() .
+    unsigned audioCbCnt;   ///< count of times the DSP execution was requested via cmRtCallback().    
+
+    unsigned iDevIdx;      ///< Input device index
+    unsigned oDevIdx;      ///< Output device index
+
+    unsigned overflowCnt;  ///< count of times the audio input buffers overflowed
+    unsigned underflowCnt; ///< count of times the audio output buffers underflowed
+    unsigned iMeterCnt;    ///< count of input meter channels
+    unsigned oMeterCnt;    ///< count of output meter channels
+    
+  } cmRtSysStatus_t;
+
+
+  typedef struct
+  {
+    cmRtSysMsgHdr_t hdr;
+    unsigned     devIdx;
+    unsigned     portIdx;
+    unsigned     msgCnt;
+    // cmMidiMsg msgArray[msgCnt]
+  } cmRtSysMidi_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

cmUiRtSysMstr.c

+#include "cmGlobal.h"
+#include "cmFloatTypes.h"
+#include "cmRpt.h"
+#include "cmErr.h"
+#include "cmCtx.h"
+#include "cmMem.h"
+#include "cmMallocDebug.h"
+#include "cmJson.h"
+#include "cmThread.h"
+#include "cmUdpPort.h"
+#include "cmUdpNet.h"
+#include "cmRtSysMsg.h"
+#include "cmRtSys.h"
+#include "cmUiDrvr.h"
+#include "cmUi.h"
+#include "cmUiRtSysMstr.h"
+
+enum
+{
+  kLabelAmId,
+  kInSliderAmId,
+  kInMeterAmId,
+  kInToneAmId,
+  kInPassAmId,
+  kInMuteAmId,
+  kOutSliderAmId,
+  kOutMeterAmId,
+  kOutToneAmId,
+  kOutPassAmId,
+  kOutMuteAmId,
+  kAmCnt
+};
+
+
+enum
+{
+  kMinDb =  24,
+  kMaxDb = -24,
+  kMtrMin  = 0,
+  kMtrMax  = 100
+};
+
+typedef struct cmAmPanel_str
+{
+  unsigned              rtSubIdx;
+
+  unsigned              panelId;
+
+  unsigned              updateId;
+  unsigned              wakeupId;
+  unsigned              msgCbId;
+  unsigned              audioCbId;
+
+  unsigned              updateCnt;
+  unsigned              wakeupCnt;
+  unsigned              msgCbCnt;
+  unsigned              audioCbCnt;
+
+  unsigned              baseOutId;
+  unsigned              iDevIdx;
+  unsigned              oDevIdx;
+  unsigned              iChCnt;
+  unsigned              oChCnt;
+  
+  unsigned              a[ kAmCnt ];
+
+
+  struct cmAmPanel_str* link;
+} cmAmPanel_t;
+
+typedef struct
+{
+  cmErr_t      err;
+  unsigned     appId;
+  cmUiH_t      uiH;
+  cmRtSysH_t   asH;
+  unsigned     nextId;
+  cmAmPanel_t* list;
+} cmAm_t;
+
+cmUiRtMstrH_t cmUiRtMstrNullHandle = cmSTATIC_NULL_HANDLE;
+
+cmAm_t* _cmUiAmHandleToPtr( cmUiRtMstrH_t h )
+{
+  cmAm_t* p = (cmAm_t*)h.h;
+  assert( p!=NULL);
+  return p;
+}
+
+cmAmRC_t _cmUiAmFreePanels( cmAm_t* p, bool callDriverFl )
+{
+  cmAmRC_t       rc = kOkAmRC;
+  cmAmPanel_t* pp = p->list;
+  
+  while( pp != NULL )
+  {
+    cmAmPanel_t* np = pp->link;
+
+    unsigned panelId = pp->panelId;
+
+    if( callDriverFl )
+      if( cmUiClearPanel( p->uiH, p->appId, panelId ) != kOkUiRC )
+      {
+        rc = cmErrMsg(&p->err,kUiFailAmRC,"The panel %i clear failed.",panelId);
+        goto errLabel;
+      }
+
+    cmMemFree(pp);
+
+    pp = np;
+  }
+
+  p->nextId = 0;
+  p->list   = NULL;
+ 
+ errLabel:
+  return rc;
+}
+
+
+cmAmRC_t _cmUiAmFree( cmAm_t* p )
+{
+  _cmUiAmFreePanels(p,false);
+
+  if( cmUiDestroyApp( p->uiH, p->appId ) != kOkUiRC )
+    cmErrMsg(&p->err,kUiFailAmRC,"UI Mgr. app destroy failed.");
+    
+  cmMemFree(p);
+  return kOkAmRC;
+}
+
+cmAmRC_t cmUiRtSysMstrAlloc( cmCtx_t* ctx, cmUiRtMstrH_t* hp, cmUiH_t uiH, cmRtSysH_t asH, unsigned appId )
+{
+  cmAmRC_t rc = kOkAmRC;
+  
+  if((rc = cmUiRtSysMstrFree(hp)) != kOkAmRC )
+    return rc;
+
+  cmAm_t* p = cmMemAllocZ(cmAm_t,1);
+  cmErrSetup(&p->err,&ctx->rpt,"Audio System Master UI");
+
+  p->appId  = appId;
+  p->uiH    = uiH;
+  p->asH    = asH;
+  p->nextId = 0;
+
+    // allocate the UI Mgr. app. slot for the audio system master control UI.
+  if( cmUiCreateApp( uiH, appId, cmInvalidId ) != kOkUiRC )
+  {
+    rc = cmErrMsg(&p->err,kUiFailAmRC,"The UI Mgr. failed while creating the Audio System UI app. slot.");
+    goto errLabel;
+  }
+
+
+  hp->h     = p;
+ errLabel:
+  if( rc != kOkAmRC )
+    _cmUiAmFree(p);
+  return rc;
+}
+
+cmAmRC_t cmUiRtSysMstrFree(  cmUiRtMstrH_t* hp )
+{
+  cmAmRC_t rc = kOkAmRC;
+
+  if(hp==NULL || cmUiRtSysMstrIsValid(*hp)==false )
+    return kOkAmRC;
+
+  cmAm_t* p = _cmUiAmHandleToPtr(*hp);
+
+  if((rc = _cmUiAmFree(p)) != kOkAmRC )
+    return rc;
+
+  hp->h = NULL;
+
+  return rc;
+}
+
+bool     cmUiRtSysMstrIsValid( cmUiRtMstrH_t h )
+{ return h.h != NULL; }
+
+
+cmAmRC_t cmUiRtSysMstrInitialize( cmUiRtMstrH_t amH, const cmRtSysCtx_t* c, const cmChar_t* inDevLabel, const cmChar_t* outDevLabel )
+{
+  cmAmRC_t rc       = kOkAmRC;
+  cmAm_t*  p        = _cmUiAmHandleToPtr(amH);
+  cmUiH_t  uiH      = p->uiH;
+  unsigned panelId  = cmInvalidId;
+  unsigned colW     = 50;
+  unsigned ctlW     = 45;
+  unsigned n        = 31;
+  cmChar_t chNumStr[ n+1 ];
+  int      w;
+  cmAmPanel_t* pp = NULL;
+
+
+  // This function is called once for each audio sub-system.
+  // If this is the first call in the sequence then clear the previous setup.
+  if( c->rtSubIdx == 0 )
+  {
+    if((rc = _cmUiAmFreePanels(p,true)) != kOkAmRC )
+      goto errLabel;
+
+    assert(p->list == NULL );
+  }
+
+  // create the panel recd and link it to the beginning of the list
+  pp = cmMemAllocZ(cmAmPanel_t,1);
+
+  pp->link     = p->list;    
+  p->list      = pp;
+  pp->rtSubIdx = c->rtSubIdx;
+  pp->iDevIdx  = c->ss->args.inDevIdx;
+  pp->oDevIdx  = c->ss->args.outDevIdx;
+  pp->iChCnt   = c->iChCnt;
+  pp->oChCnt   = c->oChCnt;
+
+  
+  pp->panelId           = p->nextId++;  
+  pp->updateId          = p->nextId++;
+  pp->wakeupId          = p->nextId++;
+  pp->msgCbId           = p->nextId++;
+  pp->audioCbId         = p->nextId++;
+
+  pp->a[kLabelAmId]     = p->nextId;
+  pp->a[kInSliderAmId]  = p->nextId += c->iChCnt;
+  pp->a[kInMeterAmId]   = p->nextId += c->iChCnt;
+  pp->a[kInToneAmId]    = p->nextId += c->iChCnt;
+  pp->a[kInPassAmId]    = p->nextId += c->iChCnt;
+  pp->a[kInMuteAmId]    = p->nextId += c->iChCnt;
+
+  pp->baseOutId         = p->nextId += c->iChCnt;  
+
+  pp->a[kOutSliderAmId] = pp->baseOutId;
+  pp->a[kOutMeterAmId]  = p->nextId += c->oChCnt;
+  pp->a[kOutToneAmId]   = p->nextId += c->oChCnt;
+  pp->a[kOutPassAmId]   = p->nextId += c->oChCnt;
+  pp->a[kOutMuteAmId]   = p->nextId += c->oChCnt;
+  p->nextId += c->oChCnt;
+
+  panelId = pp->panelId;
+
+  if( cmUiCreatePanel(uiH, p->appId, panelId, "Master", 0 ) != kOkUiRC )
+  {
+    rc = cmErrMsg(&p->err,kUiFailAmRC,"Panel %i create failed.",panelId);
+    goto errLabel;
+  }
+
+  cmUiSetFillRows( uiH, p->appId, panelId, true );
+  cmUiCreateProgress(uiH, p->appId, panelId, pp->updateId, "Update",  0, 0, 1, 0 );
+  cmUiCreateProgress(uiH, p->appId, panelId, pp->wakeupId, "Wakeup",  0, 0, 1, 0 );
+  cmUiCreateProgress(uiH, p->appId, panelId, pp->msgCbId,  "Message", 0, 0, 1, 0 );
+  cmUiCreateProgress(uiH, p->appId, panelId, pp->audioCbId,"Audio",   0, 0, 1, 0 );
+  cmUiSetFillRows( uiH, p->appId, panelId, false );
+
+  cmUiNewLine(     uiH, p->appId, panelId );
+  cmUiCreateLabel( uiH, p->appId, panelId, cmInvalidId, inDevLabel, kInsideUiFl | kLeftUiFl ); 
+  cmUiNewLine(     uiH, p->appId, panelId );
+
+  unsigned i;
+  for(i=0; i<c->iChCnt; ++i)
+  {
+    snprintf(chNumStr,n,"%i",i);
+    
+    cmUiSetNextW(     uiH, p->appId, panelId, ctlW );
+    cmUiCreateLabel(  uiH, p->appId, panelId, cmInvalidId, chNumStr, 0 );
+    cmUiCreateVSlider(uiH, p->appId, panelId, pp->a[kInSliderAmId] + i, NULL,     0, kMinDb,  kMaxDb, 0.1, 0 );
+    cmUiPlaceRight(   uiH, p->appId, panelId );
+    cmUiCreateVMeter( uiH, p->appId, panelId, pp->a[kInMeterAmId]  + i, NULL,     0, kMtrMin, kMtrMax, 0 ); 
+    w = cmUiSetW(     uiH, p->appId, panelId, ctlW );
+    cmUiCreateCheck(  uiH, p->appId, panelId, pp->a[kInToneAmId]   + i, "T",      0, false );
+    cmUiCreateCheck(  uiH, p->appId, panelId, pp->a[kInPassAmId]   + i, "P",      0, false );
+    cmUiCreateCheck(  uiH, p->appId, panelId, pp->a[kInMuteAmId]   + i, "M",      0, false );
+    cmUiSetW(         uiH, p->appId, panelId, w );
+    cmUiSetBaseCol( uiH, p->appId, panelId, 5 + (i+1)*colW);
+  }
+
+  cmUiSetBaseCol(  uiH, p->appId, panelId, 0);
+  cmUiNewLine(     uiH, p->appId, panelId );
+  cmUiCreateLabel( uiH,p->appId, panelId, cmInvalidId, outDevLabel, kInsideUiFl | kLeftUiFl ); 
+  cmUiNewLine(     uiH, p->appId, panelId );
+
+  for(i=0; i<c->oChCnt; ++i)
+  {
+    snprintf(chNumStr,n,"%i",i);
+    
+    cmUiSetNextW(     uiH, p->appId, panelId, ctlW );
+    cmUiCreateLabel(  uiH, p->appId, panelId, cmInvalidId, chNumStr, 0 );
+    cmUiCreateVSlider(uiH, p->appId, panelId, pp->a[kOutSliderAmId] + i, NULL,     0, kMinDb,  kMaxDb, 0.1, 0 );
+    cmUiPlaceRight(   uiH, p->appId, panelId );
+    cmUiCreateVMeter( uiH, p->appId, panelId, pp->a[kOutMeterAmId]  + i, NULL,     0, kMtrMin, kMtrMax, 0 ); 
+    w = cmUiSetW(     uiH, p->appId, panelId, ctlW );
+    cmUiCreateCheck(  uiH, p->appId, panelId, pp->a[kOutToneAmId]   + i, "T",      0, false );
+    cmUiCreateCheck(  uiH, p->appId, panelId, pp->a[kOutPassAmId]   + i, "P",      0, false );
+    cmUiCreateCheck(  uiH, p->appId, panelId, pp->a[kOutMuteAmId]   + i, "M",      0, false );
+    cmUiSetW(         uiH, p->appId, panelId, w );
+    cmUiSetBaseCol( uiH, p->appId, panelId, 5 + (i+1)*colW);
+  }
+
+ errLabel:
+  return rc;
+}
+
+
+cmAmPanel_t* _cmUiAmFindPanel( cmAm_t* p, unsigned panelId, bool errFl )
+{
+  cmAmPanel_t* pp = p->list;
+  for(; pp!=NULL; pp=pp->link)
+    if( pp->panelId == panelId )
+      return pp;
+
+  if( errFl )
+    cmErrMsg(&p->err,kPanelNotFoundAmRC,"The panel %i was not found.",panelId);
+
+  return NULL;
+}
+
+unsigned  _cmUiAmCtlTypeId( cmAm_t* p, cmAmPanel_t* pp, cmUiCId_t cId, unsigned usrId,
+  unsigned                          sliderId, unsigned toneId, unsigned passId, unsigned muteId )
+{
+    switch( cId )
+    {
+      case kSliderUiCId:
+        assert( pp->a[sliderId] <= usrId && usrId < pp->a[sliderId]+pp->oChCnt);
+        return sliderId;
+        break;
+
+      case kCheckUiCId:
+        if( pp->a[toneId] <= usrId && usrId < pp->a[toneId]+pp->oChCnt )
+          return toneId;
+
+        if( pp->a[passId] <= usrId && usrId < pp->a[passId]+pp->oChCnt )
+          return passId;
+
+        if( pp->a[muteId] <= usrId && usrId < pp->a[muteId]+pp->oChCnt )
+          return muteId;
+        break;
+
+      default:
+        break;
+    
+  }
+
+  return cmInvalidId;
+}
+
+
+cmUiRC_t cmUiRtSysMstrOnUiEvent( cmUiRtMstrH_t h, const cmUiDriverArg_t* a )
+{
+  cmUiRC_t      rc       = kOkUiRC;
+  cmAm_t*       p        = _cmUiAmHandleToPtr(h);
+  cmAmPanel_t*  pp;
+  cmRtSysMstr_t r;
+  unsigned      typeId;
+  bool          tabSelFl = a->dId==kSetValDId && a->cId == kPanelUiCId;
+  
+  if((pp = _cmUiAmFindPanel( p, a->panelId, !tabSelFl )) == NULL)
+  {
+    if( tabSelFl )
+      return kOkUiRC;
+
+    return cmErrLastRC(&p->err);
+  }
+
+  // if the panel tab was selected/deslected ival will be equal to 1/0
+  if( a->usrId == pp->panelId )
+  {
+    cmRtSysStatusNotifyEnable(p->asH, pp->rtSubIdx, a->ival );
+    return rc;
+  }
+
+  // based on the usrId determine which control generated the event
+  if( a->usrId >= pp->baseOutId )
+    typeId = _cmUiAmCtlTypeId(p,pp,a->cId,a->usrId,kOutSliderAmId,kOutToneAmId,kOutPassAmId,kOutMuteAmId);
+  else
+    typeId = _cmUiAmCtlTypeId(p,pp,a->cId,a->usrId,kInSliderAmId,kInToneAmId,kInPassAmId,kInMuteAmId);
+
+  
+  // this control is not a slider or check btn so ignore it
+  if( typeId == cmInvalidId )
+    return rc;
+
+  
+  unsigned asInFl  = 0;
+  unsigned asCtlId = cmInvalidId;
+  unsigned asCh    = a->usrId - pp->a[typeId];
+  double   asValue = 0;
+
+  switch( typeId )
+  {
+    case kInSliderAmId: 
+      asInFl  = 1;
+      asCtlId = kSliderUiRtId;
+      asValue = a->fval;
+      break;
+
+    case kInToneAmId:   
+      asInFl  = 1;
+      asCtlId = kToneUiRtId;
+      asValue = a->ival;
+      break;
+
+    case kInPassAmId:   
+      asInFl  = 1;
+      asCtlId = kPassUiRtId;
+      asValue = a->ival;
+      break;
+
+    case kInMuteAmId:   
+      asInFl  = 1;;
+      asCtlId = kMuteUiRtId;
+      asValue = a->ival;
+      break;
+
+    case kOutSliderAmId: 
+      asCtlId = kSliderUiRtId;
+      asValue = a->fval;
+      break;
+
+    case kOutToneAmId:   
+      asCtlId = kToneUiRtId;
+      asValue = a->ival;
+      break;
+
+    case kOutPassAmId:   
+      asCtlId = kPassUiRtId;
+      asValue = a->ival;
+      break;
+
+    case kOutMuteAmId:   
+      asCtlId = kMuteUiRtId;
+      asValue = a->ival;
+      break;
+
+  }
+
+  unsigned asDevIdx = asInFl ? pp->iDevIdx : pp->oDevIdx;
+
+  r.hdr.rtSubIdx  = pp->rtSubIdx;
+  r.hdr.selId      = kUiMstrSelRtId;
+  r.devIdx    = asDevIdx;
+  r.chIdx     = asCh;
+  r.inFl      = asInFl;
+  r.ctlId     = asCtlId;
+  r.value     = asValue;
+
+  if( cmRtSysDeliverMsg(p->asH,  &r, sizeof(r), cmInvalidId ) != kOkRtRC )
+     rc  = cmErrMsg(&p->err,kSubSysFailUiRC,"Audio System master control UI message delivery to the audio system failed.");
+
+  return rc;
+}
+
+int _cmUiAmLinToDb( double v )
+{
+  if( v <= 0 )
+    return 0;
+
+  v = round(20.0*log10(v)+100.0);
+  return cmMin(kMtrMax,cmMax(kMtrMin,v));
+  
+} 
+
+cmUiRC_t cmUiRtSysMstrOnStatusEvent( cmUiRtMstrH_t h, const cmRtSysStatus_t* m, const double* iMeterArray, const double* oMeterArray )
+{
+  cmAm_t*      p        = _cmUiAmHandleToPtr(h);
+  cmAmPanel_t* pp       = p->list;
+
+  for(; pp!=NULL; pp=pp->link)
+    if(pp->rtSubIdx == m->hdr.rtSubIdx )
+      break;
+
+  if( pp == NULL )
+    return cmErrMsg(&p->err,kPanelNotFoundUiRC,"The panel associated with Audio system index %i could not be found.",m->hdr.rtSubIdx);
+
+  cmUiSetInt(p->uiH, p->appId, pp->updateId,  m->updateCnt  != pp->updateCnt );
+  cmUiSetInt(p->uiH, p->appId, pp->wakeupId,  m->wakeupCnt  != pp->wakeupCnt );
+  cmUiSetInt(p->uiH, p->appId, pp->msgCbId,   m->msgCbCnt   != pp->msgCbCnt );
+  cmUiSetInt(p->uiH, p->appId, pp->audioCbId, m->audioCbCnt != pp->audioCbCnt );
+
+  pp->updateCnt = m->updateCnt;
+  pp->wakeupCnt = m->wakeupCnt;
+  pp->msgCbCnt  = m->msgCbCnt;
+  pp->audioCbCnt= m->audioCbCnt;
+
+  unsigned i;
+
+  for(i=0; i<m->iMeterCnt; ++i)
+    cmUiSetInt(p->uiH, p->appId, pp->a[kInMeterAmId]+i,  _cmUiAmLinToDb(iMeterArray[i]) );
+
+  for(i=0; i<m->oMeterCnt; ++i)
+    cmUiSetInt(p->uiH, p->appId, pp->a[kOutMeterAmId]+i, _cmUiAmLinToDb(oMeterArray[i])  );
+
+  return kOkUiRC;
+}
+
+void cmUiRtSysMstrClearStatus( cmUiRtMstrH_t h )
+{
+  cmAm_t*  p        = _cmUiAmHandleToPtr(h);
+
+  cmAmPanel_t* pp = p->list;
+  for(; pp!=NULL; pp=pp->link)
+  {
+    cmUiSetInt(p->uiH, p->appId, pp->updateId,  0 );
+    cmUiSetInt(p->uiH, p->appId, pp->wakeupId,  0 );
+    cmUiSetInt(p->uiH, p->appId, pp->msgCbId,   0 );
+    cmUiSetInt(p->uiH, p->appId, pp->audioCbId, 0 );
+  }
+
+}

cmUiRtSysMstr.h

+#ifndef cmUiRtSysMstr_h
+#define cmUiRtSysMstr_h
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+  enum
+  {
+    kOkAmRC = cmOkRC,
+    kUiFailAmRC,
+    kPanelNotFoundAmRC
+  };
+
+  typedef cmHandle_t cmUiRtMstrH_t;
+  typedef cmRC_t     cmAmRC_t;
+
+  extern cmUiRtMstrH_t cmUiRtMstrNullHandle;
+
+  cmAmRC_t cmUiRtSysMstrAlloc( cmCtx_t* ctx, cmUiRtMstrH_t* hp, cmUiH_t uiH, cmRtSysH_t asH, unsigned appId );
+  cmAmRC_t cmUiRtSysMstrFree(  cmUiRtMstrH_t* hp );
+
+  bool     cmUiRtSysMstrIsValid( cmUiRtMstrH_t h );
+
+  cmAmRC_t cmUiRtSysMstrInitialize( cmUiRtMstrH_t h, const cmRtSysCtx_t* c, const cmChar_t* inDevLabel, const cmChar_t* outDevLabel );
+
+  // Receive UI events.
+  cmUiRC_t cmUiRtSysMstrOnUiEvent( cmUiRtMstrH_t h, const cmUiDriverArg_t* a );
+
+  // Receive UI status events
+  cmUiRC_t cmUiRtSysMstrOnStatusEvent( cmUiRtMstrH_t h, const cmRtSysStatus_t* m, const double* iMeterArray, const double* oMeterArray );
+
+  // Clear the status indicators.
+  void cmUiRtSysMstrClearStatus( cmUiRtMstrH_t h );
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif