Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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, com.apple.jdirect.SharedLibrary, quicktime.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:

  - 0xFnnn0017 where nnn is the part number - signifies start of note request event (0x0017 is the size of a note request event)
  - the note request data
  - 0xC0010017 -> signifies end of note request event
  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):

  - 0xFnnnxxxx where nnn is the part number - signifies start of note request event (xxxx is the size of an atomic instrument + head and tail event)
  - the AtomicInstrument data
  - 0xC006xxxx -> signifies end of atomic instrument event (xxxx is the identical size as the header)
  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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD