javax.microedition.amms.control.camera
Interface ExposureControl

All Superinterfaces:

Control

public interface ExposureControl
extends Control

ExposureControl controls the exposure settings of the camera device. Exposure is based on three components: aperture, shutter speed (also known as exposure time), and sensitivity. Additionally, for automatic exposure setting, this interface offers multiple light metering modes.

A Player that plays captured stream from a camera may provide an ExposureControl via its getControl and getControls methods.

Aperture

Aperture is the size of the iris permitting incident light onto the image sensor. This is based on the diameter of the iris and the focal length. The focal length defines the cone of the incident light. The aperture in digital and analogue cameras is provided as the "F-Stop" number. The Fstop (f/#) is the ratio of focal length to diameter. The common values are f/1, f/1.4, f/2, f/2.8, f/4, f/5.6, f/8. f/11, f/16, f/22. However, some cameras provide intermediate values. Each value in this list provides 1/2 of the light of the previous value.

Exposure Time

Exposure time (shutter speed) is the amount of time the shutter is open to receive light. This is usually expressed in fractions of a second such as 1/1000 or 1/25. Common values are 1, 1/2, 1/4, 1/8, 1/15, 1/30, 1/60, 1/125, 1/250, 1/500, 1/1000, and 1/2000.

Sensitivity

Sensitivity is the light sensitivity of the film or camera sensor. This value is provided in ISO 35mm film equivalent. The common values are ISO 100, ISO 200, and ISO 400.

Since:

BlackBerry API 5.0.0

Method Summary
int	getExposureCompensation() Gets the current exposure compensation.
int	getExposureTime() Gets the current shutter speed.
int	getExposureValue()
int	getFStop()
int	getISO() Gets the current sensitivity.
String	getLightMetering()
int	getMaxExposureTime() Gets the maximum supported exposure time or 0 if only automatic exposure is supported.
int	getMinExposureTime() Gets the minimum supported exposure time.
int[]	getSupportedExposureCompensations() Gets the supported exposure compensation values.
int[]	getSupportedFStops()
int[]	getSupportedISOs()
String[]	getSupportedLightMeterings()
void	setExposureCompensation(int ec) Sets the exposure compensation.
int	setExposureTime(int time) Sets the shutter speed.
void	setFStop(int aperture) Sets the aperture.
void	setISO(int iso) Sets the sensitivity.
void	setLightMetering(String metering) Sets the metering mode for the automatic exposure of the camera device.

Method Detail

getSupportedFStops

int[] getSupportedFStops()

Returns:

Adjusting the optical zoom (via ZoomControl) might change the list.

the supported F-Stop numbers multiplied by 100. For example, returned value 280 would mean an F-Stop number f/2.8. Value 0 means automatic aperture.

Since:

BlackBerry API 5.0.0

getFStop

int getFStop()

Returns:

the current aperture as an F-Stop number multiplied by 100. For example, returned value 280 would mean an F-Stop number f/2.8.

Since:

BlackBerry API 5.0.0

setFStop

void setFStop(int aperture)
              throws MediaException

Sets the aperture. Adjusting the optical zoom (via ZoomControl) might change the value. Therefore, it is recommended to set the optical zoom first and then set the aperture if needed.

Parameters:

aperture - aperture as an F-Stop number multiplied by 100 or 0 for automatic aperture. For example, returned value 280 would mean an F-Stop number f/2.8.

Throws:

MediaException - if the given value is not supported

Since:

BlackBerry API 5.0.0

getMinExposureTime

int getMinExposureTime()

Gets the minimum supported exposure time.

Returns:

the minimum supported exposure time in microseconds or 0 if only automatic exposure is supported

Since:

BlackBerry API 5.0.0

getMaxExposureTime

int getMaxExposureTime()

Gets the maximum supported exposure time or 0 if only automatic exposure is supported.

Returns:

the maximum supported exposure time in microseconds

Since:

BlackBerry API 5.0.0

getExposureTime

int getExposureTime()

Gets the current shutter speed.

Returns:

the current exposure time in microseconds

Since:

BlackBerry API 5.0.0

setExposureTime

int setExposureTime(int time)
                    throws MediaException

Sets the shutter speed. The implementation will round the given value to the nearest supported one.

Parameters:

time - @return exposure time that was actually set exposure time in microseconds or 0 for automatic exposure time

Throws:

MediaException - if time is greater than the maximum supported exposure time (getMaxExposureTime) or is less than the minimum supported exposure time (getMinExposureTime).

Since:

BlackBerry API 5.0.0

getSupportedISOs

int[] getSupportedISOs()

Returns:

the supported sensitivities as ISO values. For example, returned value 200 would mean an ISO 200. 0 means automatic sensitivity.

Since:

BlackBerry API 5.0.0

getISO

int getISO()

Gets the current sensitivity.

Returns:

the current sensitivity as ISO value. For example, value 200 means ISO 200.

Since:

BlackBerry API 5.0.0

setISO

void setISO(int iso)
            throws MediaException

Sets the sensitivity.

Parameters:

iso - sensitivity as an ISO value. For example, value 200 means ISO 200. 0 means automatic sensitivity.

Throws:

MediaException - if the given value is not supported.

Since:

BlackBerry API 5.0.0

getSupportedExposureCompensations

int[] getSupportedExposureCompensations()

Gets the supported exposure compensation values. If none are supported just one zero will be returned.

Returns:

the supported exposure compensation values multiplied by 100. For example, a returned value 100 means 1.0 (that means doubling the light exposure).

Since:

BlackBerry API 5.0.0

getExposureCompensation

int getExposureCompensation()

Gets the current exposure compensation.

Returns:

the current exposure compensation values multiplied by 100. For example, a returned value 100 means 1.0 (that means doubling the light exposure).

Since:

BlackBerry API 5.0.0

setExposureCompensation

void setExposureCompensation(int ec)
                             throws MediaException

Sets the exposure compensation. This only affects when using automatic exposure settings.

Parameters:

ec - the wanted exposure compensation value multiplied by 100. For example, a value 100 means 1.0 (that means doubling the light exposure).

Throws:

MediaException - if the given value is not supported

Since:

BlackBerry API 5.0.0

getExposureValue

int getExposureValue()

Returns:

to current settings for aperture, shutter speed and sensitivity.

the current exposure value (EV)

Since:

BlackBerry API 5.0.0

getSupportedLightMeterings

String[] getSupportedLightMeterings()

Returns:

Available meterings might include: matrix (the scene is split into a matrix and each zone is measured and has a weighted algorithm.)center-weighted (the metering weighs the center of the image highest (this is the typical normal setting))spot (the metering uses just the center and all the rest is ignored).

the supported meterings

Since:

BlackBerry API 5.0.0

setLightMetering

void setLightMetering(String metering)

Sets the metering mode for the automatic exposure of the camera device. This only affects when using automatic exposure settings.

Parameters:

metering - the new metering mode

Throws:

IllegalArgumentException - if the given metering is not among the supported metering modes

Since:

BlackBerry API 5.0.0

getLightMetering

String getLightMetering()

Returns:

the current light metering mode of the camera device

Since:

BlackBerry API 5.0.0