javax.microedition.amms.control.imageeffect
Interface OverlayControl

All Superinterfaces:
EffectControl, Control

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
Since:
BlackBerry API 5.0.0

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.
 Object getImage(int order)
          Gets the overlay Image.
 int insertImage(Object image, int x, int y, int order)
          Adds an overlay Image to the Control.
 int insertImage(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()
           
 void removeImage(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(Object image,
                int x,
                int y,
                int order)
                throws 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 - @return order of the inserted Image after the insertion the place where the image will be added in the drawing list
Throws:
IllegalArgumentException - when overlayImage is not an Image object or is null
IllegalArgumentException - if order< 0
Since:
BlackBerry API 5.0.0

insertImage

int insertImage(Object image,
                int x,
                int y,
                int order,
                int transparentColor)
                throws 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 - @return order of the inserted Image after the insertion 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.
Throws:
IllegalArgumentException - when overlayImage is not an Image object or is null
IllegalArgumentException - if order< 0
Since:
BlackBerry API 5.0.0

removeImage

void removeImage(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:
IllegalArgumentException - if the image is not in this OverlayControl or is null
Since:
BlackBerry API 5.0.0

getImage

Object getImage(int order)
Gets the overlay Image.

Parameters:
order - @return overlay Image or null if the requested Image does not exist number of the requested Image
Throws:
IllegalArgumentException - if order< 0
Since:
BlackBerry API 5.0.0

numberOfImages

int numberOfImages()
Returns:
Images in the Control.

number of Images in the Control

Since:
BlackBerry API 5.0.0

clear

void clear()
Removes all Images from the Control.

Since:
BlackBerry API 5.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.