/*
* Copyright (c) 1999, 2017, 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.sampled;
import java.util.Arrays;
/**
* {@code DataLine} adds media-related functionality to its superinterface,
* {@code Line}. This functionality includes transport-control methods that
* start, stop, drain, and flush the audio data that passes through the line. A
* data line can also report the current position, volume, and audio format of
* the media. Data lines are used for output of audio by means of the
* subinterfaces {@link SourceDataLine} or {@link Clip}, which allow an
* application program to write data. Similarly, audio input is handled by the
* subinterface {@link TargetDataLine}, which allows data to be read.
* <p>
* A data line has an internal buffer in which the incoming or outgoing audio
* data is queued. The {@link #drain()} method blocks until this internal buffer
* becomes empty, usually because all queued data has been processed. The
* {@link #flush()} method discards any available queued data from the internal
* buffer.
* <p>
* A data line produces {@link LineEvent.Type#START START} and
* {@link LineEvent.Type#STOP STOP} events whenever it begins or ceases active
* presentation or capture of data. These events can be generated in response to
* specific requests, or as a result of less direct state changes. For example,
* if {@link #start()} is called on an inactive data line, and data is available
* for capture or playback, a {@code START} event will be generated shortly,
* when data playback or capture actually begins. Or, if the flow of data to an
* active data line is constricted so that a gap occurs in the presentation of
* data, a {@code STOP} event is generated.
* <p>
* Mixers often support synchronized control of multiple data lines.
* Synchronization can be established through the {@code Mixer} interface's
* {@link Mixer#synchronize synchronize} method. See the description of the
* {@link Mixer Mixer} interface for a more complete description.
*
* @author Kara Kytle
* @see LineEvent
* @since 1.3
*/
public interface DataLine extends Line {
/**
* Drains queued data from the line by continuing data I/O until the data
* line's internal buffer has been emptied. This method blocks until the
* draining is complete. Because this is a blocking method, it should be
* used with care. If {@code drain()} is invoked on a stopped line that has
* data in its queue, the method will block until the line is running and
* the data queue becomes empty. If {@code drain()} is invoked by one
* thread, and another continues to fill the data queue, the operation will
* not complete. This method always returns when the data line is closed.
*
* @see #flush()
*/
void drain();
/**
* Flushes queued data from the line. The flushed data is discarded. In some
* cases, not all queued data can be discarded. For example, a mixer can
* flush data from the buffer for a specific input line, but any unplayed
* data already in the output buffer (the result of the mix) will still be
* played. You can invoke this method after pausing a line (the normal case)
* if you want to skip the "stale" data when you restart playback or
* capture. (It is legal to flush a line that is not stopped, but doing so
* on an active line is likely to cause a discontinuity in the data,
* resulting in a perceptible click.)
*
* @see #stop()
* @see #drain()
*/
void flush();
/**
* Allows a line to engage in data I/O. If invoked on a line that is already
* running, this method does nothing. Unless the data in the buffer has been
* flushed, the line resumes I/O starting with the first frame that was
* unprocessed at the time the line was stopped. When audio capture or
* playback starts, a {@link LineEvent.Type#START START} event is generated.
*
* @see #stop()
* @see #isRunning()
* @see LineEvent
*/
void start();
/**
* Stops the line. A stopped line should cease I/O activity. If the line is
* open and running, however, it should retain the resources required to
* resume activity. A stopped line should retain any audio data in its
* buffer instead of discarding it, so that upon resumption the I/O can
* continue where it left off, if possible. (This doesn't guarantee that
* there will never be discontinuities beyond the current buffer, of course;
* if the stopped condition continues for too long, input or output samples
* might be dropped.) If desired, the retained data can be discarded by
* invoking the {@code flush} method. When audio capture or playback stops,
* a {@link LineEvent.Type#STOP STOP} event is generated.
*
* @see #start()
* @see #isRunning()
* @see #flush()
* @see LineEvent
*/
void stop();
/**
* Indicates whether the line is running. The default is {@code false}. An
* open line begins running when the first data is presented in response to
* an invocation of the {@code start} method, and continues until
* presentation ceases in response to a call to {@code stop} or because
* playback completes.
*
* @return {@code true} if the line is running, otherwise {@code false}
* @see #start()
* @see #stop()
*/
boolean isRunning();
/**
* Indicates whether the line is engaging in active I/O (such as playback or
* capture). When an inactive line becomes active, it sends a
* {@link LineEvent.Type#START START} event to its listeners. Similarly,
* when an active line becomes inactive, it sends a
* {@link LineEvent.Type#STOP STOP} event.
*
* @return {@code true} if the line is actively capturing or rendering
* sound, otherwise {@code false}
* @see #isOpen
* @see #addLineListener
* @see #removeLineListener
* @see LineEvent
* @see LineListener
*/
boolean isActive();
/**
* Obtains the current format (encoding, sample rate, number of channels,
* etc.) of the data line's audio data.
* <p>
* If the line is not open and has never been opened, it returns the default
* format. The default format is an implementation specific audio format,
* or, if the {@code DataLine.Info} object, which was used to retrieve this
* {@code DataLine}, specifies at least one fully qualified audio format,
* the last one will be used as the default format. Opening the line with a
* specific audio format (e.g. {@link SourceDataLine#open(AudioFormat)})
* will override the default format.
*
* @return current audio data format
* @see AudioFormat
*/
AudioFormat getFormat();
/**
* Obtains the maximum number of bytes of data that will fit in the data
* line's internal buffer. For a source data line, this is the size of the
* buffer to which data can be written. For a target data line, it is the
* size of the buffer from which data can be read. Note that the units used
* are bytes, but will always correspond to an integral number of sample
* frames of audio data.
*
* @return the size of the buffer, in bytes
*/
int getBufferSize();
/**
* Obtains the number of bytes of data currently available to the
* application for processing in the data line's internal buffer. For a
* source data line, this is the amount of data that can be written to the
* buffer without blocking. For a target data line, this is the amount of
* data available to be read by the application. For a clip, this value is
* always 0 because the audio data is loaded into the buffer when the clip
* is opened, and persists without modification until the clip is closed.
* <p>
* Note that the units used are bytes, but will always correspond to an
* integral number of sample frames of audio data.
* <p>
* An application is guaranteed that a read or write operation of up to the
* number of bytes returned from {@code available()} will not block;
* however, there is no guarantee that attempts to read or write more data
* will block.
*
* @return the amount of data available, in bytes
*/
int available();
/**
* Obtains the current position in the audio data, in sample frames. The
* frame position measures the number of sample frames captured by, or
* rendered from, the line since it was opened. This return value will wrap
* around after 2^31 frames. It is recommended to use
* {@code getLongFramePosition} instead.
*
* @return the number of frames already processed since the line was opened
* @see #getLongFramePosition()
*/
int getFramePosition();
/**
* Obtains the current position in the audio data, in sample frames. The
* frame position measures the number of sample frames captured by, or
* rendered from, the line since it was opened.
*
* @return the number of frames already processed since the line was opened
* @since 1.5
*/
long getLongFramePosition();
/**
* Obtains the current position in the audio data, in microseconds. The
* microsecond position measures the time corresponding to the number of
* sample frames captured by, or rendered from, the line since it was
* opened. The level of precision is not guaranteed. For example, an
* implementation might calculate the microsecond position from the current
* frame position and the audio sample frame rate. The precision in
* microseconds would then be limited to the number of microseconds per
* sample frame.
*
* @return the number of microseconds of data processed since the line was
* opened
*/
long getMicrosecondPosition();
/**
* Obtains the current volume level for the line. This level is a measure of
* the signal's current amplitude, and should not be confused with the
* current setting of a gain control. The range is from 0.0 (silence) to 1.0
* (maximum possible amplitude for the sound waveform). The units measure
* linear amplitude, not decibels.
*
* @return the current amplitude of the signal in this line, or
* {@link AudioSystem#NOT_SPECIFIED}
*/
float getLevel();
/**
* Besides the class information inherited from its superclass,
* {@code DataLine.Info} provides additional information specific to data
* lines. This information includes:
* <ul>
* <li>the audio formats supported by the data line
* <li>the minimum and maximum sizes of its internal buffer
* </ul>
* Because a {@code Line.Info} knows the class of the line its describes, a
* {@code DataLine.Info} object can describe {@code DataLine} subinterfaces
* such as {@link SourceDataLine}, {@link TargetDataLine}, and {@link Clip}.
* You can query a mixer for lines of any of these types, passing an
* appropriate instance of {@code DataLine.Info} as the argument to a method
* such as {@link Mixer#getLine(Line.Info)}.
*
* @author Kara Kytle
* @see Line.Info
* @since 1.3
*/
class Info extends Line.Info {
/**
* The set of supported formats.
*/
private final AudioFormat[] formats;
/**
* Minimum buffer size supported by the data line, in bytes.
*/
private final int minBufferSize;
/**
* Maximum buffer size supported by the data line, in bytes.
*/
private final int maxBufferSize;
/**
* Constructs a data line's info object from the specified information,
* which includes a set of supported audio formats and a range for the
* buffer size. This constructor is typically used by mixer
* implementations when returning information about a supported line.
*
* @param lineClass the class of the data line described by the info
* object
* @param formats set of formats supported
* @param minBufferSize minimum buffer size supported by the data line,
* in bytes
* @param maxBufferSize maximum buffer size supported by the data line,
* in bytes
*/
public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) {
super(lineClass);
if (formats == null) {
this.formats = new AudioFormat[0];
} else {
this.formats = Arrays.copyOf(formats, formats.length);
}
this.minBufferSize = minBufferSize;
this.maxBufferSize = maxBufferSize;
}
/**
* Constructs a data line's info object from the specified information,
* which includes a single audio format and a desired buffer size. This
* constructor is typically used by an application to describe a desired
* line.
*
* @param lineClass the class of the data line described by the info
* object
* @param format desired format
* @param bufferSize desired buffer size, in bytes
*/
public Info(Class<?> lineClass, AudioFormat format, int bufferSize) {
super(lineClass);
if (format == null) {
this.formats = new AudioFormat[0];
} else {
this.formats = new AudioFormat[]{format};
}
this.minBufferSize = bufferSize;
this.maxBufferSize = bufferSize;
}
/**
* Constructs a data line's info object from the specified information,
* which includes a single audio format. This constructor is typically
* used by an application to describe a desired line.
*
* @param lineClass the class of the data line described by the info
* object
* @param format desired format
*/
public Info(Class<?> lineClass, AudioFormat format) {
this(lineClass, format, AudioSystem.NOT_SPECIFIED);
}
/**
* Obtains a set of audio formats supported by the data line. Note that
* {@code isFormatSupported(AudioFormat)} might return {@code true} for
* certain additional formats that are missing from the set returned by
* {@code getFormats()}. The reverse is not the case:
* {@code isFormatSupported(AudioFormat)} is guaranteed to return
* {@code true} for all formats returned by {@code getFormats()}.
* <p>
* Some fields in the {@code AudioFormat} instances can be set to
* {@link AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} if that field does
* not apply to the format, or if the format supports a wide range of
* values for that field. For example, a multi-channel device supporting
* up to 64 channels, could set the channel field in the
* {@code AudioFormat} instances returned by this method to
* {@code NOT_SPECIFIED}.
*
* @return a set of supported audio formats
* @see #isFormatSupported(AudioFormat)
*/
public AudioFormat[] getFormats() {
return Arrays.copyOf(formats, formats.length);
}
/**
* Indicates whether this data line supports a particular audio format.
* The default implementation of this method simply returns {@code true}
* if the specified format matches any of the supported formats.
*
* @param format the audio format for which support is queried
* @return {@code true} if the format is supported, otherwise
* {@code false}
* @see #getFormats
* @see AudioFormat#matches
*/
public boolean isFormatSupported(AudioFormat format) {
for (int i = 0; i < formats.length; i++) {
if (format.matches(formats[i])) {
return true;
}
}
return false;
}
/**
* Obtains the minimum buffer size supported by the data line.
*
* @return minimum buffer size in bytes, or
* {@code AudioSystem.NOT_SPECIFIED}
*/
public int getMinBufferSize() {
return minBufferSize;
}
/**
* Obtains the maximum buffer size supported by the data line.
*
* @return maximum buffer size in bytes, or
* {@code AudioSystem.NOT_SPECIFIED}
*/
public int getMaxBufferSize() {
return maxBufferSize;
}
/**
* Determines whether the specified info object matches this one. To
* match, the superclass match requirements must be met. In addition,
* this object's minimum buffer size must be at least as large as that
* of the object specified, its maximum buffer size must be at most as
* large as that of the object specified, and all of its formats must
* match formats supported by the object specified.
*
* @param info the info object which is being compared to this one
* @return {@code true} if this object matches the one specified,
* otherwise {@code false}
*/
@Override
public boolean matches(Line.Info info) {
if (! (super.matches(info)) ) {
return false;
}
Info dataLineInfo = (Info)info;
// treat anything < 0 as NOT_SPECIFIED
// demo code in old Java Sound Demo used a wrong buffer calculation
/**代码未完, 请加载全部代码(NowJava.com).**/