javax.microedition.amms.control
Interface EffectControl

All Superinterfaces:

javax.microedition.media.Control

All Known Subinterfaces:

AudioVirtualizerControl, ChorusControl, EqualizerControl, ImageEffectControl, ImageTonalityControl, ImageTransformControl, OverlayControl, ReverbControl, WhiteBalanceControl

public interface EffectControl

extends javax.microedition.media.Control

EffectControl is an interface for controlling an abstract filter with various preset settings. Individual effects might have various parameters.

The effects can be turned on and off by using the setEnabled method. By default, effects are disabled.

Scope of the Effects

The scope of an effect specifies the stages of computation where the effect is present and active. The default scope is SCOPE_LIVE_AND_RECORD if supported, otherwise SCOPE_LIVE_ONLY. If neither of these scopes is supported then the scope defaults to SCOPE_RECORD_ONLY. It is possible that certain modes are not allowed for certain effects.

Enforcing Effects

Crucial effects can be enforced to be in use. If the resources of the system go down and an enforced effect should be dropped, the associated Player (or EffectModule) will be stopped instead. An effect which is not enforced can be dropped if the system runs out of resources without stopping the associated Player or EffectModule. This automatic dropping does, however, not affect the enabled state of the EffectControl (set/getEnabled).

Enforcing affects only the LIVE part of the processing; the RECORD part is always "enforced". The enforcing setting of an EffectControl of a MediaProcessor does not affect in any way.

Field Summary

static int	SCOPE_LIVE_AND_RECORD A constant used to identify both parts of the effect queue.
static int	SCOPE_LIVE_ONLY A constant used to identify the live part of the effect queue.
static int	SCOPE_RECORD_ONLY A constant used to identify the recording part of the effect queue.

Method Summary

java.lang.String	getPreset() Gets the current preset.
java.lang.String[]	getPresetNames() Gets the available preset names.
int	getScope() Returns the scope in which the effect is present.
boolean	isEnabled() Returns true if the effect is enabled and false otherwise.
boolean	isEnforced() Returns the current enforced setting of the effect.
void	setEnabled(boolean enable) Enables/disables the effect.
void	setEnforced(boolean enforced) Enforces the effect to be in use.
void	setPreset(java.lang.String preset) Sets the effect according to the given preset.
void	setScope(int scope) Sets the scope of the effect.

Field Detail

SCOPE_LIVE_ONLY

public static final int SCOPE_LIVE_ONLY

A constant used to identify the live part of the effect queue. For example, the live part of the effect chain might be the video shown in the viewfinder.

See Also:

Constant Field Values

SCOPE_RECORD_ONLY

public static final int SCOPE_RECORD_ONLY

A constant used to identify the recording part of the effect queue. For example, in the case of video, the live effects are applied for the viewfinder and the record effects affect the video stored in a file.

See Also:

Constant Field Values

SCOPE_LIVE_AND_RECORD

public static final int SCOPE_LIVE_AND_RECORD

A constant used to identify both parts of the effect queue. For example, in the case of video, the effects are applied both for the viewfinder and the video stored in a file.

See Also:

Constant Field Values

Method Detail

setEnabled

public void setEnabled(boolean enable)

Enables/disables the effect.

Parameters:

enable - true to enable the effect, false to disable it

Throws:

java.lang.IllegalStateException - if the effect cannot be enabled in this state of the player

See Also:

setScope(int)

isEnabled

public boolean isEnabled()

Returns true if the effect is enabled and false otherwise.

Returns:

true if the effect is enabled, false if not

setScope

public void setScope(int scope)
              throws javax.microedition.media.MediaException

Sets the scope of the effect.

If this is an EffectControl of the MediaProcessor, the scope setting does not affect in anything.

Parameters:

scope - SCOPE_LIVE_ONLY, SCOPE_RECORD_ONLY or SCOPE_LIVE_AND_RECORD.

Throws:

javax.microedition.media.MediaException - if the given scope is not supported

See Also:

getScope()

getScope

public int getScope()

Returns the scope in which the effect is present.

Returns:

SCOPE_LIVE_ONLY, SCOPE_RECORD_ONLY or SCOPE_LIVE_AND_RECORD

See Also:

setScope(int)

setEnforced

public void setEnforced(boolean enforced)

Enforces the effect to be in use.

If this is an EffectControl of a MediaProcessor, the enforced setting does not affect in any way.

Parameters:

enforced - true if the effect is essential and cannot be dropped, false if the effect can be dropped if the system runs out of resources

See Also:

setScope(int)

isEnforced

public boolean isEnforced()

Returns the current enforced setting of the effect.

Returns:

true if the effect is an enforced effect, false if not

See Also:

setEnforced(boolean)

setPreset

public void setPreset(java.lang.String preset)

Sets the effect according to the given preset.

Parameters:

preset - the new preset that will be taken into use

Throws:

java.lang.IllegalArgumentException - if the preset is not available or it is null

See Also:

getPreset()

getPreset

public java.lang.String getPreset()

Gets the current preset.

Returns:

the preset that is set at the moment. If none of the presets is set, null will be returned.

See Also:

setPreset(java.lang.String)

getPresetNames

public java.lang.String[] getPresetNames()

Gets the available preset names.

Returns:

the names of all the available preset modes