MusicKit
0.0.0
|
00001 /* 00002 $Id$ 00003 Defined In: The MusicKit 00004 00005 Description: 00006 A MKNote object represents a musical sound or event by describing its 00007 attributes. This information falls into three categories: 00008 00009 * parameters 00010 * timing information 00011 * type information. 00012 00013 Most of the information in a MKNote is in its parameters; a MKNote can 00014 have any number of parameters. A parameter consists of an identifier, 00015 a string name, and a value. The identifier is a unique integer used 00016 to catalog the parameter within the MKNote; the MusicKit defines a 00017 number of parameter identifiers such as MK_freq (for frequency) and 00018 MK_amp (for amplitude). The string name is used to identify the 00019 parameter in a scorefile. The string names for the MusicKit 00020 parameters are the same as the identifier names, but without the "MK_" 00021 prefix. You can create your own parameter identifiers by passing a 00022 name to the parTagForName: class method. This method returns the identifier 00023 associated with the parameter name, creating it if it doesn't already 00024 exit. 00025 00026 A parameter's value can be a double, int, NSString object, an MKEnvelope object, 00027 MKWaveTable object, or other (non-MusicKit) object. These six 00028 parameter value types are represented by the following MKDataType 00029 constants: 00030 00031 * MK_double 00032 * MK_int 00033 * MK_string 00034 * MK_envelope 00035 * MK_waveTable 00036 * MK_object 00037 00038 The method you invoke to set a parameter value depends on the type of 00039 the value. To set a double value, for example, you would invoke the 00040 setPar:toDouble: method. Analogous methods exist for the other data 00041 types. 00042 00043 You can retrieve the value of a parameter as any of the parameter data 00044 types. For instance, the parAsInt: method returns an integer 00045 regardless of the parameter value's actual type. The exceptions are 00046 in retrieving object information: The parAsEnvelope:, parAsWaveTable:, 00047 and parAsObject: messages return nil if the parameter value isn't the 00048 specified type. 00049 00050 A MKNote's parameters are significant only if an object that processes 00051 the MKNote (such as an instance of a subclass of MKPerformer, MKNoteFilter, 00052 MKInstrument, or MKSynthPatch) accesses and uses the information. 00053 00054 Timing information is used to perform the MKNote at the proper time and 00055 for the proper duration. This information is called the MKNote's 00056 timeTag and duration, respectively. A single MKNote can have only one 00057 timeTag and one duration. Setting a MKNote's duration automatically 00058 changes its noteType to MK_noteDur, as described below. TimeTag and 00059 duration are measured in beats. 00060 00061 A MKNote has two pieces of type information, a noteType and a noteTag. 00062 A MKNote's noteType establishes its nature; there are six noteTypes: 00063 00064 * A noteDur represents an entire musical note (a note with a duration). 00065 * A noteOn establishes the beginning of a note. 00066 * A noteOff establishes the end of a note. 00067 * A noteUpdate represents the middle of a note (it updates a sounding note). 00068 * A mute makes no sound. 00069 00070 These are represented by MKNoteType constants: 00071 00072 * MK_noteDur 00073 * MK_noteOn 00074 * MK_noteOff 00075 * MK_noteUpdate 00076 * MK_mute 00077 00078 The default is MK_mute. 00079 00080 NoteTags are integers used to identify MKNote objects that are part of 00081 the same musical sound or event; in particular, matching noteTags are 00082 used to create noteOn/noteOff pairs and to associate noteUpdates with 00083 other MKNotes. (A noteUpdate without a noteTag updates all the MKNotes in 00084 its MKPart.) 00085 00086 The C function MKNoteTag() is provided to generate noteTag values that 00087 are guaranteed to be unique across your entire application -- you 00088 should never create a new noteTag except through this function. The 00089 actual integer value of a noteTag has no significance (the range of 00090 noteTag values extends from 0 to 2^BITS_PER_INT). 00091 00092 Mutes can't have noteTags; if you set the noteTag of such a MKNote, it 00093 automatically becomes a noteUpdate. 00094 00095 MKNotes are typically added to MKPart objects. A MKPart is a time-ordered 00096 collection of MKNotes. 00097 00098 Original Author: David Jaffe 00099 00100 Copyright (c) 1988-1992, NeXT Computer, Inc. 00101 Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT 00102 Portions Copyright (c) 1994 Stanford University 00103 Portions Copyright (c) 1999-2005 The MusicKit Project. 00104 */ 00105 00106 @class MKPart; 00107 @class MKPerformer; 00108 00373 #ifndef __MK_Note_H___ 00374 #define __MK_Note_H___ 00375 00376 #import <Foundation/Foundation.h> 00377 #import <Foundation/NSObject.h> 00378 #import "MKConductor.h" 00379 #import "params.h" 00380 00381 #define BITS_PER_INT 32 00382 #define MK_MKPARBITVECTS ((((int)MK_appPars-1)/ BITS_PER_INT)+1) 00383 00391 typedef enum _MKNoteType { 00393 MK_noteDur = 257, 00395 MK_noteOn, 00397 MK_noteOff, 00399 MK_noteUpdate, 00401 MK_mute 00402 } MKNoteType; 00403 00407 typedef enum _MKDataType { 00409 MK_noType = ((int)MK_sysReset + 1), 00411 MK_double, 00413 MK_string, 00415 MK_int, 00417 MK_object, 00419 MK_envelope, 00421 MK_waveTable 00422 } MKDataType; 00423 00424 @interface MKNote: NSObject 00425 { 00427 MKNoteType noteType; 00429 int noteTag; 00431 MKPerformer *performer; 00433 MKPart *part; 00435 double timeTag; 00437 MKConductor *conductor; 00438 00439 @private 00440 NSHashTable *_parameters; /* Set of parameter values. */ 00441 unsigned _mkPars[MK_MKPARBITVECTS]; /* Bit vectors specifying presence of MusicKit parameters. */ 00442 unsigned *_appPars; /* Bit-vector for application-defined parameters. */ 00443 unsigned short _highAppPar; /* Highest bit in _appPars (0 if none). */ 00444 /* _orderTag disambiguates simultaneous notes. If it's negative, 00445 it means that the MKNote is actually slated for deletion. In this case, 00446 the ordering is the absolute value of _orderTag. */ 00447 int _orderTag; 00448 } 00449 00458 - initWithTimeTag:(double) aTimeTag; 00459 00474 - init; 00475 00484 - (void) dealloc; 00485 00494 - copyWithZone: (NSZone *) zone; 00495 00527 - split: (id *) aNoteOn : (id *) aNoteOff; 00528 00538 - (MKPerformer *) performer; 00539 00548 - (MKPart *) part; 00549 00564 - (MKConductor *) conductor; 00565 00578 - (void) setConductor: (MKConductor *) newConductor; 00579 00590 - (MKPart *) addToPart: (MKPart *) aPart; 00591 00601 - (double) timeTag; 00602 00616 - (double) setTimeTag: (double) newTimeTag; 00617 00633 - (double) setTimeTagPreserveEndTime: (double) newTimeTag; 00634 00640 - (MKPart *) removeFromPart; 00641 00667 -(int) compare: (MKNote *) aNote; 00668 /* 00669 * If the MKNotes are both not in parts or are in different parts, the 00670 * result is indeterminate. 00671 */ 00672 00673 00688 - (MKNoteType) noteType; 00689 00711 - setNoteType: (MKNoteType) newNoteType; 00712 00726 - (double) setDur: (double) value; 00727 00743 - (double) dur; 00744 00749 - (double) setEndTime: (double) newEndTime; 00750 00754 - (double) endTime; 00755 00761 - (int) noteTag; 00762 00783 - setNoteTag: (int) newTag; 00784 00791 - removeNoteTag; 00792 00803 + (int) parTagForName: (NSString *) aName; 00804 00815 + (NSString *) parNameForTag: (int) aTag; 00816 00829 - setPar: (int) parameterTag toDouble: (double) aDouble; 00830 00842 - setPar: (int) parameterTag toInt: (int) anInteger; 00843 00855 - setPar: (int) parameterTag toString: (NSString *) aString; 00856 00868 - setPar: (int) parameterTag toEnvelope: (id) anEnvelope; 00869 00881 - setPar: (int) parameterTag toWaveTable: (id) aWaveTable; 00882 00917 - setPar: (int) parameterTag toObject: (id) anObject; 00918 00931 - (double) parAsDouble: (int) parameterTag; 00932 00941 - (int) parAsInt: (int) parameterTag; 00942 00951 - (NSString *) parAsString: (int) parameterTag; 00952 00965 - (NSString *) parAsStringNoCopy: (int) parameterTag; 00966 00975 - parAsEnvelope: (int) parameterTag; 00976 00984 - parAsWaveTable: (int) parameterTag; 00985 00996 - parAsObject: (int) parameterTag; 00997 01006 - (BOOL) isParPresent: (int) parameterTag; 01007 01051 - (MKDataType) parType: (int) parameterTag; 01052 01063 - removePar: (int) parameterTag; 01064 01073 - copyParsFrom: (MKNote *) aNote; 01074 01096 - (double) freq; 01097 01116 - (int) keyNum; 01117 01127 - writeScorefileStream: (NSMutableData *) aStream; 01128 01129 /* 01130 You never send this message directly. 01131 Archives parameters, noteType, noteTag, and timeTag. Also archives 01132 performer and part using MKWriteObjectReference(). 01133 */ 01134 - (void) encodeWithCoder: (NSCoder *) aCoder; 01135 01136 /* 01137 You never send this message directly. 01138 Reads MKNote back from archive file. Note that the noteTag is NOT mapped 01139 onto a unique note tag. This is left up to the MKPart or MKScore with which 01140 the MKNote is unarchived. 01141 */ 01142 - (id) initWithCoder: (NSCoder *) aDecoder; 01143 01152 - (int) parVectorCount; 01153 01173 - (unsigned) parVector: (unsigned) index; 01174 /* 01175 * Returns a bit vector indicating the presence of parameters 01176 * identified by integers (index * BITS_PER_INT) through 01177 * ((index + 1) * BITS_PER_INT - 1). For example, 01178 * 01179 * .ib 01180 * unsigned int parVect = [aNote checkParVector:0]; 01181 * .iq 01182 * 01183 * returns the vector for parameters 0-31. 01184 * An argument of 1 returns the vector for parameters 32-63, etc. 01185 * 01186 * parVectorCount gives the number of parVectors. For example, if the 01187 * highest parameter is 65, parVectorCount returns 3. 01188 */ 01189 01190 // for debugging 01191 - (NSString *) description; 01192 01197 + note; 01198 01207 + noteWithTimeTag: (double) aTimeTag; 01208 01209 @end 01210 01229 extern unsigned MKNoteTag(void); 01230 01247 extern unsigned MKNoteTags(unsigned n); 01248 01268 extern double MKdB(double dB); 01269 01311 extern double MKMidiToAmp(int midiValue); 01312 01342 extern double MKMidiToAmpWithSensitivity(int midiValue, double sensitivity); 01343 01375 extern int MKAmpToMidi(double amp); 01376 01405 extern double MKMidiToAmpAttenuation(int midiValue); 01406 01450 extern double MKMidiToAmpAttenuationWithSensitivity(int midiValue, double sensitivity); 01451 01497 extern int MKAmpAttenuationToMidi(double amp); 01498 01517 extern int MKHighestPar(void); 01518 01578 extern NSHashEnumerator *MKInitParameterIteration(MKNote *aNote); 01579 01604 extern int MKNextParameter(MKNote *aNote, NSHashEnumerator *iterationState); 01605 01611 01682 extern id MKSetNoteParToDouble(MKNote *aNote, int par, double value); 01683 01710 extern id MKSetNoteParToInt(MKNote *aNote, int par, int value); 01711 01738 extern id MKSetNoteParToString(MKNote *aNote, int par, NSString *value); 01739 01766 extern id MKSetNoteParToEnvelope(MKNote *aNote, int par, id envObj); 01767 01794 extern id MKSetNoteParToWaveTable(MKNote *aNote, int par, id waveObj); 01795 01822 extern id MKSetNoteParToObject(MKNote *aNote, int par, id anObj); 01823 01890 extern double MKGetNoteParAsDouble(MKNote *aNote, int par); 01891 01918 extern int MKGetNoteParAsInt(MKNote *aNote, int par); 01919 01946 extern NSString *MKGetNoteParAsString(MKNote *aNote, int par); 01947 01973 extern NSString *MKGetNoteParAsStringNoCopy(MKNote *aNote, int par); 01974 02001 extern id MKGetNoteParAsEnvelope(MKNote *aNote, int par); 02002 02029 extern id MKGetNoteParAsWaveTable(MKNote *aNote, int par); 02030 02057 extern id MKGetNoteParAsObject(MKNote *aNote, int par); 02058 02089 extern BOOL MKIsNoteParPresent(MKNote *aNote, int par); 02090 02091 #endif