/*
 * @(#)Processor.java	1.25 02/08/21
 *
 * Copyright (c) 1996-2002 Sun Microsystems, Inc.  All rights reserved.
 */

package javax.media;

import javax.media.format.*;
import javax.media.protocol.*;
import javax.media.control.TrackControl;

/**
 * The <code>Processor</code> interface defines a module for processing 
 * and controlling time-based media data.
 * <code>Processor</code> extends the <code>Player</code> interface.
 *
 * Unlike a <code>Player</code>, which processes data as a "black box" and
 * only renders data to preset destinations, a <code>Processor</code> 
 * supports a programmatic interface that enables control over the media data processing
 * and access to output data streams. 
 * <p>
 * The processing performed by a <code>Processor</code> is split into
 * three stages:
 * <ul>
 * <li> Demultiplexing -
 *    an interleaved media stream is first demultiplexed into separate tracks of
 *    data streams that can be processed individually.
 * <li> Data transcoding -
 *    each track of data can be transcoded from one format to another.
 * <li> Multiplexing -
 *    the separate tracks can be multiplexed to form
 *    an interleaved stream of a particular container content type. 
 * </ul>
 * <p>
 * Both the data transcoding and multiplexing processes are programmable. 
 *
 * <h2>How a <code>Processor</code> Differs from a <code>Controller</code></h2>
 *
 * <code>Processor</code> extends the state transition cycle of a
 * <code>Controller</code> by adding the <i>Configuring</i> and
 * <i>Configured</i> states.
 * The purpose of these additional states is to further refine
 * the realizing process.  The
 * realizing step is essentially split into two phases: 
 * <ul>
 * <li> Source information gathering -
 * 	the input <code>DataSource</code> is queried and the input media 
 *	stream is parsed to get the format information for the tracks in the stream.
 * <li> Construction -
 *	the internals of the <code>Processor</code> are constructed to handle
 * 	the input media stream.
 * </ul>
 * <p>
 * Between these two steps, you can 
 * program the <code>Processor</code> to perform specific 
 * processing on its media stream.
 * <p>
 * The states of a <code>Processor</code> are:
 * <i>Unrealized,</i> <i>Configuring,</i> <i>Configured,</i>
 * <i>Realizing,</i> <i>Realized,</i> <i>Prefetching,</i>
 * <i>Prefetched,</i> and <i>Started</i>.
 *
 * <h3>The <i>Configuring</i> and <i>Configured</i> States</h3>
 * <p>
 * While it's in the <code>Configuring</code> state, a <code>Processor</code>
 * gathers the source information necessary to prepare the <code>Processor</code> to be programmed.
 * This might involve parsing an input file to access the individual
 * media tracks within the file, or connecting to a capturing device
 * to determine its capabilities.  A <code>ConfigureCompleteEvent</code>
 * is posted when the <code>Processor</code> reaches <i>Configured</i> state.
 * <p>
 * Once a <code>Processor</code> is <i>Configured,</i> you can program
 * it to perform particular processing on each track or to output data in a particular
 * format.
 *
 * <h3>Realizing a <code>Processor</code></h3>
 * <p>
 * When you're done programming the <code>Processor</code>, you call the <code>realize</code>
 * method to complete its construction.
 * <p>
 * Once the <code>Processor</code> is in the <i>Realized</i> state, reprogramming 
 * the <code>Processor</code> by calling the <code>TrackControl</code> methods or 
 * the <code>setContentDescriptor</code> method is not guaranteed
 * to work. This is because reprogramming the <code>Processor</code> might require reconstruction 
 * of its internals.
 * <p>
 * It is legal to call <code>realize</code> on a <code>Processor</code> while it 
 * is in the <i>Unrealized</i> state.  
 * This causes the <code>Processor</code> to transition from the
 * <i>Unrealized</i> state to the <i>Realized</i> state. As it does this, it goes through each
 * intermediate state: <code>Configuring</code>, <code>Configured</code>, and
 * <code>Realizing</code>.  However, when you directly realize a <code>Processor</code>, you miss the
 * opportunity to program it while it's in the 
 * <i>Configured</i> state--the <code>Processor</code> performs whatever default processing its 
 * implementation specifies.  
 *
 * <h3>Deallocating a <code>Processor</code></h3>
 * <p>
 * Calling <code>deallocate</code> changes the state of a <code>Processor</code>
 * in the same way as a <code>Controller</code> <b>except</b> that
 * if <code>deallocate</code> is called while the <code>Processor</code> 
 * is in the <i>Configuring</i> or
 * <i>Configured</i> state, the
 * <code>Processor</code> is returned to the <i>Unrealized</i> state. 
 *
 * <h2>Programming a <code>Processor</code></h2>
 * <p>
 * You can control both the transcoding and multiplexing performed by a <code>Processor</code>.  
 * Data transcoding is controlled separately for each track.
 * The <code>getTrackControls</code> method 
 * returns a <code>TrackControl</code> for each track. You use these
 * <code>TrackControl</code> objects to specify what processing you want to perform.
 * The multiplexing performed by a <code>Processor</code> is controlled by specifying 
 * the format that you want it to output. This is done through 
 * the <code>setContentDescriptor</code> method.
 * <p>
 * A <code>Processor</code> can be programmed while it is in the
 * <i>Configured</i> state.  A <code>NotConfiguredError</code> is thrown
 * if you attempt to program the <code>Processor</code> before
 * is configured.
 * <p>
 * If you do not program a <code>Processor</code> through the
 * <code>TrackControl</code> methods or by calling <code>setContentDescriptor</code>, 
 * it performs whatever default processing is specified by its implementation.
 *
 * <h2>Getting the Output from a <code>Processor</code></h2>
 * <p>
 * The processed output data streams can be retrieved from a <code>Processor</code> 
 * through its output <code>DataSource</code>.  The output 
 * <code>DataSource</code> provides the gateway for the output data to 
 * be read.  A <code>DataSource</code> output from a <code>Processor</code> 
 * can be a <code>PushDataSource</code>, <code>PushBufferDataSource</code>, 
 * <code>PullDataSource</code>, or <code>PullBufferDataSource</code> depending 
 * on the implementation of the <code>Processor</code>.
 * <p>
 * A <code>NotRealizedError</code> is thrown if 
 * <code>getDataOutput</code> is called on a <code>Processor</code>
 * that has not yet been realized.
 *
 *
 * <h2>Using a <code>Processor</code> as a <code>Player</code></h2>
 *
 * Many <code>Processor</code> implementations can be used like a
 * <code>Player</code> to render media data instead of sending it to an
 * output <code>DataSource</code>.  In this case, the <code>TrackControl</code> objects
 * provide additional information and control over the individual 
 * tracks to be rendered.  When used as a <code>Player</code>, a <code>Processor</code> 
 * does not produce an output <code>DataSource</code>.
 * To use a <code>Processor</code> as a <code>Player</code>, you call
 * <code>setContentDescriptor(null)</code>. 
 *
 * @see Controller
 * @see Player
 * @see TrackControl
 * @since JMF 2.0
 */

public interface Processor extends Player {

    /**
     * Returned by <code>getState</code>.
     */
    public final static int Configuring = 140;

    /**
     * Returned by <code>getState</code>.
     */
    public final static int Configured = 180;


    /**
     * Prepares the <code>Processor</code> to be programmed. The <code>Processor</code> 
     * gathers information about the data it is going to process.
     * Calling <code>configure</code> puts the <code>Processor</code> 
     * into the <i>Configuring</i> state and returns immediately. 
     * When this process is complete and the 
     * <code>Processor</code> is in the <i>Configured</i> state, 
     * the <code>Processor</code> posts a <code>ConfigureCompleteEvent</code>. 
     */
    public void configure();
    
    /**
     * Gets a <code>TrackControl</code> for each track in the media stream. 
     * This method can only be called once 
     * the <code>Processor</code> has been configured. 
     *
     * @return  An array of <code>TrackControl</code> objects.  An empty array is returned
     *   if there is no <code>TrackControl</code> available for this 
     * <code>Processor</code>.
     * @exception NotConfiguredError  If the <code>Processor</code> is in the <i>Unrealized</i> or 
     * <i>Configuring</i> state. 
     */
    public TrackControl[] getTrackControls() throws NotConfiguredError;

    /** 
     * Gets all of the content types that this <code>Processor</code>  
     * can output. The <code>Processor</code> builds the 
     * <code>ContentDescriptor</code> array according to its input 
     * <code>DataSource</code> and
     * the available codecs and multiplexers.
     *
     * @return  An array of the content types supported by this 
     * <code>Processor</code>.
     * @exception NotConfiguredError If the <code>Processor</code> is in the <i>Unrealized</i> or 
     * <i>Configuring</i> state. 
     */
    public ContentDescriptor[] getSupportedContentDescriptors() throws NotConfiguredError;
    
    /**
     * Sets the output content-type for this <code>Processor</code>.
     * If <code>setContentDescriptor</code> is not called, the output 
     * <code>DataSource</code> is set to raw output by default:
     * <code>(new ContentDescriptor(ContentDescriptor.RAW))</code>.  The source streams
     * from the <code>DataSource</code> are the demultiplexed tracks
     * from the input source.
     *
     * @return The content descriptor that most closely matches the specified content 
     * descriptor or null if the specified content descriptor cannot be set.
     * @param outputContentDescriptor  The content type to be used for the <code>Processor</code> output.
     * @exception NotConfiguredError If the <code>Processor</code> is in the <i>Unrealized</i> or 
     * <i>Configuring</i> state. 
     */
    public ContentDescriptor setContentDescriptor(ContentDescriptor outputContentDescriptor) throws NotConfiguredError ;
    
    /**
     * Gets the output content-type currently set for this <code>Processor</code>.
     *
     * @return  The current output content-type.
     * @exception NotConfiguredError If the <code>Processor</code> is in the <i>Unrealized</i> or 
     * <i>Configuring</i> state. 
     */
    public ContentDescriptor getContentDescriptor() throws NotConfiguredError;
    
    /** 
     * Gets the output <code>DataSource</code> from the <code>Processor</code>. The 
     * output <code>DataSource</code> is the output connection through which the processed 
     * streams are supplied. The output <code>DataSource</code> returned by the <code>Processor</code> is  
     * in the <i>Connected</I> state.
     * @exception NotRealizedError If the <code>Processor</code> is has not yet been 
     * realized.
     */
    public DataSource getDataOutput() throws NotRealizedError;
    
}