javax.microedition.amms.control.camera
Interface ZoomControl

All Superinterfaces:

Control

public interface ZoomControl
extends 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.

Since:

BlackBerry API 5.0.0

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()
int	getDigitalZoomLevels() Tells how many levels the digital zoom has.
int	getMaxDigitalZoom()
int	getMaxOpticalZoom()
int	getMinFocalLength()
int	getOpticalZoom()
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

static final int NEXT

Moves the setting to the next level.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

PREVIOUS

static final int PREVIOUS

Moves the setting to the previous level.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

UNKNOWN

static final int UNKNOWN

Unknown value.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

Method Detail

setOpticalZoom

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 - @return zoom value that was actually set by the implementation the new optical zoom value (>= 100) or NEXT or PREVIOUS to set the zoom to the next or previous level, respectively

Throws:

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

Since:

BlackBerry API 5.0.0

getOpticalZoom

int getOpticalZoom()

Returns:

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

Since:

BlackBerry API 5.0.0

getMaxOpticalZoom

int getMaxOpticalZoom()

Returns:

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

the maximum optical zoom value

Since:

BlackBerry API 5.0.0

getOpticalZoomLevels

int getOpticalZoomLevels()

Tells how many levels the optical zoom has.

Returns:

number of optical zoom levels

Since:

BlackBerry API 5.0.0

getMinFocalLength

int getMinFocalLength()

Returns:

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;

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

Since:

BlackBerry API 5.0.0

setDigitalZoom

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 - @return Digital zoom that was actually set. 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.

Throws:

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.

Since:

BlackBerry API 5.0.0

getDigitalZoom

int getDigitalZoom()

Returns:

the current digital zoom value

Since:

BlackBerry API 5.0.0

getMaxDigitalZoom

int getMaxDigitalZoom()

Returns:

tells that setting of the digital zoom is not supported.

the maximum zoom value to be used with setDigitalZoom

Since:

BlackBerry API 5.0.0

getDigitalZoomLevels

int getDigitalZoomLevels()

Tells how many levels the digital zoom has.

Returns:

number of digital zoom levels

Since:

BlackBerry API 5.0.0