quicktime.std.music
Class MusicData

java.lang.Object
  |
  +--quicktime.QTObject
        |
        +--quicktime.util.QTHandleRef
              |
              +--quicktime.util.QTHandle
                    |
                    +--quicktime.std.music.MusicData
All Implemented Interfaces:
quicktime.jdirect.InterfaceLib, quicktime.jdirect.PrimitivesLib, quicktime.jdirect.QuickTimeLib, quicktime.jdirect.SharedLibrary, com.apple.jdirect.SharedLibrary

public class MusicData
extends QTHandle

MusicData objects contain general information for a Music Track that the TunePlayer uses when it instantiates NoteChannels for the parts contained in the music media. MusicData object's internal data are all aligned on int values (ie. 32bit data segments) so the offsets for getting and setting values in this structure are expressed in terms of these 32bit values.

Data in MusicData is in big endian order and the stuff static methods return values are in the correct big endian format and order to be added to a MusicData object as is. If an application writes its own stuff methods they can return the data in big endian order to ensure compatibility with the existing stuff methods. Thus when music events are added to the MusicData they must be in big endian format and the values retrieved from a constructed MusicData object will be in big endian order.

Many of the macros that are provided in the QuickTimeMusic.h file are translated here as static methods. The names of the macros are represented here with the qtma_ removed and the first letter after the _ is NOT a capital. Thus qtma_StuffRestEvent becomes stuffRestEvent.

An application does NOT need to set the end of sequence marker event if this marker should be set as the last music data element in the MusicData object. The set... and get... calls will check for proper bounds and include a check that allows for the required existence of the end of sequence marker.


Field Summary
static int kNoteRequestHeaderEventLength
          The size (numer of ints) of a kNoteRequestEvent (including its header and footer)
 
Fields inherited from interface quicktime.jdirect.QuickTimeLib
JDirect_MacOSX, libraryInstance, name
 
Constructor Summary
MusicData(int size)
          Create a MusicData object of the specified number of bytes.
 
Method Summary
static int controlController(int x)
          Given a stuffed big-endian order QuickTime music event this method will extract the controller number.
static int controlValue(int x)
          Given a stuffed big-endian order QuickTime music event this method will extract the controller's specified value.
static int eventType(int x)
          Given a stuffed big-endian order QuickTime music event this method will extract the event type.
static int generalLength(int x)
          Given a stuffed big-endian order QuickTime music event this method will extract the general event's length from either header or the footer of the general event.
static int generalSubtype_Footer(int x)
          Given a stuffed big-endian order QuickTime music event this method will extract the general event's sub type from the footer of the general event.
 AtomicInstrument getAtomicInstrument(int offset)
          Returns an AtomicInstrument from the specified offset (numer of ints) into the MusicData.
 int getMusicEvent(int offset)
          Returns the big endian ordered stuffed QuickTime music event at the specified number of ints into the MusicData.
 NoteRequest getNoteRequest(int offset)
          Returns a NoteRequest object from the specified offset (numer of ints) into the MusicData.
 long getXMusicEvent(int offset)
          Returns the stuffed QuickTime extended music event at the specified number of ints into the MusicData.
static int markerSubtype(int x)
          Given a stuffed big-endian order QuickTime music event this method will extract the marker's sub type.
static int markerValue(int x)
          Given a stuffed big-endian order QuickTime music event this method will extract the marker's value.
static int noteDuration(int x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the note duration.
static int notePitch(int x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the note pitch.
static int noteVelocity(int x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the note velocity.
static int part(int x)
          Given a stuffed big-endian order QuickTime music event this method will extract the part number.
static int restDuration(int x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the rest duration.
 void setAtomicInstrument(int offset, int partNumber, AtomicInstrument ai)
          Copies the AtomicInstrument data to the specified offset (numer of ints) into the MusicData.
 void setMusicEvent(int offset, int musicData)
          Sets the big endian ordered stuffed QuickTime music event at the specified number of ints into the MusicData.
 void setNoteRequest(int offset, int partNumber, NoteRequest nr)
          Copies the NoteRequest data to the specified offset (numer of ints) into the MusicData.
 void setSize(int newSize)
          Resets the size of the MusicData object to the new size (in bytes).
 void setXMusicEvent(int offset, long musicData)
          Sets the stuffed QuickTime extended music event at the specified number of ints into the MusicData.
static int stuffControlEvent(int part, int control, int value)
          Returns an int that is the stuffed representation of the control music event.
static int stuffGeneralEvent_Footer(int subType, int length)
          Returns an int that is the stuffed representation of the footer portion of a general music event.
static int stuffGeneralEvent_Header(int part, int length)
          Returns an int that is the stuffed representation of the header portion of a general music event.
static int stuffMarkerEvent(int markerType, int markerValue)
          Returns an int that is the stuffed representation of the marker music event.
static int stuffNoteEvent(int part, int pitch, int velocity, int duration)
          Returns an int that is the stuffed representation of the note music event.
static int stuffRestEvent(int duration)
          Returns an int that is the stuffed representation of the rest music event.
static long stuffXControlEvent(int part, int control, int value)
          Returns a long that is the stuffed representation of the extended note music event.
static long stuffXKnobEvent(int part, int knob, int value)
          Returns a long that is the stuffed representation of the extended note music event.
static long stuffXNoteEvent(int part, int pitch, int volume, int duration)
          Returns a long that is the stuffed representation of the extended note music event.
static int xControlController(long x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the controller number.
static int xControlValue(long x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the controller number.
static int xKnobID(long x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the knob's value.
static int xKnobValue(long x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the knob's value.
static int xNoteDuration(long x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the note duration.
static int xNotePitch(long x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the note pitch.
static int xNoteVelocity(long x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the note velocity.
static int xPart(long x)
          Given a stuffed big-endian order QuickTime extended music event this method will extract the part number.
 
Methods inherited from class quicktime.util.QTHandle
clone, concatenate, fromEncodedImage, fromGraphicsExporterInput, fromGraphicsExporterOutput, fromGraphicsExporterText, fromGraphicsImporterAlias, fromGraphicsImporterData, fromSoundDescription, fromTimeCoderCurrent, fromTimeCoderSource, fromTimeCoderTime, fromTrack, reserveMemory
 
Methods inherited from class quicktime.util.QTHandleRef
copyFromArray, copyFromArray, copyFromArray, copyFromArray, copyFromArray, copyFromArray, copyFromArray, copyToArray, copyToArray, copyToArray, copyToArray, copyToArray, copyToArray, copyToArray, fromCompressionDialogState, fromSCSequence, getBytes, getSize, inMemory, isLocked, lock, lockHigh, moveHigh, toQTPointer, toQTPointer, toString, unlock
 
Methods inherited from class quicktime.QTObject
disposeQTObject, equals, ID
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

kNoteRequestHeaderEventLength

public static final int kNoteRequestHeaderEventLength
The size (numer of ints) of a kNoteRequestEvent (including its header and footer)
Constructor Detail

MusicData

public MusicData(int size)
          throws QTException
Create a MusicData object of the specified number of bytes. The end of sequence marker is inserted in the last four bytes of the MusicData object.
Parameters:
size - the size in bytes of the required MusicData object
Method Detail

stuffGeneralEvent_Header

public static int stuffGeneralEvent_Header(int part,
                                           int length)
Returns an int that is the stuffed representation of the header portion of a general music event.
Parameters:
part - the part that the event applies to
length - the length (including the surrounding general event header and footer) of the size of the general event. This size is in bytes.
Returns:
the stuffed representation of this type of music event in big endian order

stuffGeneralEvent_Footer

public static int stuffGeneralEvent_Footer(int subType,
                                           int length)
Returns an int that is the stuffed representation of the footer portion of a general music event.
Parameters:
part - the part that the event applies to
length - the length (including the surrounding general event header and footer) of the size of the general event. This size is in bytes.
Returns:
the stuffed representation of this type of music event in big endian order

stuffRestEvent

public static int stuffRestEvent(int duration)
Returns an int that is the stuffed representation of the rest music event.
Parameters:
duration - the duration in the time scale of the TunePlayer or the MusicMedia
Returns:
the stuffed representation of this type of music event in big endian order

stuffNoteEvent

public static int stuffNoteEvent(int part,
                                 int pitch,
                                 int velocity,
                                 int duration)
Returns an int that is the stuffed representation of the note music event.
Parameters:
part - the part that the note is played by
pitch - the MIDI note pitch of the note - valid range is 32 - 95 (with middle C as 60)
velocity - the note-on velocity when the note is played
duration - the duration in the time scale of the TunePlayer or the MusicMedia
Returns:
the stuffed representation of this type of music event in big endian order

stuffControlEvent

public static int stuffControlEvent(int part,
                                    int control,
                                    int value)
Returns an int that is the stuffed representation of the control music event.
Parameters:
part - the part that the note is played by
control - the number of the controller
value - 8.8 bit fixed point signed controller specific value
Returns:
the stuffed representation of this type of music event in big endian order

stuffMarkerEvent

public static int stuffMarkerEvent(int markerType,
                                   int markerValue)
Returns an int that is the stuffed representation of the marker music event.
Parameters:
markerType - the type of marker that is required
markerValue - the value applied to the specified marker
Returns:
the stuffed representation of this type of music event in big endian order

stuffXNoteEvent

public static long stuffXNoteEvent(int part,
                                   int pitch,
                                   int volume,
                                   int duration)
Returns a long that is the stuffed representation of the extended note music event. Extended music events are 2 big endian ints stuffed into a long.
Parameters:
part - the part that the note is played by
pitch - a 8.8 pitch value where the high 8 bits are the MIDI note number and the low 8 bits represent some fractional value of a semitone
velocity - the note-on velocity when the note is played
duration - the duration in the time scale of the TunePlayer or the MusicMedia
Returns:
the stuffed representation of this type of extended music event.

stuffXControlEvent

public static long stuffXControlEvent(int part,
                                      int control,
                                      int value)
Returns a long that is the stuffed representation of the extended note music event. Extended music events are 2 big endian ints stuffed into a long.
Parameters:
part - the part that the note is played by
control - the number of the controller
value - 8.8 bit fixed point signed controller specific value
Returns:
the stuffed representation of this type of extended music event.

stuffXKnobEvent

public static long stuffXKnobEvent(int part,
                                   int knob,
                                   int value)
Returns a long that is the stuffed representation of the extended note music event. Extended music events are 2 big endian ints stuffed into a long.
Parameters:
part - the part that the knob is applied too
knob - the knob
value - the new value for the specified knob
Returns:
the stuffed representation of this type of extended music event.

eventType

public static int eventType(int x)
Given a stuffed big-endian order QuickTime music event this method will extract the event type.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the music event

part

public static int part(int x)
Given a stuffed big-endian order QuickTime music event this method will extract the part number.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the music event

xPart

public static int xPart(long x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the part number.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

restDuration

public static int restDuration(int x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the rest duration.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

notePitch

public static int notePitch(int x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the note pitch.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

noteVelocity

public static int noteVelocity(int x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the note velocity.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

noteDuration

public static int noteDuration(int x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the note duration.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

xNotePitch

public static int xNotePitch(long x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the note pitch.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

xNoteVelocity

public static int xNoteVelocity(long x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the note velocity.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

xNoteDuration

public static int xNoteDuration(long x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the note duration.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

controlController

public static int controlController(int x)
Given a stuffed big-endian order QuickTime music event this method will extract the controller number.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the music event

controlValue

public static int controlValue(int x)
Given a stuffed big-endian order QuickTime music event this method will extract the controller's specified value.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the music event

xControlController

public static int xControlController(long x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the controller number.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

xControlValue

public static int xControlValue(long x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the controller number.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

markerSubtype

public static int markerSubtype(int x)
Given a stuffed big-endian order QuickTime music event this method will extract the marker's sub type.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the music event

markerValue

public static int markerValue(int x)
Given a stuffed big-endian order QuickTime music event this method will extract the marker's value.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the music event

xKnobValue

public static int xKnobValue(long x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the knob's value.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

xKnobID

public static int xKnobID(long x)
Given a stuffed big-endian order QuickTime extended music event this method will extract the knob's value.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the extended music event

generalSubtype_Footer

public static int generalSubtype_Footer(int x)
Given a stuffed big-endian order QuickTime music event this method will extract the general event's sub type from the footer of the general event.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the music event

generalLength

public static int generalLength(int x)
Given a stuffed big-endian order QuickTime music event this method will extract the general event's length from either header or the footer of the general event.
Parameters:
x - the stuffed big-endian music event
Returns:
the desired sub field of the music event

setSize

public void setSize(int newSize)
             throws UtilException
Resets the size of the MusicData object to the new size (in bytes). The end of sequence marker is inserted in the last four bytes of the MusicData object.
Overrides:
setSize in class QTHandle
Parameters:
newSize - - the new size of the MusicData object.

getMusicEvent

public int getMusicEvent(int offset)
                  throws QTException
Returns the big endian ordered stuffed QuickTime music event at the specified number of ints into the MusicData.
Parameters:
offset - - the number of ints in the header
Returns:
the big endian ordered music event
Throws:
QTException - if the offset would get data past the end of the MusicData

setMusicEvent

public void setMusicEvent(int offset,
                          int musicData)
                   throws QTException
Sets the big endian ordered stuffed QuickTime music event at the specified number of ints into the MusicData.

An application can only set the last four bytes if the value of the musicData in this case is the end of sequence marker - this is generally not required as it will be set by the constructor and setSize calls.

Parameters:
offset - - the number of ints in the header
musicData - the big endian ordered music event
Throws:
QTException - if the offset would set data past the end of the MusicData

getXMusicEvent

public long getXMusicEvent(int offset)
                    throws QTException
Returns the stuffed QuickTime extended music event at the specified number of ints into the MusicData. Extended music events are two big endian ints stuffed into a long.
Parameters:
offset - - the number of ints in the header
Returns:
the music event - two big endian ints stuffed into a long
Throws:
QTException - if the offset would get data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not an extended music event.

setXMusicEvent

public void setXMusicEvent(int offset,
                           long musicData)
                    throws QTException
Sets the stuffed QuickTime extended music event at the specified number of ints into the MusicData. Extended music events are two big endian ints stuffed into a long.
Parameters:
offset - - the number of ints in the header
musicData - the music event - two big endian ints stuffed into a long
Throws:
QTException - if the offset would set data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not an extended music event.

setNoteRequest

public void setNoteRequest(int offset,
                           int partNumber,
                           NoteRequest nr)
                    throws QTException
Copies the NoteRequest data to the specified offset (numer of ints) into the MusicData. This will also setup the note request header and tail values - the part number is used to associate the given note request with a part reference in the concommitant music data.

When a note request event is stuffed into music data it is surrounded by two ints:

Thus when calculating offsets for the position in the MusicData for a second NoteRequest event it is (given that the first note request is event is at the start of the music data and its offset is 1 as the header event takes up the first entry):
nextNoteEventOffset = StdQTConstants.kNoteRequestHeaderEventLength
The size (the number of ints) of a NoteRequest event (inc. header and footer) is supplied as the StdQTConstants.kNoteRequestHeaderEventLength constant in this class.

Parameters:
offset - - the number of music events (ints) into the header
partNumber - - the partNumber that is associated with this note request. The partNumber must be in the range of 0 to 0xFFF - the method will itself do the bit shifting required for the noteRequestEvent
nr - the NoteRequest to copy
Throws:
QTException - if the offset would set data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not a general music event.

getNoteRequest

public NoteRequest getNoteRequest(int offset)
                           throws QTException
Returns a NoteRequest object from the specified offset (numer of ints) into the MusicData. This checks to see if the data at that offset is a valid NoteRequest structure - if not a paramErr is thrown. Thus if retrieving a previously set NoteRequest the offset should take into account the addition of the head and tail fields of the setNoteRequest.
Parameters:
offset - - the number of ints in the header
Returns:
the NoteRequest
Throws:
QTException - if the offset would get data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not a general music event.

setAtomicInstrument

public void setAtomicInstrument(int offset,
                                int partNumber,
                                AtomicInstrument ai)
                         throws QTException
Copies the AtomicInstrument data to the specified offset (numer of ints) into the MusicData. This will also setup the atomic instrument header and tail values - the part number is used to associate the given instrument with a part reference in the concommitant music data.

When an AtomicInstrument event is stuffed into music data it is surrounded by two music events (ints):

Thus when calculating offsets for the position in the MusicData for a second AtomicInstrument event it is:
nextAtomicInstOffset = sizeOfPreviousGeneralEvent + 1 (where 1 is the header event for the ai you are setting)

Parameters:
offset - - the number of ints into the header
partNumber - - the partNumber that is associated with this atomic instrument. The partNumber must be in the range of 0 to 0xFFF - the method will itself do the bit shifting required for the noteRequestEvent
ai - the AtomicInstrument to copy
Throws:
QTException - if the offset would set data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not a general music event.

getAtomicInstrument

public AtomicInstrument getAtomicInstrument(int offset)
                                     throws QTException
Returns an AtomicInstrument from the specified offset (numer of ints) into the MusicData. This checks to see if the data at that offset is a valid AtomicInstrument structure - if not a paramErr exception is thrown Thus if retrieving a previously set AtomicInstrument the offset should take into account the addition of the head and tail fields of the AtomicInstrument event.
Parameters:
offset - - the number of ints in the header
Returns:
an AtomicInstrument
Throws:
QTException - if the offset would get data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not a general music event.