javax.microedition.amms.control.imageeffect
Interface OverlayControl

All Superinterfaces:

javax.microedition.media.Control, EffectControl

public interface OverlayControl
extends EffectControl

OverlayControl controls the setting of overlay images on top of video or still image. This is useful, for instance, when adding frames to a photograph.

Images are referenced as Objects in order to support multiple UI technologies. For example, in MIDP lcdui the Object is javax.microedition.lcdui.Image and in AWT it is java.awt.Image.

Overlayed images can be placed partially or completely outside the video or image which the overlay is done for in which case the overlayed images will be cropped and the parts left outside will be ignored.

OverlayControl of a video Player only affects the viewfinder. Overlayed images for recorded video and captured images can be added by using MediaProcessor to post-process the media.

Same image can be added multiple times to the Control. removeImage(Object image) removes them all.

Image Drawing Order

Images in OverlayControl have an order. When Images are rendered on top of the content, the drawing is started from the Image which has the lowest order and the Image drawn last has the highest order. An Image inserted with an order that already contains an Image, causes the new Image to be inserted in that place and the order of the previous Image is increased by one.

For example, two images are added to OverlayControl so that the inner frame will be drawn on top of the outer frame.

 Image outerFrame = Image.createImage("/outerFrame.png");
 Image innerFrame = Image.createImage("/innerFrame.png");
 OverlayControl overlay = myMediaProcessor.getControl
    ("javax.microedition.media.control.imageeffect.OverlayControl");

 overlay.insertImage(innerFrame, 0,0,1); // order = 1
 overlay.insertImage(outerFrame, 0,0,0); // order = 0
 

Transparency and Image Types

The alpha channel and transparency of the overlayed images will remain when they are rendered on top of the content. It is also possible to define one color for each overlayed image to be fully transparent by setting the transparentColor to the RGB value that represents transparency in the image.

Mutable Images can be used for overlays but the modifications to the Image are not effective to the overlay. The contents of the Image are copied when the Image is added and it has to be removed and added again to make later changes effective.

See Also:

Image, EffectControl, MediaProcessor

Field Summary

Fields inherited from interface javax.microedition.amms.control.EffectControl

SCOPE_LIVE_AND_RECORD, SCOPE_LIVE_ONLY, SCOPE_RECORD_ONLY

Method Summary

void	clear() Removes all Images from the Control.
java.lang.Object	getImage(int order) Gets the overlay Image.
int	insertImage(java.lang.Object image, int x, int y, int order) Adds an overlay Image to the Control.
int	insertImage(java.lang.Object image, int x, int y, int order, int transparentColor) Adds an overlay Image to the specified position in the drawing list and to the specified position on the picture.
int	numberOfImages() Returns the number of Images in the Control.
void	removeImage(java.lang.Object image) Removes the overlay Image.

Methods inherited from interface javax.microedition.amms.control.EffectControl

getPreset, getPresetNames, getScope, isEnabled, isEnforced, setEnabled, setEnforced, setPreset, setScope

Method Detail

insertImage

int insertImage(java.lang.Object image,
                int x,
                int y,
                int order)
                throws java.lang.IllegalArgumentException

Adds an overlay Image to the Control. The coordinates of the Image refer to the top left corner of the video or image which the overlay is done for.

Parameters:

image - Image object containing the overlay image

x - the x-coordinate of the processed image where the top left corner of the overlayed image will be rendered

y - the y-coordinate of the processed image where the top left corner of the overlayed image will be rendered

order - the place where the image will be added in the drawing list

Returns:

order of the inserted Image after the insertion

Throws:

java.lang.IllegalArgumentException - when overlayImage is not an Image object or is null

java.lang.IllegalArgumentException - if order < 0

insertImage

int insertImage(java.lang.Object image,
                int x,
                int y,
                int order,
                int transparentColor)
                throws java.lang.IllegalArgumentException

Adds an overlay Image to the specified position in the drawing list and to the specified position on the picture. The coordinates of the image refer to the top left corner of the video or image which the overlay is done for.

Parameters:

image - Image object containing the overlay image

x - the x-coordinate of the processed image where the top left corner of the overlayed image will be rendered

y - the y-coordinate of the processed image where the top left corner of the overlayed image will be rendered

order - the place where the image will be added in the drawing list

transparentColor - RGB value of the color that is intended to be transparent. The format for storing the RGB into int is 0xXXRRGGBB where the high order byte (XX) is ignored and the remaining bytes contain red, green and blue, respectively.

Returns:

order of the inserted Image after the insertion

Throws:

java.lang.IllegalArgumentException - when overlayImage is not an Image object or is null

java.lang.IllegalArgumentException - if order < 0

removeImage

void removeImage(java.lang.Object image)

Removes the overlay Image. If the Image has been added multiple times, all occurences of it will be removed.

Parameters:

image - Image object to be removed

Throws:

java.lang.IllegalArgumentException - if the image is not in this OverlayControl or is null

getImage

java.lang.Object getImage(int order)

Gets the overlay Image.

Parameters:

order - number of the requested Image

Returns:

overlay Image or null if the requested Image does not exist

Throws:

java.lang.IllegalArgumentException - if order < 0

numberOfImages

int numberOfImages()

Returns the number of Images in the Control.

Returns:

number of Images in the Control

clear

void clear()

Removes all Images from the Control.