javax.microedition.amms.control
Interface EffectControl

All Superinterfaces:

Control

All Known Subinterfaces:

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

public interface EffectControl
extends 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; that is, status changes are allowed and last value set is returned, but the value is ignored in processing.

Since:

BlackBerry API 5.0.0

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
String	getPreset() Gets the current preset.
String[]	getPresetNames() Gets the available preset names.
int	getScope()
boolean	isEnabled()
boolean	isEnforced()
void	setEnabled(boolean enable) Enables/disables the effect.
void	setEnforced(boolean enforced) Enforces the effect to be in use.
void	setPreset(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

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

Since:

BlackBerry API 5.0.0

SCOPE_RECORD_ONLY

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

Since:

BlackBerry API 5.0.0

SCOPE_LIVE_AND_RECORD

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

Since:

BlackBerry API 5.0.0

Method Detail

setEnabled

void setEnabled(boolean enable)

Enables/disables the effect.

Parameters:

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

Throws:

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

Since:

BlackBerry API 5.0.0

isEnabled

boolean isEnabled()

Returns:

true if the effect is enabled, false if not

Since:

BlackBerry API 5.0.0

setScope

void setScope(int scope)
              throws 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:

MediaException - if the given scope is not supported

Since:

BlackBerry API 5.0.0

getScope

int getScope()

Returns:

SCOPE_LIVE_ONLY, SCOPE_RECORD_ONLY or SCOPE_LIVE_AND_RECORD

Since:

BlackBerry API 5.0.0

setEnforced

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

Since:

BlackBerry API 5.0.0

isEnforced

boolean isEnforced()

Returns:

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

Since:

BlackBerry API 5.0.0

setPreset

void setPreset(String preset)

Sets the effect according to the given preset.

Parameters:

preset - the new preset that will be taken into use

Throws:

IllegalArgumentException - if the preset is not available or it is null

Since:

BlackBerry API 5.0.0

getPreset

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.

Since:

BlackBerry API 5.0.0

getPresetNames

String[] getPresetNames()

Gets the available preset names.

Returns:

the names of all the available preset modes

Since:

BlackBerry API 5.0.0