MusicKit: MKOrchestra.h Source File

00001 /*
00002   $Id: MKOrchestra.h 3623 2009-09-25 11:14:32Z leighsmith $
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     See headerdoc description below for details.
00007  
00008     The MKOrchestra factory object manages all programs running on all the DSPs.
00009     Each instance of the MKOrchestra class corresponds to a single DSP. We call
00010     these instances "orchestra instances" or, simply, "orchestras". We call the
00011     collection of all orchestras the "MKOrchestra". Each orchestra instance is
00012     referred to by an integer 'orchIndex'. These indecies start at 0. 
00013     For the basic configuration, orchIndex is always 0.
00014 
00015     There are two levels of allocation: MKSynthPatch allocation and
00016     unit generator allocation. MKSynthPatches are higher-level entities,
00017     collections of MKUnitGenerators. Both levels may be used at the same time.
00018 
00019     CF: MKUnitGenerator.m, MKSynthPatch.m, MKSynthData.m and MKPatchTemplate.m.
00020 
00021   Original Author: David A. Jaffe
00022 
00023   Copyright 1988-1992, NeXT Inc.  All rights reserved.
00024   DSP Serial Port and subclass support and other 4.0 release extensions,
00025   Copyright 1993, CCRMA, Stanford Univ.
00026   Portions Copyright (c) 1999-2004 The MusicKit Project.
00027 */
00324 #ifndef __MK_Orchestra_H___
00325 #define __MK_Orchestra_H___
00326 
00327 #import <Foundation/Foundation.h>
00328 #import <SndKit/SndKit.h>
00329 #import "orch.h"
00330 #import "MKDeviceStatus.h"
00331 #import "MKSynthData.h"
00332 
00348 typedef enum _MKOrchSharedType {
00350     MK_noOrchSharedType = 0, 
00354     MK_oscTable = 1, 
00357     MK_waveshapingTable = 2,
00361     MK_excitationTable = 3
00362 } MKOrchSharedType;
00363 
00364 typedef enum _MKEMemType {
00365     MK_orchEmemNonOverlaid = 0, 
00366     MK_orchEmemOverlaidXYP = 1, 
00367     MK_orchEmemOverlaidPX = 2
00368 } MKEMemType;
00369 
00375 typedef enum {
00377     MK_UNTIMED = 0,
00379     MK_TIMED = 1,
00381     MK_SOFTTIMED = 2
00382 } MKOrchestraTiming;
00383 
00406 extern double MKGetPreemptDuration(void);
00407 
00426 extern void MKSetPreemptDuration(double seconds);
00427  
00428 @interface MKOrchestra : SndStreamClient
00429 {
00431     double computeTime; 
00433     double samplingRate;
00435     NSMutableArray *unitGeneratorStack;      
00437     NSString *outputSoundfile;
00438     id outputSoundDelegate;
00440     NSString *inputSoundfile;
00442     NSString *outputCommandsFile;
00443     id xZero;         /* Special pre-allocated x patch-point that always holds
00444                          0 and to which nobody ever writes, by convention.  */
00445     id yZero;         /* Special pre-allocated y patch-point that always holds
00446                          0 and to which nobody ever writes, by convention.  */
00447     id xSink;      /* Special pre-allocated x patch-point that nobody ever
00448                       reads, by convention. */
00449     id ySink;      /* Special pre-allocated y patch-point that nobody ever
00450                       reads, by convention. */
00451     id xModulusSink;/* Special pre-allocated x patch-point that nobody ever
00452                       reads, by convention. */
00453     id yModulusSink;/* Special pre-allocated y patch-point that nobody ever
00454                       reads, by convention. */
00455     id sineROM;    /* Special read-only MKSynthData object used to represent
00456                       the SineROM. */
00457     id muLawROM;   /* Special read-only MKSynthData object used to represent
00458                       the Mu-law ROM. */
00460     MKDeviceStatus deviceStatus;
00462     unsigned short orchIndex;
00463     char isTimed;    /* Determines whether DSP commands go out timed or not. */
00464     BOOL useDSP;     /* YES if running on an actual DSP (Default is YES) */
00465     BOOL hostSoundOut;   /* YES if sound is going to the DACs. */
00467     BOOL soundIn;
00468     BOOL isLoopOffChip; /* YES if loop has overflowed off chip. */
00469     BOOL fastResponse;  /* YES if response latency should be minimized */
00471     double localDeltaT;
00472     short onChipPatchPoints;
00473     int release;
00474     char version;
00475     NSString *monitorFileName;   /* NULL uses default monitor */
00476     DSPLoadSpec *mkSys;
00477     NSString *lastAllocFailStr;
00478     id _sysUG;
00479     int _looper;
00480     void *_availDataMem;
00481     void  *_eMemList;
00482     NSMutableDictionary *_sharedSet;
00483     DSPAddress _piLoop;
00484     DSPAddress _xArg;
00485     DSPAddress _yArg;
00486     DSPAddress _lArg;
00487     DSPAddress _maxXArg;
00488     DSPAddress _maxYArg;
00489     DSPAddress *_xPatch;
00490     DSPAddress *_yPatch;
00491     unsigned long _xPatchAllocBits;
00492     unsigned long _yPatchAllocBits;
00493     double _headroom;
00494     double _effectiveSamplePeriod;
00495     id _orchloopClass;
00496     id _previousLosingTemplate;
00497     DSPFix48 _previousTimeStamp;
00498     int _parenCount;
00499     int _bottomOfMemory;
00500     unsigned int _bottomOfExternalMemory;
00501     int _topOfExternalMemory;
00502     int _onChipPPPartitionSize;
00503     int _numXArgs;
00504     int _numYArgs;
00505     float _xArgPercentage;
00506     float _yArgPercentage;
00507     void *_simFP;
00508     MKEMemType _overlaidEMem;
00509     BOOL _nextCompatibleSerialPort;
00510     NSString *_driverParMonitorFileName;
00511     // added in by LMS, thawing the ancient ivar freeze
00512     double previousTime;
00513     NSHashTable *sharedGarbage;
00514     char *simulatorFile;
00515     id readDataUG;
00516     id xReadData;
00517     id yReadData;
00518     double timeOffset;
00519     double synchTimeRatio;
00520     NSTimer *timedEntry;
00521     BOOL synchToConductor;
00522 }
00523 
00539 - (MKDeviceStatus) deviceStatus;
00540 
00561 - (void) setHeadroom: (double) headroom;
00562 
00569 + (void) setHeadroom: (double) headroom;
00570 
00577 - (double) headroom;
00578 
00579 // TODO investigate if needed.
00580 // TODO candidate to return void
00588 - beginAtomicSection;
00589 
00590 // TODO investigate if needed.
00591 // TODO candidate to return void
00598 - endAtomicSection;
00599 
00608 + orchestra; 
00609 
00624 + orchestraOnDSP: (unsigned short) index; 
00625 
00634 + (NSArray *) orchestrasOnAllDSPs;
00635 
00645 + flushTimedMessages; 
00646 
00653 + (unsigned short) DSPCount;
00654 
00663 + (MKOrchestra *) nthOrchestra: (unsigned short) index; 
00664 
00668 - init;
00669 
00677 - initOnDSP: (unsigned short) dspIndex;
00678 
00690 + open; 
00691 
00700 + run; 
00701 
00711 + stop; 
00712 
00721 + close; 
00722 
00730 + abort;
00731 
00732 // TODO document
00733 // TODO investigate if needed.
00734 - (void) synchTime: (NSTimer *) timer;
00735 
00743 - (int) tickSize; 
00744 
00751 - (double) samplingRate; 
00752 
00753 // TODO candidate to return void
00765 + (void) setSamplingRate: (double) newSRate; 
00766 
00767 // TODO candidate to return BOOL
00778 - setSamplingRate: (double) newSRate; 
00779 
00780 // TODO candidate to return void
00794 + setTimed: (MKOrchestraTiming) areOrchsTimed; 
00795 
00796 // TODO candidate to return void
00814 - setTimed: (MKOrchestraTiming) isOrchTimed; 
00815 
00820 - (MKOrchestraTiming) isTimed; 
00821 
00822 // TODO candidate to return void
00849 - setSynchToConductor: (BOOL) yesOrNo;
00850 
00864 - setFastResponse: (char) yesOrNo;
00865 
00875 +setFastResponse:(char)yesOrNo;
00876 
00884 - (char) fastResponse;
00885 
00886 + setAbortNotification:aDelegate;
00887 
00897 - setLocalDeltaT: (double) val;
00898 
00903 - (double) localDeltaT;
00904 
00911 + setLocalDeltaT: (double) val;
00912 
00929 - setHostSoundOut: (BOOL) yesOrNo;
00930 
00931 - (BOOL) hostSoundOut;
00932 
00933 - setSoundOut: (BOOL) yesOrNo;
00934 
00940 - setSoundIn: (BOOL) yesOrNo;
00941 
00946 - (BOOL) soundIn;
00947 
00953 - (void) setDebug: (BOOL) yesOrNo;
00954 
00974 - setOutputSoundfile: (NSString *) fileName;
00975 
00980 - (NSString *) outputSoundfile;
00981 
00982 -setOutputSoundDelegate:aDelegate;
00983 -outputSoundDelegate;
00984 
00997 - setOutputCommandsFile: (NSString *) fileName;
00998 
01003 - (NSString *) outputCommandsFile;
01004 
01014 + allocUnitGenerator: (id) classObj; // (Class) classObj 
01015 
01027 + allocSynthData: (MKOrchMemSegment) segment length: (unsigned) size; 
01028 
01036 + allocPatchpoint: (MKOrchMemSegment) segment; 
01037 
01045 + allocSynthPatch: (id) aSynthPatchClass;  // (Class) aSynthPatchClass 
01046 
01056 + allocSynthPatch: (id) aSynthPatchClass patchTemplate: (id) p;
01057 
01068 + dealloc: (id) aSynthResource;
01069 
01083 - flushTimedMessages;
01084 
01085 + (int) sharedTypeForName: (char *) str;
01086 + (char *) nameForSharedType: (int) typeInt;
01087 
01103 - installSharedObject: (id) aSynthObj for: (id) aKeyObj;
01104 
01128 - installSharedObject: (id) aSynthObj for: (id) aKeyObj type: (MKOrchSharedType) aType;
01129 
01145 - installSharedSynthDataWithSegment: (id) aSynthDataObj for: (id) aKeyObj;
01146 
01164 - installSharedSynthDataWithSegment: (id) aSynthDataObj 
01165                                 for: (id) aKeyObj 
01166                                type: (MKOrchSharedType) aType;
01167 
01168 - installSharedSynthDataWithSegmentAndLength: (MKSynthData *) aSynthDataObj
01169                                          for: (id) aKeyObj;
01170 
01186 - installSharedSynthDataWithSegmentAndLength: (MKSynthData *) aSynthDataObj
01187                                          for: (id) aKeyObj
01188                                         type: (MKOrchSharedType) aType;
01189 
01201 - sharedObjectFor: (id) aKeyObj;
01202 
01216 - sharedObjectFor: (id) aKeyObj type: (MKOrchSharedType) aType;
01217 
01232 - sharedSynthDataFor: (id) aKeyObj segment: (MKOrchMemSegment) whichSegment;
01233 
01249 - sharedSynthDataFor: (id) aKeyObj 
01250              segment: (MKOrchMemSegment) whichSegment
01251                 type: (MKOrchSharedType) aType; 
01252 
01268 - sharedSynthDataFor: (id) aKeyObj
01269              segment: (MKOrchMemSegment) whichSegment 
01270               length: (int) length;
01271 
01289 - sharedSynthDataFor: (id) aKeyObj
01290              segment: (MKOrchMemSegment) whichSegment
01291               length: (int) length
01292                 type: (MKOrchSharedType) aType; 
01293 
01301 - sineROM; 
01302 
01310 - muLawROM; 
01311 
01322 - segmentZero: (MKOrchMemSegment) segment; 
01323 
01335 - segmentSink: (MKOrchMemSegment) segment; 
01336 
01348 - segmentSinkModulus: (MKOrchMemSegment) segment; 
01349 
01363 - open; 
01364 
01375 - run; 
01376 
01386 - stop; 
01387 
01396 - close; 
01397 
01406 - abort;
01407 
01408 - useDSP: (BOOL) useIt; 
01409 - (BOOL) isDSPUsed; 
01410 
01420 - trace: (int) typeOfInfo msg: (NSString *) fmt,...; 
01421 
01429 - (NSString *) segmentName: (int) whichSegment; 
01430 
01437 - (unsigned short) orchestraIndex; 
01438 
01444 - (double) computeTime; 
01445 
01452 - allocSynthPatch: (id) aSynthPatchClass; 
01453 
01466 - allocSynthPatch: (id) aSynthPatchClass patchTemplate: (id) p; 
01467 
01474 - allocUnitGenerator: (id) aClass; 
01475 
01484 - allocUnitGenerator: (id) aClass before: (id) aUnitGeneratorInstance; 
01485 
01494 - allocUnitGenerator: (id) aClass after: (id) aUnitGeneratorInstance; 
01495 
01506 - allocUnitGenerator: (id) aClass between: (id) aUnitGeneratorInstance : (id) anotherUnitGeneratorInstance;
01507 
01508 - (NSString *) lastAllocationFailureString;
01509 
01521 - allocSynthData: (MKOrchMemSegment) segment length: (unsigned) size; 
01522 
01531 - allocPatchpoint: (MKOrchMemSegment) segment; 
01532 
01543 - dealloc: (id) aSynthResource;
01544 
01552 - (BOOL) isRealTime;
01553 
01554 
01567 - (BOOL) supportsSamplingRate: (double) rate;
01568 
01569 - (int) hardwareSupportedSamplingRates: (double **) arr;
01570 
01584 - (double) defaultSamplingRate;
01585 
01595 - (BOOL) prefersAlternativeSamplingRate;
01596 
01597 + setAbortNotification: aDelegate;
01598 
01608 - setDefaultSoundOut;
01609 
01617 - getMonitorVersion: (char *) versionP release: (int *) releaseP;
01618 
01622 #define MK_nextCompatibleDSPPort 1
01623 
01626 #define MK_hostSoundOut (1<<1)
01627 
01630 #define MK_serialSoundOut (1<<2)
01631 
01634 #define MK_soundIn (1<<3)
01635 
01638 #define MK_soundfileOut (1<<4)
01639 
01654 - (unsigned) capabilities;
01655 
01666 - (int) outputChannelCount;
01667 
01679 - (BOOL) upSamplingOutput;
01680 
01688 - setUpDSP;
01689 
01697 - (BOOL) startSoundWhenOpening;
01698 
01709 + registerOrchestraSubclass: (id) classObject forOrchIndex: (int) index;
01710 
01711 - segmentInputSoundfile: (MKOrchMemSegment) segment;
01712 - setInputSoundfile: (NSString *) file;
01713 - (NSString *) inputSoundfile;
01714 - pauseInputSoundfile;
01715 - resumeInputSoundfile;
01716 
01724 + (NSArray *) getDriverNames;
01725 
01732 - (NSString *) driverName;
01733 
01739 - (int) driverUnit;
01740 
01741 - (int) driverSubUnit;
01742 
01753 + (NSString *) driverParameter: (NSString *) parameterName forOrchIndex: (unsigned short) index;
01754 
01764 - (NSString *) driverParameter: (NSString *) parameterName;
01765 
01766 - awaitEndOfTime: (double) endOfTime timeStamp: (DSPTimeStamp *) aTimeStampP;
01767 
01768 - setSimulatorFile: (char *) filename;
01769 - (char *) simulatorFile;
01770 
01771 - sharedObjectFor: aKeyObj segment: (MKOrchMemSegment) whichSegment length: (int) length;
01772 - sharedObjectFor: aKeyObj segment: (MKOrchMemSegment) whichSegment;
01773 
01774 @end
01775 
01776 @interface OrchestraDelegate : NSObject
01777 
01778 -orchestra: (id) sender didRecordData: (short *) data size: (unsigned int) dataCount;
01779 
01780 @end
01781 
01782 #endif