JDK14/Java14源码在线阅读
/*
* Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sound.midi;
/**
* A {@code ShortMessage} contains a MIDI message that has at most two data
* bytes following its status byte. The types of MIDI message that satisfy this
* criterion are channel voice, channel mode, system common, and system
* real-time--in other words, everything except system exclusive and
* meta-events. The {@code ShortMessage} class provides methods for getting and
* setting the contents of the MIDI message.
* <p>
* A number of {@code ShortMessage} methods have integer parameters by which you
* specify a MIDI status or data byte. If you know the numeric value, you can
* express it directly. For system common and system real-time messages, you can
* often use the corresponding fields of {@code ShortMessage}, such as
* {@link #SYSTEM_RESET SYSTEM_RESET}. For channel messages, the upper four bits
* of the status byte are specified by a command value and the lower four bits
* are specified by a MIDI channel number. To convert incoming MIDI data bytes
* that are in the form of Java's signed bytes, you can use the
* <a href="MidiMessage.html#integersVsBytes">conversion code</a> given in the
* {@link MidiMessage} class description.
*
* @author David Rivas
* @author Kara Kytle
* @author Florian Bomers
* @see SysexMessage
* @see MetaMessage
*/
public class ShortMessage extends MidiMessage {
// Status byte defines
// System common messages
/**
* Status byte for MIDI Time Code Quarter Frame message (0xF1, or 241).
*
* @see MidiMessage#getStatus
*/
public static final int MIDI_TIME_CODE = 0xF1; // 241
/**
* Status byte for Song Position Pointer message (0xF2, or 242).
*
* @see MidiMessage#getStatus
*/
public static final int SONG_POSITION_POINTER = 0xF2; // 242
/**
* Status byte for MIDI Song Select message (0xF3, or 243).
*
* @see MidiMessage#getStatus
*/
public static final int SONG_SELECT = 0xF3; // 243
/**
* Status byte for Tune Request message (0xF6, or 246).
*
* @see MidiMessage#getStatus
*/
public static final int TUNE_REQUEST = 0xF6; // 246
/**
* Status byte for End of System Exclusive message (0xF7, or 247).
*
* @see MidiMessage#getStatus
*/
public static final int END_OF_EXCLUSIVE = 0xF7; // 247
// System real-time messages
/**
* Status byte for Timing Clock message (0xF8, or 248).
*
* @see MidiMessage#getStatus
*/
public static final int TIMING_CLOCK = 0xF8; // 248
/**
* Status byte for Start message (0xFA, or 250).
*
* @see MidiMessage#getStatus
*/
public static final int START = 0xFA; // 250
/**
* Status byte for Continue message (0xFB, or 251).
*
* @see MidiMessage#getStatus
*/
public static final int CONTINUE = 0xFB; // 251
/**
* Status byte for Stop message (0xFC, or 252).
*
* @see MidiMessage#getStatus
*/
public static final int STOP = 0xFC; //252
/**
* Status byte for Active Sensing message (0xFE, or 254).
*
* @see MidiMessage#getStatus
*/
public static final int ACTIVE_SENSING = 0xFE; // 254
/**
* Status byte for System Reset message (0xFF, or 255).
*
* @see MidiMessage#getStatus
*/
public static final int SYSTEM_RESET = 0xFF; // 255
// Channel voice message upper nibble defines
/**
* Command value for Note Off message (0x80, or 128).
*/
public static final int NOTE_OFF = 0x80; // 128
/**
* Command value for Note On message (0x90, or 144).
*/
public static final int NOTE_ON = 0x90; // 144
/**
* Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or
* 160).
*/
public static final int POLY_PRESSURE = 0xA0; // 160
/**
* Command value for Control Change message (0xB0, or 176).
*/
public static final int CONTROL_CHANGE = 0xB0; // 176
/**
* Command value for Program Change message (0xC0, or 192).
*/
public static final int PROGRAM_CHANGE = 0xC0; // 192
/**
* Command value for Channel Pressure (Aftertouch) message (0xD0, or 208).
*/
public static final int CHANNEL_PRESSURE = 0xD0; // 208
/**
* Command value for Pitch Bend message (0xE0, or 224).
*/
public static final int PITCH_BEND = 0xE0; // 224
/**
* Constructs a new {@code ShortMessage}. The contents of the new message
* are guaranteed to specify a valid MIDI message. Subsequently, you may set
* the contents of the message using one of the {@code setMessage} methods.
*
* @see #setMessage
*/
public ShortMessage() {
this(new byte[3]);
// Default message data: NOTE_ON on Channel 0 with max volume
data[0] = (byte) (NOTE_ON & 0xFF);
data[1] = (byte) 64;
data[2] = (byte) 127;
length = 3;
}
/**
* Constructs a new {@code ShortMessage} which represents a MIDI message
* that takes no data bytes. The contents of the message can be changed by
* using one of the {@code setMessage} methods.
*
* @param status the MIDI status byte
* @throws InvalidMidiDataException if {@code status} does not specify a
* valid MIDI status byte for a message that requires no data bytes
* @see #setMessage(int)
* @see #setMessage(int, int, int)
* @see #setMessage(int, int, int, int)
* @see #getStatus()
* @since 1.7
*/
public ShortMessage(int status) throws InvalidMidiDataException {
super(null);
setMessage(status); // can throw InvalidMidiDataException
}
/**
* Constructs a new {@code ShortMessage} which represents a MIDI message
* that takes up to two data bytes. If the message only takes one data byte,
* the second data byte is ignored. If the message does not take any data
* bytes, both data bytes are ignored. The contents of the message can be
* changed by using one of the {@code setMessage} methods.
*
* @param status the MIDI status byte
* @param data1 the first data byte
* @param data2 the second data byte
* @throws InvalidMidiDataException if the status byte or all data bytes
* belonging to the message do not specify a valid MIDI message
* @see #setMessage(int)
* @see #setMessage(int, int, int)
* @see #setMessage(int, int, int, int)
* @see #getStatus()
* @see #getData1()
* @see #getData2()
* @since 1.7
*/
public ShortMessage(int status, int data1, int data2)
throws InvalidMidiDataException {
super(null);
setMessage(status, data1, data2); // can throw InvalidMidiDataException
}
/**
* Constructs a new {@code ShortMessage} which represents a channel MIDI
* message that takes up to two data bytes. If the message only takes one
* data byte, the second data byte is ignored. If the message does not take
* any data bytes, both data bytes are ignored. The contents of the message
* can be changed by using one of the {@code setMessage} methods.
*
* @param command the MIDI command represented by this message
* @param channel the channel associated with the message
* @param data1 the first data byte
* @param data2 the second data byte
* @throws InvalidMidiDataException if the command value, channel value or
* all data bytes belonging to the message do not specify a valid
* MIDI message
* @see #setMessage(int)
* @see #setMessage(int, int, int)
* @see #setMessage(int, int, int, int)
* @see #getCommand()
* @see #getChannel()
* @see #getData1()
* @see #getData2()
* @since 1.7
*/
public ShortMessage(int command, int channel, int data1, int data2)
throws InvalidMidiDataException {
super(null);
setMessage(command, channel, data1, data2);
}
/**
* Constructs a new {@code ShortMessage}.
*
* @param data an array of bytes containing the complete message. The
* message data may be changed using the {@code setMessage} method.
* @see #setMessage
*/
// $$fb this should throw an Exception in case of an illegal message!
protected ShortMessage(byte[] data) {
// $$fb this may set an invalid message.
// Can't correct without compromising compatibility
super(data);
}
/**
* Sets the parameters for a MIDI message that takes no data bytes.
*
* @param status the MIDI status byte
* @throws InvalidMidiDataException if {@code status} does not specify a
* valid MIDI status byte for a message that requires no data bytes
* @see #setMessage(int, int, int)
* @see #setMessage(int, int, int, int)
*/
public void setMessage(int status) throws InvalidMidiDataException {
// check for valid values
int dataLength = getDataLength(status); // can throw InvalidMidiDataException
if (dataLength != 0) {
throw new InvalidMidiDataException("Status byte; " + status + " requires " + dataLength + " data bytes");
}
setMessage(status, 0, 0);
}
/**
* Sets the parameters for a MIDI message that takes one or two data bytes.
* If the message takes only one data byte, the second data byte is ignored;
* if the message does not take any data bytes, both data bytes are ignored.
*
* @param status the MIDI status byte
* @param data1 the first data byte
* @param data2 the second data byte
* @throws InvalidMidiDataException if the status byte, or all data bytes
* belonging to the message, do not specify a valid MIDI message
* @see #setMessage(int, int, int, int)
* @see #setMessage(int)
*/
public void setMessage(int status, int data1, int data2) throws InvalidMidiDataException {
// check for valid values
int dataLength = getDataLength(status); // can throw InvalidMidiDataException
if (dataLength > 0) {
if (data1 < 0 || data1 > 127) {
throw new InvalidMidiDataException("data1 out of range: " + data1);
}
if (dataLength > 1) {
if (data2 < 0 || data2 > 127) {
throw new InvalidMidiDataException("data2 out of range: " + data2);
}
}
}
// set the length
length = dataLength + 1;
// re-allocate array if ShortMessage(byte[]) constructor gave array with fewer elements
if (data == null || data.length < length) {
data = new byte[3];
}
// set the data
data[0] = (byte) (status & 0xFF);
if (length > 1) {
data[1] = (byte) (data1 & 0xFF);
if (length > 2) {
data[2] = (byte) (data2 & 0xFF);
}
}
}
/**
* Sets the short message parameters for a channel message which takes up to
* two data bytes. If the message only takes one data byte, the second data
* byte is ignored; if the message does not take any data bytes, both data
* bytes are ignored.
*
* @param command the MIDI command represented by this message
* @param channel the channel associated with the message
* @param data1 the first data byte
* @param data2 the second data byte
* @throws InvalidMidiDataException if the status byte or all data bytes
* belonging to the message, do not specify a valid MIDI message
* @see #setMessage(int, int, int)
* @see #setMessage(int)
* @see #getCommand
* @see #getChannel
* @see #getData1
* @see #getData2
*/
public void setMessage(int command, int channel, int data1, int data2) throws InvalidMidiDataException {
// check for valid values
if (command >= 0xF0 || command < 0x80) {
throw new InvalidMidiDataException("command out of range: 0x" + Integer.toHexString(command));
}
if ((channel & 0xFFFFFFF0) != 0) { // <=> (channel<0 || channel>15)
throw new InvalidMidiDataException("channel out of range: " + channel);
}
setMessage((command & 0xF0) | (channel & 0x0F), data1, data2);
}
/**
* Obtains the MIDI channel associated with this event. This method assumes
* that the event is a MIDI channel message; if not, the return value will
* not be meaningful.
*
* @return MIDI channel associated with the message
* @see #setMessage(int, int, int, int)
*/
public int getChannel() {
// this returns 0 if an invalid message is set
return (getStatus() & 0x0F);
}
/**
* Obtains the MIDI command associated with this event. This method assumes
* that the event is a MIDI channel message; if not, the return value will
* not be meaningful.
*
* @return the MIDI command associated with this event
* @see #setMessage(int, int, int, int)
*/
public int getCommand() {
// this returns 0 if an invalid message is set
return (getStatus() & 0xF0);
}
/**
* Obtains the first data byte in the message.
*
* @return the value of the {@code data1} field
* @see #setMessage(int, int, int)
*/
public int getData1() {
if (length > 1) {
return (data[1] & 0xFF);
}
return 0;
}
/**
* Obtains the second data byte in the message.
*
* @return the value of the {@code data2} field
* @see #setMessage(int, int, int)
*/
public int getData2() {
if (length > 2) {
return (data[2] & 0xFF);
}
return 0;
}
/**
* Creates a new object of the same class and with the same contents as this
* object.
*
* @return a clone of this instance
*/
@Override
public Object clone() {
byte[] newData = new byte[length];
System.arraycopy(data, 0, newData, 0, newData.length);
return new ShortMessage(newData);
}
/**
/**代码未完, 请加载全部代码(NowJava.com).**/
关注时代Java
关注时代Java