com.sun.dtv.ui
Class PlaneSetupPattern

java.lang.Object
  com.sun.dtv.ui.PlaneSetupPattern

public class PlaneSetupPattern
extends Object

This class is a means to describe the setup of a screen plane by specifying various properties and their importance to the application. It is used to request a valid instance of a setup conforming to the provided description. Sub-classes of this class define additional properties. Those classes can be sub-classed in order to add further properties if needed.

In case of conflicting preferences between PlaneSetupPatterns the following rules will apply:

• In case all conflicting preferences have priority PREFERRED, PREFERRED_NOT or DONT_CARE, the conflicting preferences shall be discarded from the pattern.
• In case all the conflicting preferences have priority REQUIRED or REQUIRED_NOT, the method call fails.
• In all other cases, as much preferences with priority PREFERRED, PREFERRED_NOT or DONT_CARE as necessary shall be discarded. If there is still a conflict after this, the method fails.

Several preferences in this class are required to be not filled into platform-generated patterns.

Field Summary

static int	CHANGEABLE_SINGLE_COLOR A preference value for use in the setPreference(int, int) and getPriority(int) methods in the PlaneSetupPattern.
static int	DIRECT_COLOR_SUPPORT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	DONT_CARE A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	FLICKER_FILTERING A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	GRAPHICS_MIXING A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	IMAGE_SCALING_SUPPORT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	INDEXED_COLOR_SUPPORT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	INTERLACED_DISPLAY A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	MATTE_SUPPORT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	NO_BACKGROUND_IMPACT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	NO_GRAPHICS_IMPACT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	NO_STILLVIDEO_IMPACT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	NO_SUBTITLE_IMPACT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	NO_VIDEO_IMPACT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	PIXEL_ASPECT_RATIO A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	PIXEL_RESOLUTION A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	PREFERRED A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	PREFERRED_NOT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	REQUIRED A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	REQUIRED_NOT A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	STILL_IMAGE A preference value for use in the setPreference(int, int) and getPriority(int) methods in the PlaneSetupPattern.
static int	VIDEO_GRAPHICS_PIXEL_ALIGNED A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.
static int	VIDEO_MIXING A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern.

Constructor Summary

PlaneSetupPattern()

Method Summary

Object	getPreferenceValue(int preference) Returns the preference value for the specified preference.
int	getPriority(int preference) Return the priority for the specified preference.
boolean	isSetupFitting(PlaneSetup setup) Informs whether or not the specified PlaneSetup can be used to create a plane that supports the features set in this pattern.
void	setPreference(int preference, int priority) Set the indicated preference to have the specified priority.
void	setPreference(int preference, Object value, int priority) Sets the indicated preference to have the specified value with the specified priority.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REQUIRED

public static final int REQUIRED

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that this feature is required in the PlaneSetup. If this feature is not available, the PlaneSetup object won't be selected.

See Also:

Constant Field Values

PREFERRED

public static final int PREFERRED

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that this feature is desired in the PlaneSetup. A selection with this feature is preferred over a selection that does not include this feature, although both selections are valid matches.

See Also:

Constant Field Values

DONT_CARE

public static final int DONT_CARE

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the presence or absence of this feature in the PlaneSetup does not matter. Preferences with this priority do not influence the selection result.

See Also:

Constant Field Values

PREFERRED_NOT

public static final int PREFERRED_NOT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that this feature is desired not to be present in the PlaneSetup. A selection without this feature is preferred over a selection that does include this feature, although both selections are valid matches.

See Also:

Constant Field Values

REQUIRED_NOT

public static final int REQUIRED_NOT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that this feature is required not to be present in the PlaneSetup. If this feature is available, the PlaneSetup object won't be selected.

See Also:

Constant Field Values

NO_BACKGROUND_IMPACT

public static final int NO_BACKGROUND_IMPACT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup should have no impact on already displayed backgrounds.

If used with the REQUIRED priority, this means there must not be any changes. If used with the PREFERRED priority, this means changes may be made but should be minimized.

The PREFERRED_NOT and REQUIRED_NOT priorities can be ignored in the selection of an PlaneSetup for this preference type.

This preference is used by the platform as a constraint in selecting setups. Patterns generated by the platform and then returned to applications (e.g. from a getSetupPattern method) shall not have this preference filled in by the platform.

See Also:

Constant Field Values

NO_GRAPHICS_IMPACT

public static final int NO_GRAPHICS_IMPACT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup should have no impact on already running graphical applications.

If used with the REQUIRED priority, this means there must not be any changes. If used with the PREFERRED priority, this means changes may be made but should be minimized.

The PREFERRED_NOT and REQUIRED_NOT priorities can be ignored in the selection of an PlaneSetup for this preference type.

This preference is used by the platform as a constraint in selecting setups. Patterns generated by the platform and then returned to applications (e.g. from a getSetupPattern method) shall not have this preference filled in by the platform.

See Also:

Constant Field Values

NO_SUBTITLE_IMPACT

public static final int NO_SUBTITLE_IMPACT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup should have no impact on already running subtitle applications.

If used with the REQUIRED priority, this means there must not be any changes. If used with the PREFERRED priority, this means changes may be made but should be minimized.

The PREFERRED_NOT and REQUIRED_NOT priorities can be ignored in the selection of an PlaneSetup for this preference type.

This preference is used by the platform as a constraint in selecting setups. Patterns generated by the platform and then returned to applications (e.g. from a getSetupPattern method) shall not have this preference filled in by the platform.

See Also:

Constant Field Values

NO_VIDEO_IMPACT

public static final int NO_VIDEO_IMPACT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup should have no impact on already running video streams. This does also include video stills.

If used with the REQUIRED priority, this means there must not be any changes. If used with the PREFERRED priority, this means changes may be made but should be minimized.

The PREFERRED_NOT and REQUIRED_NOT priorities can be ignored in the selection of an PlaneSetup for this preference type.

This preference is used by the platform as a constraint in selecting setups. Patterns generated by the platform and then returned to applications (e.g. from a getSetupPattern method) shall not have this preference filled in by the platform.

See Also:

Constant Field Values

NO_STILLVIDEO_IMPACT

public static final int NO_STILLVIDEO_IMPACT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup should have no impact on already displayed videos stills. This does not include video streams in general.

If used with the REQUIRED priority, this means there must not be any changes. If used with the PREFERRED priority, this means changes may be made but should be minimized.

The PREFERRED_NOT and REQUIRED_NOT priorities can be ignored in the selection of an PlaneSetup for this preference type.

This preference is used by the platform as a constraint in selecting setups. Patterns generated by the platform and then returned to applications (e.g. from a getSetupPattern method) shall not have this preference filled in by the platform.

See Also:

Constant Field Values

INTERLACED_DISPLAY

public static final int INTERLACED_DISPLAY

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup supports an interlaced display.

See Also:

Constant Field Values

FLICKER_FILTERING

public static final int FLICKER_FILTERING

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup supports flicker filtering (if it supports an interlaced screen).

See Also:

Constant Field Values

VIDEO_GRAPHICS_PIXEL_ALIGNED

public static final int VIDEO_GRAPHICS_PIXEL_ALIGNED

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup supports the display of video streams and graphics with aligned pixels of the same size. This does not include alignment of the origins of the two pixel coordinate spaces. Where a video plane is moving the video relative to the screen in real time (e.g. implementing pan and scan), graphics setups shall only support this feature where the implementation of the GraphicsPlane can track the position changes in the VideoPlane automatically.

This preference is used by the platform as a constraint in selecting setups. Patterns generated by the platform and then returned to applications (e.g. from a getSetupPattern method) shall not have this preference filled in by the platform.

See Also:

Constant Field Values

PIXEL_ASPECT_RATIO

public static final int PIXEL_ASPECT_RATIO

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup supports the pixel aspect ratio, as specified in a com.sun.dtv.lwuit.geom.Dimension object which indicates the (relative) x, y pixel aspect ratio.

Instances of PlaneSetupPattern generated by the platform and returned to applications (e.g. from a getPattern method ) shall have this preference set to a platform specific value with the REQUIRED priority.

See Also:

Constant Field Values

PIXEL_RESOLUTION

public static final int PIXEL_RESOLUTION

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup supports the pixel resolution, as specified in a com.sun.dtv.lwuit.geom.Dimension object which indicates the pixel resolution of the GraphicsPlane.

Instances of PlaneSetupPattern generated by the platform and returned to applications (e.g. from a getPattern method ) shall have this preference set to a platform specific value with the REQUIRED priority.

See Also:

Constant Field Values

CHANGEABLE_SINGLE_COLOR

public static final int CHANGEABLE_SINGLE_COLOR

A preference value for use in the setPreference(int, int) and getPriority(int) methods in the PlaneSetupPattern. It indicates that a single color background is requested, where that single color can be changed by applications.

See Also:

Constant Field Values

STILL_IMAGE

public static final int STILL_IMAGE

A preference value for use in the setPreference(int, int) and getPriority(int) methods in the PlaneSetupPattern. It indicates that a background is requested which can support still images.

See Also:

Constant Field Values

VIDEO_MIXING

public static final int VIDEO_MIXING

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the setup should support transparency in the graphics system such that the output of a video decoder is visible. (This includes also video stills.) The following setups fulfill this requirement:

• Setups with a well defined transformation between video / still video pixels and graphics pixels (e.g. pixels are the same size).
• Setups where an application displays graphics over video / still video, while the video / still video is used as a background. Therefore there is no transformation required between the two sets of pixels in such kind of setups.

Applications may specify a particular video / still video setup with which mixing must be supported. In cases where no specific video setup is required then it is not required to specify such a setup and null can be used instead.

This preference is used by the platform as a constraint in selecting setups. Patterns generated by the platform and then returned to applications (e.g. from a getSetupPattern method) shall not have this preference filled in by the platform.

See Also:

Constant Field Values

GRAPHICS_MIXING

public static final int GRAPHICS_MIXING

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the plane setup supports the display of graphics in addition to video streams. The screen then includes planes associated with both kinds of setups where the video pixels and graphics pixels are fully aligned (same size) as well as setups where they are displayed together but where a more complex relationship exists between the two pixel coordinate spaces.

This preference is used by the platform as a constraint in selecting setups. Patterns generated by the platform and then returned to applications (e.g. from a getSetupPattern method) shall not have this preference filled in by the platform.

See Also:

Constant Field Values

MATTE_SUPPORT

public static final int MATTE_SUPPORT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the setup should support the mattes feature.

See Also:

Constant Field Values

IMAGE_SCALING_SUPPORT

public static final int IMAGE_SCALING_SUPPORT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the setup should support rapid image scaling.

See Also:

Constant Field Values

INDEXED_COLOR_SUPPORT

public static final int INDEXED_COLOR_SUPPORT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the graphics setup should support a Color Lookup Table.

See Also:

Constant Field Values

DIRECT_COLOR_SUPPORT

public static final int DIRECT_COLOR_SUPPORT

A preference value for use in the setPreference and getPriority methods in the PlaneSetupPattern. It indicates that the graphics setup should support Direct Color.

See Also:

Constant Field Values

Constructor Detail

PlaneSetupPattern

public PlaneSetupPattern()

Method Detail

setPreference

public void setPreference(int preference,
                          int priority)
                   throws IllegalArgumentException

Set the indicated preference to have the specified priority. If the preference has been previously set, the previous priority for this preference will be overwritten.

Attributes that are not filled in in a pattern (through setPreference(int, int)), shall have the priority DONT_CARE. Any setup always satisfies these attributes.

Parameters:

preference - the preference to be indicated. Valid values for an PlaneSetupPattern are: NO_GRAPHICS_IMPACT, NO_SUBTITLE_IMPACT, NO_BACKGROUND_IMPACT, NO_VIDEO_IMPACT, NO_STILLVIDEO_IMPACT, INTERLACED_DISPLAY, FLICKER_FILTERING, VIDEO_GRAPHICS_PIXEL_ALIGNED, CHANGEABLE_SINGLE_COLOR, STILL_IMAGE, VIDEO_MIXING, GRAPHICS_MIXING, MATTE_SUPPORT, IMAGE_SCALING_SUPPORT, INDEXED_COLOR_SUPPORT, and DIRECT_COLOR_SUPPORT.

Subclasses may add further valid values. An IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of PlaneSetupPattern

priority - the priority of the preference. Valid values are: REQUIRED, PREFERRED, DONT_CARE, PREFERRED_NOT and REQUIRED_NOT.

If priority is not a valid priority as defined here a java.lang.IllegalArgumentException will be thrown.

Throws:

IllegalArgumentException - if the preference or the priority parameter does not have a valid value

setPreference

public void setPreference(int preference,
                          Object value,
                          int priority)
                   throws IllegalArgumentException

Sets the indicated preference to have the specified value with the specified priority. A call to this method can be also used to overwrite values and priorities of previously set preferences.

Parameters:

preference - the preference to to be indicated. Valid values are PIXEL_ASPECT_RATIO, and PIXEL_RESOLUTION.

value - the value to be set for the indicated preference

priority - the priority of the indicated preference. Valid values are: REQUIRED, PREFERRED, DONT_CARE, PREFERRED_NOT and REQUIRED_NOT.

Throws:

IllegalArgumentException - if any of the parameters has an unappropriate value

getPreferenceValue

public Object getPreferenceValue(int preference)
                          throws IllegalArgumentException

Returns the preference value for the specified preference.

Parameters:

preference - the preference for which the value should be retrieved. Valid values are PIXEL_ASPECT_RATIO, and PIXEL_RESOLUTION.

Returns:

the currently valid value for the specified preference. This should be a java.awt.Dimension object

Throws:

IllegalArgumentException - if the paramter has an unappropriate value

getPriority

public int getPriority(int preference)
                throws IllegalArgumentException

Return the priority for the specified preference.

Individual properties in the PlaneSetupPattern can then be examined using the getPriority method. Implemented features will return REQUIRED, not implemented features will return REQUIRED_NOT.

Parameters:

preference - the preference to be indicated. Valid values for an PlaneSetupPattern are: NO_GRAPHICS_IMPACT, NO_SUBTITLE_IMPACT, NO_BACKGROUND_IMPACT, NO_VIDEO_IMPACT, NO_STILLVIDEO_IMPACT, INTERLACED_DISPLAY, FLICKER_FILTERING, VIDEO_GRAPHICS_PIXEL_ALIGNED, CHANGEABLE_SINGLE_COLOR, STILL_IMAGE, VIDEO_MIXING, GRAPHICS_MIXING, MATTE_SUPPORT, IMAGE_SCALING_SUPPORT, INDEXED_COLOR_SUPPORT, DIRECT_COLOR_SUPPORT, PIXEL_ASPECT_RATIO, and PIXEL_RESOLUTION.

Subclasses may add further valid values. An IllegalArgumentException shall be thrown if the preference is not a valid value for this instance of PlaneSetupPattern

Returns:

the priority for the specified preference.

Throws:

IllegalArgumentException - if the preference parameter does not have a valid value

isSetupFitting

public boolean isSetupFitting(PlaneSetup setup)

Informs whether or not the specified PlaneSetup can be used to create a plane that supports the features set in this pattern.

Parameters:

setup - - the PlaneSetup object to be tested against this pattern.

Returns:

true if this PlaneSetup object can be used to create a plane that supports the feature set in this pattern, false otherwise.