Copyright (C) Kevin Larke 2009-2020

This file is part of libcm.

libcm is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

libcm is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See the GNU General Public License distributed with the libcm package or look here: .


cmDspSys : Host application interface to the 'snap' data flow system.


extern cmDspSysH_t cmDspNullHandle;


// Print labels of the form 'label'-xxx. Where xxx is an integer.
// The total length of the label must be &lt=127 or it will be truncated.
// The returned string is kept in static memory and therefore will be
// rewritten by the next call to this function.  This makes the function
// inherently useless if called by multiple threads.
const cmChar_t* cmDspSysPrintLabel( const cmChar_t* label, unsigned i );
const cmChar_t* cmDspSysPrintLabel2( const cmChar_t* label, unsigned i );



// Control Functions //
cmDspRC_t cmDspSysInitialize( cmCtx_t* ctx, cmDspSysH_t* hp, cmUdpNetH_t netH, cmSeH_t serialPortH ); cmDspRC_t cmDspSysFinalize( cmDspSysH_t* hp ); bool cmDspSysIsValid( cmDspSysH_t h ); cmDspRC_t cmDspSysLastRC( cmDspSysH_t h ); unsigned cmDspSysPgmCount( cmDspSysH_t h ); const cmChar_t* cmDspPgmLabel( cmDspSysH_t h, unsigned pgmIdx ); // Load a DSP program. cmDspRC_t cmDspSysLoad( cmDspSysH_t h, cmAudioSysCtx_t* asCtx, unsigned pgmIdx ); // Unload the previously loaded DSP program cmDspRC_t cmDspSysUnload( cmDspSysH_t h ); // Call 'reset' on each of the DSP processer instances in the current program. cmDspRC_t cmDspSysReset( cmDspSysH_t h ); // Called by the audioSystem to send messages to the DSP system during runtime. cmDspRC_t cmDspSysRcvMsg( cmDspSysH_t h, cmAudioSysCtx_t* asCtx, const void* msgPtr, unsigned msgByteCnt, unsigned srcNetNodeId ); enum { kSyncPreDspId, kSyncPendingDspId, kSyncSuccessDspId, kSyncFailDspId }; unsigned cmDspSysSyncState( cmDspSysH_t h ); // Print the loaded program (instances and connections) to a JSON file. cmDspRC_t cmDspSysPrintPgm( cmDspSysH_t h, const cmChar_t* outFn );
// Preset function: //
// A 'preset group' identifies a collection of 'preset's. The group id allows // a particular preset instance to be restored to the same place from which it was formed. unsigned cmDspSysPresetGroupCount( cmDspSysH_t h ); unsigned cmDspSysPresetGroupSymId( cmDspSysH_t h, unsigned groupIdx ); const cmChar_t* cmDspSysPresetGroupLabel( cmDspSysH_t h, unsigned groupIdx ); cmDspRC_t cmDspSysPresetGroupJsonList( cmDspSysH_t h, cmJsonH_t* jsHPtr ); // A 'preset' is a collection of stored DSP instances and their variables. A preset belongs // to a group. A given group may have multiple presets. Each preset represents a saved // instance/var state. unsigned cmDspSysPresetPresetCount( cmDspSysH_t h, unsigned groupIdx ); unsigned cmDspSysPresetPresetSymId( cmDspSysH_t h, unsigned groupIdx, unsigned presetIdx ); const cmChar_t* cmDspSysPresetPresetLabel( cmDspSysH_t h, unsigned groupIdx, unsigned presetIdx ); cmDspRC_t cmDspSysPresetPresetJsonList(cmDspSysH_t h, unsigned groupSymId, cmJsonH_t* jsHPtr ); // This function returns a preset group id from a string label. unsigned cmDspSysPresetRegisterGroup( cmDspSysH_t h, const cmChar_t* groupLabel ); // Create a preset named 'presetLabel' in the group named 'groupLabel'. If the group does not // exist it will be created. The creation will fail if the 'presetLabel' already exists. // This function calls the 'storeFunc' on every DSP instance belonging to the group // identified by 'groupLabel'. cmDspRC_t cmDspSysPresetCreate( cmDspSysH_t h, const cmChar_t* groupLabel, const cmChar_t* presetLabel ); // Apply the stored preset named by 'groupLabel' and 'presetLabel'. cmDspRC_t cmDspSysPresetRecall( cmDspSysH_t h, const cmChar_t* groupLabel, const cmChar_t* presetLabel ); // Helper functions used by DSP instances to read and write preset variable values. These functions // are called from inside the user defined DSP instance 'storeFunc'. cmDspRC_t cmDspSysPresetWriteValue( cmDspSysH_t h, unsigned varSymId, const cmDspValue_t* valPtr ); cmDspRC_t cmDspSysPresetReadValue( cmDspSysH_t h, unsigned varSymId, cmDspValue_t* valPtr );
// Generic constructors //
// Allocate single DSP instances. cmDspInst_t* cmDspSysAllocInstSV( cmDspSysH_t h, const cmChar_t* classLabelStr, unsigned presetGroupSymId, const cmChar_t* instLabelStr, unsigned va_cnt, va_list vl ); cmDspInst_t* cmDspSysAllocInstS( cmDspSysH_t h, const cmChar_t* classLabelStr, unsigned presetGroupSymId, const cmChar_t* instLabelStr, unsigned va_cnt, ... ); cmDspInst_t* cmDspSysAllocInst( cmDspSysH_t h, const cmChar_t* classLabelStr, const cmChar_t* instLabelStr, unsigned va_cnt, ... ); typedef const cmChar_t* (*cmDspSysLabelFunc_t)( cmDspSysH_t h, unsigned i ); // Allocate arrays of DSP instances. The memory used by the array is allocated from // the cmDspSys linked heap and is therefore automatically garbage collected. cmDspInst_t** cmDspSysAllocInstArraySV( cmDspSysH_t h, unsigned cnt, unsigned presetGroupSymId, const cmChar_t* classLabelStr, const cmChar_t* instLabelStr, cmDspSysLabelFunc_t labelFunc, unsigned va_cnt, va_list vl ); cmDspInst_t** cmDspSysAllocInstArrayS( cmDspSysH_t h, unsigned cnt, unsigned presetGroupSymId, const cmChar_t* classLabelStr, const cmChar_t* instLabelStr, cmDspSysLabelFunc_t labelFunc, unsigned va_cnt, ... ); cmDspInst_t** cmDspSysAllocInstArray( cmDspSysH_t h, unsigned cnt, const cmChar_t* classLabelStr, const cmChar_t* instLabelStr, cmDspSysLabelFunc_t labelFunc, unsigned va_cnt, ... ); cmDspRC_t cmDspSysNewColumn( cmDspSysH_t h, unsigned colW ); cmDspRC_t cmDspSysInsertHorzBorder( cmDspSysH_t h ); cmDspRC_t cmDspSysNewPage( cmDspSysH_t h, const cmChar_t* title );
// Connection Functions. //
cmDspRC_t cmDspSysConnectAudio( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarLbl, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarLbl ); cmDspRC_t cmDspSysConnectAudioN11N( cmDspSysH_t h, cmDspInst_t* srcInstArray[], const cmChar_t* srcVarLabel, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarPrefixStr, unsigned n ); cmDspRC_t cmDspSysConnectAudio1NN1( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, cmDspInst_t* dstInstArray[], const cmChar_t* dstVarLabel, unsigned n ); cmDspRC_t cmDspSysConnectAudio1N1N( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarPrefixLabel, unsigned n ); cmDspRC_t cmDspSysConnectAudioN1N1( cmDspSysH_t h, cmDspInst_t* srcInstArray[], const cmChar_t* srcVarLabel, cmDspInst_t* dstInstArray[], const cmChar_t* dstVarLabel, unsigned n ); cmDspRC_t cmDspSysConnectAudio11N1( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarLabel, cmDspInst_t* dstInstPArray[],const cmChar_t* dstVarPrefixStr, unsigned n ); cmDspRC_t cmDspSysConnectAudio111N( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarLabel, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarLabel, unsigned n ); // Connect srcInstArray[ map[i] ] to dstInst.in[i] - map[dstCnt] therefore contains dstCnt elements cmDspRC_t cmDspSysConnectAudioN11NM( cmDspSysH_t h, cmDspInst_t* srcInstArray[], const cmChar_t* srcVarLabel, unsigned srcCnt, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarPrefixStr, unsigned dstCnt, const unsigned* map ); cmDspRC_t cmDspSysInstallCb( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarLabel, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarLabel, void* dstCbDataPtr); cmDspRC_t cmDspSysInstallCbN11N( cmDspSysH_t h, cmDspInst_t* srcInstArray[], const cmChar_t* srcVarLabel, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarPrefixStr, unsigned n ); cmDspRC_t cmDspSysInstallCb1NN1( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, cmDspInst_t* dstInstArray[], const cmChar_t* dstVarLabel, unsigned n ); cmDspRC_t cmDspSysInstallCb1N1N( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarPrefixLabel, unsigned n ); cmDspRC_t cmDspSysInstallCbN1N1( cmDspSysH_t h, cmDspInst_t* srcInstArray[], const cmChar_t* srcVarLabel, cmDspInst_t* dstInstArray[], const cmChar_t* dstVarLabel, unsigned n ); cmDspRC_t cmDspSysInstallCb11N1( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarLabel, cmDspInst_t* dstInstArray[], const cmChar_t* dstVarLabel, unsigned n ); cmDspRC_t cmDspSysInstallCb111N( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarLabel, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarPrefixLabel, unsigned n ); cmDspRC_t cmDspSysInstallCbN111( cmDspSysH_t h, cmDspInst_t* srcInstArray[], const cmChar_t* srcVarLabel, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarLabel, unsigned n ); cmDspRC_t cmDspSysInstallCb1N11( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarLabel, unsigned n ); cmDspRC_t cmDspSysInstallCb1N1NM( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, unsigned srcCnt, cmDspInst_t* dstInstPtr, const cmChar_t* dstVarPrefixLabel, unsigned dstCnt, const unsigned* map ); cmDspRC_t cmDspSysInstallCb1NN1M( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, unsigned srcCnt, cmDspInst_t* dstInstArray[], const cmChar_t* dstVarLabel, unsigned dstCnt, const unsigned* map ); cmDspRC_t cmDspSysInstallCb1NN1M2(cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, unsigned srcCnt, const unsigned* map, cmDspInst_t* dstInstArray[], const cmChar_t* dstVarLabel, unsigned dstCnt ); cmDspRC_t cmDspSysInstallNetCb( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarLabel, const cmChar_t* dstNetNodeLabel, const cmChar_t* dstInstLabel, const cmChar_t* dstVarLabel ); cmDspRC_t cmDspSysInstallNetCb1N1N( cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, const cmChar_t* dstNetNodeLabel, const cmChar_t* dstInstLabel, const cmChar_t* dstVarPrefixStr, unsigned dstOffs, unsigned n ); cmDspRC_t cmDspSysInstallNetCb1N1NM(cmDspSysH_t h, cmDspInst_t* srcInstPtr, const cmChar_t* srcVarPrefixStr, unsigned srcCnt, const cmChar_t* dstNetNodeLabel, const cmChar_t* dstInstLabel, const cmChar_t* dstVarPrefixStr, unsigned dstCnt, const unsigned* map );
// cmDspSysH_t Accessor Functions //
double cmDspSysSampleRate( cmDspSysH_t h ); cmJsonH_t cmDspSysPgmRsrcHandle( cmDspSysH_t h ); cmSymTblH_t cmDspSysSymbolTable( cmDspSysH_t h ); cmSeH_t cmDspSysSerialPort( cmDspSysH_t h ); unsigned cmDspSysRegisterStaticSymbol( cmDspSysH_t h, const cmChar_t* symLabel ); unsigned cmDspSysRegisterSymbol( cmDspSysH_t h, const cmChar_t* symLabel ); cmCtx_t* cmDspSysPgmCtx( cmDspSysH_t h ); cmLHeapH_t cmDspSysLHeap( cmDspSysH_t h ); unsigned cmDspSysNetNodeId( cmDspSysH_t h ); const cmChar_t* cmDspSysNetNodeLabel( cmDspSysH_t h ); const cmChar_t* cmDspSysNetNodeIdToLabel( cmDspSysH_t h, unsigned netNodeId ); unsigned cmDspSysNetNodeLabelToId( cmDspSysH_t h, const cmChar_t* netNodeLabel );
// Attribute Symbol assignment and value broadcasing //
// Each DSP instance can be tagged with an arbitrary number of 'attribute' symbols. // The primary use of an attribute symbol is to identify targets of // messages sent via the cmDspSysBroadcastValue() call. // This function declares an active attribute symbol which will be assigned to all DSP // instances which are created after the function is called and before // cmDspSysRemoveInstAttrSymbol(). Multiple attribute symbols may be made active // in this way - in which case all active attribute symbols will be assigned to any // DSP instances created during their life time. // Return symId or cmInvalidId on failure. unsigned cmDspSysRegisterInstAttrSymbol( cmDspSysH_t h, unsigned symId ); unsigned cmDspSysRegisterInstAttrSymbolStr( cmDspSysH_t h, const cmChar_t* symLabel ); // Assign a instance attribute symbol to a DSP instance. cmDspRC_t cmDspSysAssignInstAttrSymbol( cmDspSysH_t h, cmDspInst_t* inst, unsigned symId ); // Return cmInvalidId on error otherwise returns the symbol id associated with symLabel. unsigned cmDspSysAssignInstAttrSymbolStr( cmDspSysH_t h, cmDspInst_t* inst, const cmChar_t* symLabel ); // Remove a previously registered attribute symbol. cmDspRC_t cmDspSysRemoveInstAttrSymbol( cmDspSysH_t h, unsigned symId ); cmDspRC_t cmDspSysRemoveInstAttrSymbolStr( cmDspSysH_t h, const cmChar_t* symLabel ); // Send a value to every DSP instance tagged with the attribute symbol // 'instAttrSymId'. // Set instAttrSymId to cmInvalidId to send to all instances cmDspRC_t cmDspSysBroadcastValue( cmDspSysH_t h, unsigned instAttrSymId, const cmDspValue_t* valuePtr );
// Specialized Constructors: //
// align: kRightAlignDuiId, kLeftAlignDuiId, kCenterAlignDuiId cmDspInst_t* cmDspSysAllocLabel( cmDspSysH_t h, const cmChar_t* label, unsigned alignId ); cmDspInst_t* cmDspSysAllocScalar( cmDspSysH_t h, const cmChar_t* label, cmReal_t min, cmReal_t max, cmReal_t step, cmReal_t val ); cmDspInst_t* cmDspSysAllocScalarP( cmDspSysH_t h, unsigned presetGroupSymId, const cmChar_t* prefixLabel, const cmChar_t* label, cmReal_t min, cmReal_t max, cmReal_t step, cmReal_t val ); cmDspInst_t* cmDspSysAllocScalarRsrc( cmDspSysH_t h, const cmChar_t* label, cmReal_t min, cmReal_t max, cmReal_t step, const cmChar_t* rsrcPath ); cmDspInst_t** cmDspSysAllocScalarA( cmDspSysH_t h, unsigned cnt, unsigned presetGroupSymId, const cmChar_t* prefixLabel, const cmChar_t* label, cmReal_t min, cmReal_t max, cmReal_t step, cmReal_t val ); cmDspInst_t* cmDspSysAllocButton( cmDspSysH_t h, const cmChar_t* label, cmReal_t val ); cmDspInst_t* cmDspSysAllocButtonP( cmDspSysH_t h, const cmChar_t* prefixLabel, const cmChar_t* label, cmReal_t val ); cmDspInst_t* cmDspSysAllocButtonRsrc( cmDspSysH_t h, const cmChar_t* label, const cmChar_t* rsrcPath ); cmDspInst_t* cmDspSysAllocCheck( cmDspSysH_t h, const cmChar_t* label, cmReal_t val ); cmDspInst_t* cmDspSysAllocCheckP( cmDspSysH_t h, unsigned presetGroupSymId, const cmChar_t* prefixLabel, const cmChar_t* label, cmReal_t val ); cmDspInst_t* cmDspSysAllocCheckRsrc( cmDspSysH_t h, const cmChar_t* label, const cmChar_t* rsrcPath ); // If 'fn' is NULL then the DSP rsrc tree is used to locate the resource. // The resource named by 'rsrcLabel' may be any place in the resource tree. cmDspInst_t* cmDspSysAllocMsgList( cmDspSysH_t h, const cmChar_t* fn, const cmChar_t* rsrcLabel, unsigned initSelIdx ); cmDspInst_t* cmDspSysAllocMsgListP( cmDspSysH_t h, unsigned presetGroupSymId, const cmChar_t* preLabel, const cmChar_t* label, const cmChar_t* fn, const cmChar_t* rsrcLabel, unsigned initSelIdx ); cmDspInst_t* cmDspSysAllocAudioIn( cmDspSysH_t h, unsigned chIdx, cmReal_t gain ); // Set chMapRsrcLabel to NULL to use the rsrc named 'audioInMap'. // *retChCntPtr is set to the count of audio channels created (and the count of channels in the map). cmDspInst_t** cmDspSysAllocAudioInAR( cmDspSysH_t h, const cmChar_t* chMapRsrcLabel, cmReal_t gain, unsigned* retChCntPtr ); cmDspInst_t* cmDspSysAllocAudioOut( cmDspSysH_t h, unsigned chIdx, cmReal_t gain ); // Set chMapRsrcLabel to NULL to use the rsrc named 'audioOutMap'. // *retChCntPtr is set to the count of audio channels created (and the count of channels in the map). cmDspInst_t** cmDspSysAllocAudioOutAR( cmDspSysH_t h, const cmChar_t* chMapRsrcLabel, cmReal_t gain, unsigned* retChCntPtr );
// Read resource values from the program resource file. //
cmDspRC_t cmDspRsrcBoolV( cmDspSysH_t h, bool* vp, va_list vl ); cmDspRC_t cmDspRsrcIntV( cmDspSysH_t h, int* vp, va_list vl ); cmDspRC_t cmDspRsrcUIntV( cmDspSysH_t h, unsigned* vp, va_list vl ); cmDspRC_t cmDspRsrcDblV( cmDspSysH_t h, double* vp, va_list vl ); cmDspRC_t cmDspRsrcRealV( cmDspSysH_t h, cmReal_t* vp, va_list vl ); cmDspRC_t cmDspRsrcStringV( cmDspSysH_t h, const cmChar_t** vp, va_list vl ); cmDspRC_t cmDspRsrcArrayCountV( cmDspSysH_t h, unsigned* np, va_list vl ); cmDspRC_t cmDspRsrcBoolArrayV( cmDspSysH_t h, unsigned* np, bool** vpp, va_list vl ); cmDspRC_t cmDspRsrcIntArrayV( cmDspSysH_t h, unsigned* np, int** vpp, va_list vl ); cmDspRC_t cmDspRsrcUIntArrayV( cmDspSysH_t h, unsigned* np, unsigned** vpp, va_list vl ); cmDspRC_t cmDspRsrcDblArrayV( cmDspSysH_t h, unsigned* np, double** vpp, va_list vl ); cmDspRC_t cmDspRsrcRealArrayV( cmDspSysH_t h, unsigned* np, cmReal_t** vpp, va_list vl ); cmDspRC_t cmDspRsrcStringArrayV(cmDspSysH_t h, unsigned* np, const cmChar_t*** vpp, va_list vl ); cmDspRC_t cmDspRsrcInt( cmDspSysH_t h, int* vp, ... ); cmDspRC_t cmDspRsrcBool( cmDspSysH_t h, bool* vp, ... ); cmDspRC_t cmDspRsrcUInt( cmDspSysH_t h, unsigned* vp, ... ); cmDspRC_t cmDspRsrcDbl( cmDspSysH_t h, double* vp, ... ); cmDspRC_t cmDspRsrcReal( cmDspSysH_t h, cmReal_t* vp, ... ); cmDspRC_t cmDspRsrcString( cmDspSysH_t h, const cmChar_t** vp, ... ); cmDspRC_t cmDspRsrcArrayCount( cmDspSysH_t h, unsigned* np, ... ); cmDspRC_t cmDspRsrcBoolArray( cmDspSysH_t h, unsigned* np, bool** vpp, ... ); cmDspRC_t cmDspRsrcIntArray( cmDspSysH_t h, unsigned* np, int** vpp, ... ); cmDspRC_t cmDspRsrcUIntArray( cmDspSysH_t h, unsigned* np, unsigned** vpp, ... ); cmDspRC_t cmDspRsrcDblArray( cmDspSysH_t h, unsigned* np, double** vpp, ... ); cmDspRC_t cmDspRsrcRealArray( cmDspSysH_t h, unsigned* np, cmReal_t** vpp, ... ); cmDspRC_t cmDspRsrcStringArray( cmDspSysH_t h, unsigned* np, const cmChar_t*** vpp, ... ); cmDspRC_t cmDspRsrcWriteStringV( cmDspSysH_t h, const cmChar_t* v, va_list vl ); cmDspRC_t cmDspRsrcWriteString( cmDspSysH_t h, const cmChar_t* v, ... );