javax.media
Interface Processor


public interface Processor
extends Player

The Processor interface defines a module for processing and controlling time-based media data. Processor extends the Player interface. Unlike a Player, which processes data as a "black box" and only renders data to preset destinations, a Processor supports a programmatic interface that enables control over the media data processing and access to output data streams.

The processing performed by a Processor is split into three stages:

Both the data transcoding and multiplexing processes are programmable.

How a Processor Differs from a Controller

Processor extends the state transition cycle of a Controller by adding the Configuring and Configured states. The purpose of these additional states is to further refine the realizing process. The realizing step is essentially split into two phases:

Between these two steps, you can program the Processor to perform specific processing on its media stream.

The states of a Processor are: Unrealized, Configuring, Configured, Realizing, Realized, Prefetching, Prefetched, and Started.

The Configuring and Configured States

While it's in the Configuring state, a Processor gathers the source information necessary to prepare the Processor 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 ConfigureCompleteEvent is posted when the Processor reaches Configured state.

Once a Processor is Configured, you can program it to perform particular processing on each track or to output data in a particular format.

Realizing a Processor

When you're done programming the Processor, you call the realize method to complete its construction.

Once the Processor is in the Realized state, reprogramming the Processor by calling the TrackControl methods or the setContentDescriptor method is not guaranteed to work. This is because reprogramming the Processor might require reconstruction of its internals.

It is legal to call realize on a Processor while it is in the Unrealized state. This causes the Processor to transition from the Unrealized state to the Realized state. As it does this, it goes through each intermediate state: Configuring, Configured, and Realizing. However, when you directly realize a Processor, you miss the opportunity to program it while it's in the Configured state--the Processor performs whatever default processing its implementation specifies.

Deallocating a Processor

Calling deallocate changes the state of a Processor in the same way as a Controller except that if deallocate is called while the Processor is in the Configuring or Configured state, the Processor is returned to the Unrealized state.

Programming a Processor

You can control both the transcoding and multiplexing performed by a Processor. Data transcoding is controlled separately for each track. The getTrackControls method returns a TrackControl for each track. You use these TrackControl objects to specify what processing you want to perform. The multiplexing performed by a Processor is controlled by specifying the format that you want it to output. This is done through the setContentDescriptor method.

A Processor can be programmed while it is in the Configured state. A NotConfiguredError is thrown if you attempt to program the Processor before is configured.

If you do not program a Processor through the TrackControl methods or by calling setContentDescriptor, it performs whatever default processing is specified by its implementation.

Getting the Output from a Processor

The processed output data streams can be retrieved from a Processor through its output DataSource. The output DataSource provides the gateway for the output data to be read. A DataSource output from a Processor can be a PushDataSource, PushBufferDataSource, PullDataSource, or PullBufferDataSource depending on the implementation of the Processor.

A NotRealizedError is thrown if getDataOutput is called on a Processor that has not yet been realized.

Using a Processor as a Player

Many Processor implementations can be used like a Player to render media data instead of sending it to an output DataSource. In this case, the TrackControl objects provide additional information and control over the individual tracks to be rendered. When used as a Player, a Processor does not produce an output DataSource. To use a Processor as a Player, you call setContentDescriptor(null).

Since:
JMF 2.0
See Also:
Controller, Player, TrackControl

Field Summary
static int Configured
          Returned by getState.
static int Configuring
          Returned by getState.
 
Fields inherited from interface javax.media.Controller
LATENCY_UNKNOWN, Prefetched, Prefetching, Realized, Realizing, Started, Unrealized
 
Fields inherited from interface javax.media.Clock
RESET
 
Fields inherited from interface javax.media.Duration
DURATION_UNBOUNDED, DURATION_UNKNOWN
 
Method Summary
 void configure()
          Prepares the Processor to be programmed.
 ContentDescriptor getContentDescriptor()
          Gets the output content-type currently set for this Processor.
 DataSource getDataOutput()
          Gets the output DataSource from the Processor.
 ContentDescriptor[] getSupportedContentDescriptors()
          Gets all of the content types that this Processor can output.
 TrackControl[] getTrackControls()
          Gets a TrackControl for each track in the media stream.
 ContentDescriptor setContentDescriptor(ContentDescriptor outputContentDescriptor)
          Sets the output content-type for this Processor.
 
Methods inherited from interface javax.media.Player
addController, getControlPanelComponent, getGainControl, getVisualComponent, removeController, start
 
Methods inherited from interface javax.media.MediaHandler
setSource
 
Methods inherited from interface javax.media.Controller
addControllerListener, close, deallocate, getControl, getControls, getStartLatency, getState, getTargetState, prefetch, realize, removeControllerListener
 
Methods inherited from interface javax.media.Clock
getMediaNanoseconds, getMediaTime, getRate, getStopTime, getSyncTime, getTimeBase, mapToTimeBase, setMediaTime, setRate, setStopTime, setTimeBase, stop, syncStart
 
Methods inherited from interface javax.media.Duration
getDuration
 

Field Detail

Configuring

public static final int Configuring
Returned by getState.

Configured

public static final int Configured
Returned by getState.
Method Detail

configure

public void configure()
Prepares the Processor to be programmed. The Processor gathers information about the data it is going to process. Calling configure puts the Processor into the Configuring state and returns immediately. When this process is complete and the Processor is in the Configured state, the Processor posts a ConfigureCompleteEvent.

getTrackControls

public TrackControl[] getTrackControls()
                                throws NotConfiguredError
Gets a TrackControl for each track in the media stream. This method can only be called once the Processor has been configured.
Returns:
An array of TrackControl objects. An empty array is returned if there is no TrackControl available for this Processor.
Throws:
NotConfiguredError - If the Processor is in the Unrealized or Configuring state.

getSupportedContentDescriptors

public ContentDescriptor[] getSupportedContentDescriptors()
                                                   throws NotConfiguredError
Gets all of the content types that this Processor can output. The Processor builds the ContentDescriptor array according to its input DataSource and the available codecs and multiplexers.
Returns:
An array of the content types supported by this Processor.
Throws:
NotConfiguredError - If the Processor is in the Unrealized or Configuring state.

setContentDescriptor

public ContentDescriptor setContentDescriptor(ContentDescriptor outputContentDescriptor)
                                       throws NotConfiguredError
Sets the output content-type for this Processor. If setContentDescriptor is not called, the output DataSource is set to raw output by default: (new ContentDescriptor(ContentDescriptor.RAW)). The source streams from the DataSource are the demultiplexed tracks from the input source.
Parameters:
outputContentDescriptor - The content type to be used for the Processor output.
Returns:
The content descriptor that most closely matches the specified content descriptor or null if the specified content descriptor cannot be set.
Throws:
NotConfiguredError - If the Processor is in the Unrealized or Configuring state.

getContentDescriptor

public ContentDescriptor getContentDescriptor()
                                       throws NotConfiguredError
Gets the output content-type currently set for this Processor.
Returns:
The current output content-type.
Throws:
NotConfiguredError - If the Processor is in the Unrealized or Configuring state.

getDataOutput

public DataSource getDataOutput()
                         throws NotRealizedError
Gets the output DataSource from the Processor. The output DataSource is the output connection through which the processed streams are supplied. The output DataSource returned by the Processor is in the Connected state.
Throws:
NotRealizedError - If the Processor is has not yet been realized.


Submit a bug or feature
Copyright 1999-2000 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. See the Specification License for more details.
Sun, Sun Microsystems, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.