MusicKit  0.0.0
MKNote.h
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