MKNote.h

Go to the documentation of this file.

/*
  $Id: MKNote.h 3449 2009-04-04 16:52:47Z leighsmith $
  Defined In: The MusicKit

  Description:   
    A MKNote object represents a musical sound or event by describing its
    attributes.  This information falls into three categories:
   
    * parameters
    * timing information
    * type information.
   
    Most of the information in a MKNote is in its parameters; a MKNote can
    have any number of parameters.  A parameter consists of an identifier,
    a string name, and a value.  The identifier is a unique integer used
    to catalog the parameter within the MKNote; the MusicKit defines a
    number of parameter identifiers such as MK_freq (for frequency) and
    MK_amp (for amplitude).  The string name is used to identify the
    parameter in a scorefile.  The string names for the MusicKit
    parameters are the same as the identifier names, but without the "MK_"
    prefix.  You can create your own parameter identifiers by passing a
    name to the parTagForName: class method.  This method returns the identifier
    associated with the parameter name, creating it if it doesn't already
    exit.
   
    A parameter's value can be a double, int, NSString object, an MKEnvelope object,
    MKWaveTable object, or other (non-MusicKit) object.  These six
    parameter value types are represented by the following MKDataType
    constants:
   
    * MK_double
    * MK_int
    * MK_string
    * MK_envelope
    * MK_waveTable
    * MK_object
   
    The method you invoke to set a parameter value depends on the type of
    the value.  To set a double value, for example, you would invoke the
    setPar:toDouble: method.  Analogous methods exist for the other data
    types.
   
    You can retrieve the value of a parameter as any of the parameter data
    types.  For instance, the parAsInt: method returns an integer
    regardless of the parameter value's actual type.  The exceptions are
    in retrieving object information: The parAsEnvelope:, parAsWaveTable:,
    and parAsObject: messages return nil if the parameter value isn't the
    specified type.
   
    A MKNote's parameters are significant only if an object that processes
    the MKNote (such as an instance of a subclass of MKPerformer, MKNoteFilter,
    MKInstrument, or MKSynthPatch) accesses and uses the information.
   
    Timing information is used to perform the MKNote at the proper time and
    for the proper duration.  This information is called the MKNote's
    timeTag and duration, respectively.  A single MKNote can have only one
    timeTag and one duration.  Setting a MKNote's duration automatically
    changes its noteType to MK_noteDur, as described below.  TimeTag and
    duration are measured in beats.
   
    A MKNote has two pieces of type information, a noteType and a noteTag.
    A MKNote's noteType establishes its nature; there are six noteTypes:
   
    * A noteDur represents an entire musical note (a note with a duration).
    * A noteOn establishes the beginning of a note.
    * A noteOff establishes the end of a note.
    * A noteUpdate represents the middle of a note (it updates a sounding note).
    * A mute makes no sound.
   
    These are represented by MKNoteType constants:
   
    * MK_noteDur
    * MK_noteOn
    * MK_noteOff
    * MK_noteUpdate
    * MK_mute
   
    The default is MK_mute.
   
    NoteTags are integers used to identify MKNote objects that are part of
    the same musical sound or event; in particular, matching noteTags are
    used to create noteOn/noteOff pairs and to associate noteUpdates with
    other MKNotes.  (A noteUpdate without a noteTag updates all the MKNotes in
    its MKPart.)
  
    The C function MKNoteTag() is provided to generate noteTag values that
    are guaranteed to be unique across your entire application -- you
    should never create a new noteTag except through this function.  The
    actual integer value of a noteTag has no significance (the range of
    noteTag values extends from 0 to 2^BITS_PER_INT).
   
    Mutes can't have noteTags; if you set the noteTag of such a MKNote, it
    automatically becomes a noteUpdate.
   
    MKNotes are typically added to MKPart objects.  A MKPart is a time-ordered
    collection of MKNotes.
  
  Original Author: David Jaffe

  Copyright (c) 1988-1992, NeXT Computer, Inc.
  Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
  Portions Copyright (c) 1994 Stanford University
  Portions Copyright (c) 1999-2005 The MusicKit Project.
*/

@class MKPart;
@class MKPerformer;

#ifndef __MK_Note_H___
#define __MK_Note_H___

#import <Foundation/Foundation.h>
#import <Foundation/NSObject.h>
#import "MKConductor.h"
#import "params.h"

#define BITS_PER_INT 32
#define MK_MKPARBITVECTS ((((int)MK_appPars-1)/ BITS_PER_INT)+1)

typedef enum _MKNoteType {
    MK_noteDur = 257,
    MK_noteOn,
    MK_noteOff,
    MK_noteUpdate,
    MK_mute
} MKNoteType;

typedef enum _MKDataType {
    MK_noType = ((int)MK_sysReset + 1),
    MK_double,  
    MK_string,
    MK_int,
    MK_object,
    MK_envelope, 
    MK_waveTable
} MKDataType;

@interface MKNote: NSObject
{
    MKNoteType noteType;
    int noteTag;
    MKPerformer *performer;   
    MKPart *part;
    double timeTag;
    MKConductor *conductor;  

@private
    NSHashTable *_parameters;       /* Set of parameter values. */
    unsigned _mkPars; /* Bit vectors specifying presence of MusicKit parameters. */
    unsigned *_appPars; /* Bit-vector for application-defined parameters. */
    unsigned short _highAppPar; /* Highest bit in _appPars (0 if none). */
    /* _orderTag disambiguates simultaneous notes. If it's negative,
       it means that the MKNote is actually slated for deletion. In this case,
       the ordering is the absolute value of _orderTag. */
    int _orderTag;
} 

- initWithTimeTag:(double) aTimeTag;

- init;

- (void) dealloc; 

- copyWithZone: (NSZone *) zone; 

- split: (id *) aNoteOn : (id *) aNoteOff; 

- (MKPerformer *) performer; 

- (MKPart *) part; 

- (MKConductor *) conductor; 

- (void) setConductor: (MKConductor *) newConductor; 

- (MKPart *) addToPart: (MKPart *) aPart; 

- (double) timeTag; 

- (double) setTimeTag: (double) newTimeTag; 

- (double) setTimeTagPreserveEndTime: (double) newTimeTag;

- (MKPart *) removeFromPart; 

-(int) compare: (MKNote *) aNote; 
 /* 
  * If the MKNotes are both not in parts or are in different parts, the
  * result is indeterminate.
  */


- (MKNoteType) noteType; 

- setNoteType: (MKNoteType) newNoteType; 

- (double) setDur: (double) value;

- (double) dur; 

- (double) setEndTime: (double) newEndTime;

- (double) endTime;

- (int) noteTag; 

- setNoteTag: (int) newTag; 

- removeNoteTag;

+ (int) parTagForName: (NSString *) aName; 

+ (NSString *) parNameForTag: (int) aTag;

- setPar: (int) parameterTag toDouble: (double) aDouble; 

- setPar: (int) parameterTag toInt: (int) anInteger; 

- setPar: (int) parameterTag toString: (NSString *) aString; 

- setPar: (int) parameterTag toEnvelope: (id) anEnvelope; 

- setPar: (int) parameterTag toWaveTable: (id) aWaveTable; 

- setPar: (int) parameterTag toObject: (id) anObject; 

- (double) parAsDouble: (int) parameterTag; 

- (int) parAsInt: (int) parameterTag; 

- (NSString *) parAsString: (int) parameterTag; 

- (NSString *) parAsStringNoCopy: (int) parameterTag; 

- parAsEnvelope: (int) parameterTag; 

- parAsWaveTable: (int) parameterTag;

- parAsObject: (int) parameterTag; 

- (BOOL) isParPresent: (int) parameterTag;

- (MKDataType) parType: (int) parameterTag; 

- removePar: (int) parameterTag; 

- copyParsFrom: (MKNote *) aNote; 

- (double) freq;

- (int) keyNum; 

- writeScorefileStream: (NSMutableData *) aStream; 

/* 
 You never send this message directly.
 Archives parameters, noteType, noteTag, and timeTag. Also archives
 performer and part using MKWriteObjectReference(). 
 */
- (void) encodeWithCoder: (NSCoder *) aCoder;

/* 
 You never send this message directly.  
 Reads MKNote back from archive file. Note that the noteTag is NOT mapped
 onto a unique note tag. This is left up to the MKPart or MKScore with which
 the MKNote is unarchived.
 */
- (id) initWithCoder: (NSCoder *) aDecoder;

- (int) parVectorCount;

- (unsigned) parVector: (unsigned) index;
 /* 
 * Returns a bit vector indicating the presence of parameters 
 * identified by integers (index * BITS_PER_INT) through 
 * ((index + 1) * BITS_PER_INT - 1). For example,
 *
 * .ib
 * unsigned int parVect = [aNote checkParVector:0];
 * .iq
 *
 * returns the vector for parameters 0-31.
 * An argument of 1 returns the vector for parameters 32-63, etc.
 *
 * parVectorCount gives the number of parVectors. For example, if the
 * highest parameter is 65, parVectorCount returns 3.
 */

// for debugging
- (NSString *) description;

+ note;

+ noteWithTimeTag: (double) aTimeTag; 

@end

extern unsigned MKNoteTag(void);

extern unsigned MKNoteTags(unsigned n);

extern double MKdB(double dB);          

extern double MKMidiToAmp(int midiValue);

extern double MKMidiToAmpWithSensitivity(int midiValue, double sensitivity);

extern int MKAmpToMidi(double amp);

extern double MKMidiToAmpAttenuation(int midiValue);

extern double MKMidiToAmpAttenuationWithSensitivity(int midiValue, double sensitivity);

extern int MKAmpAttenuationToMidi(double amp);

extern int MKHighestPar(void);

extern NSHashEnumerator *MKInitParameterIteration(MKNote *aNote);

extern int MKNextParameter(MKNote *aNote, NSHashEnumerator *iterationState);


extern id MKSetNoteParToDouble(MKNote *aNote, int par, double value);

extern id MKSetNoteParToInt(MKNote *aNote, int par, int value);

extern id MKSetNoteParToString(MKNote *aNote, int par, NSString *value);

extern id MKSetNoteParToEnvelope(MKNote *aNote, int par, id envObj);

extern id MKSetNoteParToWaveTable(MKNote *aNote, int par, id waveObj);

extern id MKSetNoteParToObject(MKNote *aNote, int par, id anObj);

extern double MKGetNoteParAsDouble(MKNote *aNote, int par);

extern int MKGetNoteParAsInt(MKNote *aNote, int par);

extern NSString *MKGetNoteParAsString(MKNote *aNote, int par);

extern NSString *MKGetNoteParAsStringNoCopy(MKNote *aNote, int par);

extern id MKGetNoteParAsEnvelope(MKNote *aNote, int par);

extern id MKGetNoteParAsWaveTable(MKNote *aNote, int par);

extern id MKGetNoteParAsObject(MKNote *aNote, int par);

extern BOOL MKIsNoteParPresent(MKNote *aNote, int par);

#endif

---