javax.microedition.amms.control.camera
Interface ZoomControl

All Superinterfaces:

javax.microedition.media.Control

public interface ZoomControl

extends javax.microedition.media.Control

ZoomControl controls the Optical and Digital Zoom (Magnification) of the digital camera device.

The zoom is expressed in image magnification such as 1x, 2x, 2.5x and so forth. In ZoomControl, the values of the zoom are multiplied by 100 so a zoom of 1x has a value of 100, a zoom of 2.5x will have the value of 250 etc. The smallest zoom value of a camera is 1x (value == 100) and it is also the default zoom value for a digital zoom. The default zoom value for an optical zoom is not necessarily 100; it can vary. It can be queried by getOpticalZoom before setting a new value by setOpticalZoom.

The zoom for either an optical or a digital zoom ranges from the minimum 100 to the maximum by incremental levels. Setting the zoom to a value other than a supported level will result in a rounding to the closest level value. The methods getMaxOpticalZoom() and getMaxDigitalZoom() enable an application to query for the maximum zoom level. The methods getOpticalZoomLevels() and getDigitalZoomLevels() enable an application to query for the number of supported zoom levels. The constants NEXT and PREVIOUS enable an application to step through the zoom levels from minimum to maximum.

If the optical or digital zoom is not supported, getMaxOpticalZoom and getMaxDigitalZoom return 100 and getOpticalZoomLevels and getDigitalZoomLevels return 1, respectively.

Field Summary

static int	NEXT Moves the setting to the next level.
static int	PREVIOUS Moves the setting to the previous level.
static int	UNKNOWN Unknown value.

Method Summary

int	getDigitalZoom() Returns the current digital zoom value.
int	getDigitalZoomLevels() Tells how many levels the digital zoom has.
int	getMaxDigitalZoom() Returns the maximum digital zoom value.
int	getMaxOpticalZoom() Returns the maximum optical zoom value of the camera device.
int	getMinFocalLength() Returns the minimum (35 mm camera equivalent) focal length of the camera device.
int	getOpticalZoom() Returns the optical zoom value of the camera device.
int	getOpticalZoomLevels() Tells how many levels the optical zoom has.
int	setDigitalZoom(int level) Sets the digital zoom of the camera device.
int	setOpticalZoom(int level) Sets the optical zoom of the camera device.

Field Detail

NEXT

public static final int NEXT

Moves the setting to the next level.

See Also:

Constant Field Values

PREVIOUS

public static final int PREVIOUS

Moves the setting to the previous level.

See Also:

Constant Field Values

UNKNOWN

public static final int UNKNOWN

Unknown value.

See Also:

Constant Field Values

Method Detail

setOpticalZoom

public int setOpticalZoom(int level)

Sets the optical zoom of the camera device. The default optical zoom value is not necessarily 100 which is the minimum magnification. getOpticalZoom can be used to ask the default value before setting the new value.

The camera may have some set of zoom levels which the optical zoom can be set to. getOpticalZoomLevels can be used to query the number of zoom levels, and setting the zoom to PREVIOUS or NEXT sets the zoom to the previous or next zoom level, respectively.

Setting the optical zoom is a mechanical operation which it takes some time to complete. The method only returns when the setting of the zoom has been completed.

Implementation of the setOpticalZoom method is synchronized to let only one physical setting of the object lens be effective at a time.

Please note that changing the optical zooming might change the minimum possible focusing distance (the return value of FocusControl.getMinFocus) and therefore alter the actual current focusing distance (FocusControl.getFocus) if the current focus setting is not possible with the new zoom setting.

Parameters:

level - the new optical zoom value (>= 100) or NEXT or PREVIOUS to set the zoom to the next or previous level, respectively

Returns:

zoom value that was actually set by the implementation

Throws:

java.lang.IllegalArgumentException - thrown if the level is less than 100, or if the level is greater than the maximum optical zoom value, and if the level is not NEXT or PREVIOUS

getOpticalZoom

public int getOpticalZoom()

Returns the optical zoom value of the camera device.

Returns:

the current optical zoom value or UNKNOWN if the setting is unknown

getMaxOpticalZoom

public int getMaxOpticalZoom()

Returns the maximum optical zoom value of the camera device. If the maximum optical zoom is 100 the camera device does not support optical zoom.

Returns:

the maximum optical zoom value

getOpticalZoomLevels

public int getOpticalZoomLevels()

Tells how many levels the optical zoom has.

Returns:

number of optical zoom levels

getMinFocalLength

public int getMinFocalLength()

Returns the minimum (35 mm camera equivalent) focal length of the camera device.

The current focal length can be calculated when the minimum focal length and the current optical zoom value are known by the following formula.

focal length = magnification * minimum focal length

Since the magnification is expressed in a form where 100 = 1x magnification, then in the application the calculation is:

int focalLength = getOpticalZoom() * getMinFocalLength() / 100;

Returns:

minimum focal length in micrometers or UNKNOWN if minimum focal length is not known

setDigitalZoom

public int setDigitalZoom(int level)

Sets the digital zoom of the camera device. The default digital zoom value is 100. Setting the digital zoom is effective in images that are taken by getSnapshot.

The zoom value of 100 corresponds to no zoom, the value of 200 corresponds to a double zoom, etc. If the exact given value is not supported it will be rounded to the closest supported value.

The digital zoom probably has a set of zoom levels which the zoom can be set to. getDigitalZoomLevels can be used to query the number of zoom levels, and setting the zoom to PREVIOUS or NEXT sets the zoom to the previous or next zoom level, respectively.

Parameters:

level - new digital zoom value, or NEXT or PREVIOUS to set the digital zoom to the next or previous supported level, respectively. That is, NEXT zooms in and PREVIOUS zooms out.

Returns:

Digital zoom that was actually set.

Throws:

java.lang.IllegalArgumentException - thrown if the level is less than 100 and not NEXT or PREVIOUS, or if the level is greater than the maximum digital zoom value.

getDigitalZoom

public int getDigitalZoom()

Returns the current digital zoom value.

Returns:

the current digital zoom value

getMaxDigitalZoom

public int getMaxDigitalZoom()

Returns the maximum digital zoom value. Maximum value of 100 tells that setting of the digital zoom is not supported.

Returns:

the maximum zoom value to be used with setDigitalZoom

getDigitalZoomLevels

public int getDigitalZoomLevels()

Tells how many levels the digital zoom has.

Returns:

number of digital zoom levels