javax.microedition.amms.control.camera
Interface ZoomControl

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.

UNKNOWN

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.