MusicKit: MKConductor.h Source File

00001 /*
00002   $Id: MKConductor.h 3623 2009-09-25 11:14:32Z leighsmith $
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     This is the header for the MusicKit scheduler. See documentation below for details.
00007 
00008   Original Author: David Jaffe
00009 
00010   Copyright (c) 1988-1992, NeXT Computer, Inc.
00011   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00012   Portions Copyright (c) 1994 Stanford University.
00013   Portions Copyright (c) 1999-2005 The MusicKit Project.
00014 */
00015 
00016 #import <Foundation/Foundation.h>
00017 
00018 @class MKMidi;
00019 @class MKConductor;
00020 
00267 #ifndef __MK_Conductor_H___
00268 #define __MK_Conductor_H___
00269 
00270 #import <Foundation/NSObject.h>
00271 #import <Foundation/NSArray.h>
00272 #import <Foundation/NSThread.h>
00273 #import <SndKit/SndKit.h>
00274 
00275 // Enforce C name mangling to allow linking MusicKit functions to C++ code
00276 #ifdef __cplusplus
00277 extern "C" {
00278 #endif
00279 
00280  /* The MKConductor message structure.  All fields are private and
00281   * shouldn't be altered directly from an application.
00282   * LMS: should become an object named MKConductorMessage
00283   */
00288 typedef struct _MKMsgStruct { 
00289     double _timeOfMsg;     
00290     SEL _aSelector;       
00291     id _toObject;              
00292     int _argCount;             
00293     BOOL _retainArg1;
00294     BOOL _retainArg2;
00295     id _arg1;
00296     id _arg2;
00297     struct _MKMsgStruct *_next; 
00298     IMP _methodImp;        
00299     id *_otherArgs;
00300     BOOL _conductorFrees;  
00301     BOOL _onQueue;      
00302     struct _MKMsgStruct *_prev;
00303     MKConductor *_conductor;
00304 } MKMsgStruct;
00305 
00307 #define MK_ENDOFTIME (6000000000.0) /* A long time, but not as long as MK_FOREVER */
00308 
00322 extern double MKGetTime(void);
00323 
00339 extern double MKGetDeltaT(void);
00340 
00367 extern void MKSetDeltaT(double val);
00368 
00378 extern double MKGetDeltaTTime(void);
00379 
00385 #define MK_DELTAT_DEVICE_LAG 0
00386 
00387 #define MK_DELTAT_SCHEDULER_ADVANCE 1
00388  
00398 extern void MKSetDeltaTMode(int newMode);
00399 
00406 extern int MKGetDeltaTMode(void);
00407 
00425 extern double MKSetTime(double newTime);
00426 
00451 extern MKMsgStruct 
00452   *MKNewMsgRequest(double timeOfMsg, SEL whichSelector, id destinationObject, int argCount, ...);
00453 
00454 extern MKMsgStruct 
00455   *MKNewMsgRequestWithObjectArgs(double timeOfMsg, SEL whichSelector, id destinationObject,
00456                    int argCount, id arg1, BOOL, id arg2, BOOL);
00457 
00483 extern void MKScheduleMsgRequest(MKMsgStruct *aMsgStructPtr, id conductor);
00484 
00511 extern MKMsgStruct *MKCancelMsgRequest(MKMsgStruct *aMsgStructPtr);
00512 
00537 extern MKMsgStruct *
00538   MKRescheduleMsgRequest(MKMsgStruct *aMsgStructPtr, id conductor,
00539                          double timeOfNewMsg, SEL whichSelector,
00540                          id destinationObject, int argCount, ...);
00541 
00542 extern MKMsgStruct *
00543   MKRescheduleMsgRequestWithObjectArgs(MKMsgStruct *aMsgStructPtr, id conductor,
00544                          double timeOfNewMsg, SEL whichSelector,
00545                          id destinationObject, int argCount,
00546                          id arg1, BOOL retainArg1,
00547                          id arg2, BOOL retainArg2);
00548 
00578 extern MKMsgStruct *MKRepositionMsgRequest(MKMsgStruct *aMsgStructPtr, double newTimeOfMsg);
00596 extern void MKFinishPerformance(void);
00597 
00598 @interface MKConductor: NSObject
00599 {
00601     double time;       
00603     double nextMsgTime;           // sb: relative to start of performance, I think.
00604     /* nextMsgTime = (nextbeat - time) * beatSize */
00606     double beatSize;    
00608     double timeOffset;
00613     BOOL isPaused;      
00615     id delegate;
00617     NSMutableArray *activePerformers;
00619     id MTCSynch;
00620 
00621     /* Internal use only */
00622 @private
00623     MKMsgStruct *_msgQueue;
00624     MKConductor *_condNext;
00625     MKConductor *_condLast;
00626     double _pauseOffset;
00627     double inverseBeatSize;
00628     double oldAdjustedClockTime;
00629     MKMsgStruct *pauseFor;
00630     unsigned char archivingFlags;
00631     unsigned char delegateFlags;
00632 }
00633  
00642 + allocWithZone: (NSZone *) zone;
00643 
00652 + alloc;
00653 
00662 - init;
00663 
00668 - copyWithZone: (NSZone *) zone;
00669 
00687 + startPerformance;
00688 
00700 + finishPerformance; 
00701 
00715 + pausePerformance; 
00716 
00725 + resumePerformance; 
00726 
00740 - pause; 
00741 
00759 - pauseFor: (double) seconds;
00760 
00767 - resume; 
00768 
00779 + (MKConductor *) defaultConductor; 
00780 
00786 +(BOOL) inPerformance; 
00787 
00792 + (BOOL) isPaused; 
00793 
00799 + currentConductor; 
00800 
00805 + clockConductor;
00806 
00813 + (BOOL) isClocked; 
00814 
00821 + (BOOL) isEmpty;
00822 
00829 + (BOOL) finishWhenEmpty;
00830 
00835 - (BOOL) isPaused; 
00836 
00841 - (double) beatSize; 
00842 
00847 - (double) tempo; 
00848 
00859 + (double) timeInSeconds; 
00860 
00866 - (double) timeInBeats; 
00867 
00872 - (double) timeOffset; 
00873 
00879 - (BOOL) isCurrentConductor;
00880 
00885 + (double) deltaT;
00886 
00891 - delegate;
00892 
00898 + delegate;
00899 
00908 - activePerformers;
00909 
00932 + setClocked: (BOOL) yesOrNo; 
00933 
00942 + setFinishWhenEmpty: (BOOL) yesOrNo; 
00943 
00951 - emptyQueue; 
00952 
00959 + (void) setDeltaT: (double) newDeltaT;
00960 
00971 - (void) setDelegate: (id) delegate;
00972 
00983 + (void) setDelegate: (id) delegate;
00984 
00991 
01010 + adjustTime; 
01011 
01022 - (double) setBeatSize: (double) newBeatSize; 
01023 
01033 -(double) setTempo: (double) newTempo; 
01034 
01045 - (double) setTimeOffset: (double) newTimeOffset; 
01046 
01047 /* Obsolete methods */
01048 - (double) predictTime:(double)beatTime; 
01049 
01057 
01076 - sel: (SEL) aSelector to: toObject withDelay: (double) beats argCount: (int) argCount, ...;
01077 
01100 - (id) sel: (SEL) aSelector
01101         to: (id) toObject
01102  withDelay: (double) beats
01103   argCount: (int) argCount
01104       arg1: (id) arg1 
01105     retain: (BOOL) retainArg1
01106       arg2: (id) arg2 
01107     retain: (BOOL) retainArg2;
01108 
01123 - sel: (SEL) aSelector to: toObject atTime: (double) time argCount: (int) argCount, ...;
01124 
01145 -    sel: (SEL) aSelector 
01146       to: (id) toObject 
01147   atTime: (double) time
01148 argCount: (int) argCount
01149     arg1: (id) arg1 
01150   retain: (BOOL) retainArg1
01151     arg2: (id) arg2 
01152   retain: (BOOL) retainArg2;
01153 
01170 + (MKMsgStruct *) afterPerformanceSel: (SEL) aSelector
01171                                    to: (id) toObject
01172                              argCount: (int) argCount, ...; 
01173 
01198 + (MKMsgStruct *) afterPerformanceSel: (SEL) aSelector 
01199                                    to: (id) toObject 
01200                              argCount: (int) argCount
01201                                  arg1: (id) arg1 
01202                                retain: (BOOL) retainArg1
01203                                  arg2: (id) arg2
01204                                retain: (BOOL) retainArg2;
01205 
01222 + (MKMsgStruct *) beforePerformanceSel: (SEL) aSelector to: toObject argCount: (int) argCount, ...; 
01223 
01247 + (MKMsgStruct *) beforePerformanceSel: (SEL) aSelector
01248                                     to: (id) toObject 
01249                               argCount: (int) argCount
01250                                   arg1: (id) arg1
01251                                 retain: (BOOL) retainArg1
01252                                   arg2: (id) arg2
01253                                 retain: (BOOL) retainArg2;
01254 
01257 - (void) encodeWithCoder: (NSCoder *) aCoder;
01258 - (id) initWithCoder: (NSCoder *) aDecoder;
01259 - awakeAfterUsingCoder: (NSCoder *) aDecoder;
01260 
01261 @end
01262 
01263 @interface MKConductor(MTC)
01264 
01281 - setMTCSynch: (MKMidi *) aMidiObj;
01282 
01291 - (MKMidi *) MTCSynch;
01292 
01304 - (double) clockTime;
01305 
01306 @end
01307 
01308 @interface MKConductor(SeparateThread)  <SndDelegateMessagePassing>
01309 
01325 + useSeparateThread: (BOOL) yesOrNo;
01326 
01333 + (BOOL) separateThreaded;
01334 
01341 + (BOOL) separateThreadedAndInMusicKitThread;
01342 
01359 + lockPerformance;
01360 
01372 + unlockPerformance;
01373 
01384 + (BOOL) lockPerformanceNoBlock;
01385 
01412 + setThreadPriority: (float) priorityFactor;
01413 
01418 + (NSThread *) performanceThread;
01419 
01440 + sendMsgToApplicationThreadSel: (SEL) aSelector to: (id) toObject argCount: (int) argCount, ...;
01441 
01452 + (void) detachDelegateMessageThread;
01453 
01467 + (void) sendMessageInMainThreadToTarget: (id) target 
01468                                      sel: (SEL) aSelector
01469                                     arg1: (id) arg1
01470                                     arg2: (id) arg2
01471                                    count: (int) count;
01472 
01482 + setInterThreadThreshold: (NSString *) newThreshold;
01483 
01495 + (void) _sendDelegateInvocation: (in unsigned long) mesg;
01496 
01497 @end
01498 
01499 #import "MKConductorDelegate.h"
01500 
01501 #ifdef __cplusplus
01502 }
01503 #endif
01504 
01505 #endif