/*
* @(#)Codec.java 1.13 02/08/21
*
* Copyright (c) 1996-2002 Sun Microsystems, Inc. All rights reserved.
*/
package javax.media;
import javax.media.*;
import javax.media.format.*;
/**
* A <code>Codec</code> is a media processing unit that accepts a <code>Buffer</code>
* object as its input, performs some processing on the input data, and then puts the
* result in an output <code>Buffer</code> object. It has one input and one output.
* Typical examples of codecs include audio decoders, video encoders, and effects.
*
* <p>
* A codec usually works in one of the following modes:
* <ul>
*
* <li>Frame based mode. In this mode, the codec accepts one frame of data from its input
* and converts it to one frame of output data.
* The codec must consume its input <code>Buffer</code> and generate
* an output <code>Buffer</code>.
* <p>
* This mode is useful when the codec can handle any size of input. A
* simple gain codec fits this model: it multiplies each
* sample with the gain factor and puts the product in an output <code>Buffer</code>.
* Another scenario where this mode is useful is when the codec can only process
* data that's in a fixed, pre-determined frame size
* and the input <code>Buffer</code> is already packetized accordingly.
* One example of such a codec is a GSM audio decoder, which accepts a compressed
* GSM audio packet from an RTP depacketizer, decodes the packet, and then puts the result in
* an output <code>Buffer</code>. <br> </li>
*
* <li>Stream based mode. In this mode, the codec accepts chunks of data from its input and
* might generate an output <code>Buffer</code>.
* The codec might consume only part of the input <code>Buffer</code> each time its <code>process</code>
* method is called and might not generate an output <code>Buffer</code> during each round of processing.
* This mode is useful in stream packetizers, which accept a stream of bytes and divide the stream
* into packets (frames) that are used in the next processing phase.
* Another scenario where this mode is useful is when two audio processing units that have
* incompatible frame sizes need to be chained.
* </li>
* </ul>
* <p>
* Some restrictions apply to the processing a <code>Codec</code> can perform on its input
* and output <code>Buffer</code> objects:
* <ul>
* <li> The <code>Codec</code> might receive an output <code>Buffer</code> that is not big enough to hold its output data.
* In this case, the <code>Codec</code> should allocate a new <code>Buffer</code> for its output data. <br> </li>
*
* <li> The <code>Codec</code> cannot cache references to <code>Buffer</code> object fields.
* It must read all of the parameters from the input and output <code>Buffer</code> objects each time
* its <code>process</code> method is called. <br> </li>
*
* <li> If the <code>Codec</code> needs to keep references to a <code>Buffer</code> object's data (for performance reasons),
* the <code>Codec</code> must assign other data to the input <code>Buffer</code> object by calling <code>setData</code>
* before returning from the <code>process</code> method.
* The data assigned can be null, but it is better to assign
* some unneeded data to the <code>Buffer</code>, such as input data received earlier.
* Such manipulations can be used for in-place processing (where the output of the processing
* is put in the same location as input data in order to enhance memory utilization) or for codecs
* that need access to more than one frame of data without copying the data (for example, temporal video effects).
* </li>
* </ul>
* @since JMF 2.0
**/
public interface Codec extends javax.media.PlugIn {
/**
* Lists all of the input formats that this codec accepts.
* @return An array that contains the supported input <code>Formats</code>.
*/
public Format [] getSupportedInputFormats();
/**
* Lists the output formats that this codec can generate.
* If <code>input</code> is non-null, this method lists the possible
* output formats that can be generated from input data of the specified <code>Format</code>.
* If <code>input</code> is null, this method lists
* all of the output formats supported by this plug-in.
* @param input The <code>Format</code> of the data to be used as input to the plug-in.
* @return An array that contains the supported output <code>Formats</code>.
*/
public Format [] getSupportedOutputFormats(Format input);
/**
* Sets the format of the data to be input to this codec.
* @param format The <code>Format</code> to be set.
* @return The <code>Format</code> that was set, which might be the
* supported <code>Format</code> that most closely matches the one specified.
* Returns null if the specified <code>Format</code> is not supported and
* no reasonable match could be found.
*/
public Format setInputFormat(Format format);
/**
* Sets the format for the data this codec outputs.
* @param format The <code>Format</code> to be set.
* @return The <code>Format</code> that was set, which might be the
* <code>Format</code> that most closely matched the one specified.
* Returns null if the specified <code>Format</code> is not supported and
* no reasonable match could be found.
*/
public Format setOutputFormat(Format format);
/**
* Performs the media processing defined by this codec.
* @param input The <code>Buffer</code> that contains the media data to be processed.
* @param output The <code>Buffer</code> in which to store the processed media data.
* @return <CODE>BUFFER_PROCESSED_OK</CODE> if the processing is successful. Other
* possible return codes are defined in <CODE>PlugIn</CODE>.
* @see PlugIn
*/
public int process(Buffer input, Buffer output);
}
|