Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

Advanced Multimedia Supplement API - What's Supported

by Retired ‎02-03-2011 11:24 AM - edited ‎09-13-2011 01:58 PM (6,137 Views)

The Advanced Multimedia Supplement (AMMS) API, also known as JSR-234, is used to access advanced camera features on the BlackBerry® platform.  As of BlackBerry® 6.0 none of the audio capabilities of AMMS has been implemented, with the exception of AudioFormatControl and VideoFormatControl which have been implemented only so far as to support their stated features for video and still image capture.  Conversely many of the camera capabilities have been implemented.

 

AMMS by definition allows implementers to implement only some of the API.  Specifically, only the relevant ‘parts’ to the destination platform need to be implemented, with each ‘part’ consisting of a set of classes to implement.  The guarantee AMMS makes however is that any part that is implemented must be fully implemented to the extent that the platform can support it.  This means that each class that must be implemented as a part will itself be only partially implemented enough to fulfill that part with what the device is capable of.  Still following? 

 

To put it another way, within each class the level of implementation depends on what the device can actually do. When an AMMS class is implemented the BlackBerry platform will guarantee to support the invocation (meaning an application that attempts to call an unsupported feature will compile and, if properly written, will fail gracefully and not crash) but not necessarily the implementation.

 

This is why developers who have used the AMMS API classes have found that not every portion of a class is fully implemented.  For example, the CameraControl class is an implemented AMMS class on the BlackBerry platform.  If an application were to call its isShutterFeedbackEnabled() method, it would always return true since that feature is supported on all platforms (a ‘click’ sound is heard when a picture is taken).  However, if that same application called its enableShutterFeedback(boolean) method, a MediaException would be thrown with the message “Setting shutter feedback is not possible”. This is because although the feature is supported, the ability to toggle it is not - it is always on.

 

For most classes in the AMMS API there are built-in methods to query the level of support of that class, but this was not done consistently.  In some cases the AMMS JavaDoc™ will state the behaviour of the platform if the particular feature or method is not supported on the implementing platform.  For example, in the case of the MediaException mentioned in the example above, there is no method to query if toggling shutter feedback is supported but the documentation states that the method “throws javax.microedition.media.MediaException - if setting of the shutter feedback is not possible”.[1]

 

What’s Supported?

Once your application has created a player for still image capture or for video capture, the controls available depend largely on the context of the player.  For example a player for still image capture will not have an AudioFormatControl available, however a player for video capture will.  The following is a list of controls that are implemented for at least one player context:

 

      javax.microedition.amms.control.camera.CameraControl

      javax.microedition.amms.control.camera.FlashControl

      javax.microedition.amms.control.camera.SnapshotControl

      javax.microedition.amms.control.camera.ZoomControl

      javax.microedition.amms.control.camera.FocusControl

      javax.microedition.amms.control.AudioFormatControl

      javax.microedition.amms.control.VideoFormatControl

      javax.microedition.amms.control.ContainerFormatControl

      All controls and classes in net.rim.device.api.amms.control.camera

 

Similarly, the following controls are not implemented at all on the BlackBerry platform:

 

      javax.microedition.amms.EffectOrderControl

      javax.microedition.amms.control.camera.ImageFormatControl

      javax.microedition.amms.MIDIChannelControl

      javax.microedition.amms.PanControl

      javax.microedition.amms.PriorityControl

      javax.microedition.amms.control.camera.ExposureControl

      None of the classes in the javax.microedition.amms root package

      None of the controls in javax.microedition.amms.control.audio3d

      None of the controls in javax.microedition.amms.control.audioeffect

      None of the controls in javax.microedition.amms.control.tuner

      None of the controls in javax.microedition.amms.control.imageeffect

 

Within each implemented class, there are varying levels of implemented methods, as previously explained.  The table below shows a list of which methods are implemented for each supported AMMS Control.

 

Class

Method

Implemented?

CameraControl

enableShutterFeedback(boolean)

NO

getCameraRotation()

YES

getExposureMode()

YES

getStillResolution()

YES

getSupportedExposureModes()

YES

getSupportedStillResolutions()

YES

getSupportedVideoResolutions()

NO

getVideoResolution()

NO

isShutterFeedbackEnabled()

YES

setExposureMode(String)

YES

setStillResolution(int)

YES

setVideoResolution(int)

NO

FocusControl

getFocus()

YES

getFocusSteps()

NO

getMacro()

YES

getMinFocus()

NO

isAutoFocusSupported()

YES

isMacroSupported()

YES

isManualFocusSupported()

YES

setFocus(int)

YES

setMacro(boolean)

YES

EnhancedFocusControl

getCurrentFocusMode()

YES

isAutoFocusLocked()

YES

isFocusModeSupported()

YES

setFocusMode()

YES

startAutoFocus()

YES

stopAutoFocus()

YES

FlashControl

getMode()

YES

getSupportedModes()

YES

isFlashReady()

YES

setMode(int)

YES

ZoomControl

getDigitalZoom()

YES

getDigitalZoomLevels()

YES

getMaxDigitalZoom()

YES

getMaxOpticalZoom()

NO

getMinFocalLength()

NO

getOpticalZoom()

NO

getOpticalZoomLevels()

YES

setDigitalZoom(int)

YES

setOpticalZoom(int)

YES

SnapshotControl

getDirectory()

YES

getFilePrefix()

YES

getFileSuffix()

YES

setDirectory(String)

YES

setFilePrefix(String)

YES

setFileSuffix(String)

YES

start(int)

YES

stop()

YES

unfreeze(boolean)

YES

AudioFormatControl

getEstimatedBitRate()

NO

getFormat()

YES

getIntParameterValue(String)

NO

getMetadataOverride()

YES

getMetadataSupportMode()

YES

getStrParameterValue(String)

YES

getSupportedFormats()

YES

getSupportedIntParameterRange(String)

NO

getSupportedIntParameters()

YES

getSupportedMetadataKeys()

YES

getSupportedStrParameters()

YES

getSupportedStrParameterValues(String)

YES

setFormat(String)

YES

setMetadata(String, String)

NO

setMetadataOverride(boolean)

NO

setParameter(String, int)

NO

setParameter(String, String)

YES

VideoFormatControl

getEstimatedBitRate()

NO

getFormat()

YES

getIntParameterValue(String)

YES

getMetadataOverride()

YES

getMetadataSupportMode()

YES

getStrParameterValue(String)

YES

getSupportedFormats()

YES

getSupportedIntParameterRange(String)

YES

getSupportedIntParameters()

YES

getSupportedMetadataKeys()

YES

getSupportedStrParameters()

YES

getSupportedStrParameterValues(String)

YES

setFormat(String)

YES

setMetadata(String, String)

NO

setMetadataOverride(boolean)

NO

setParameter(String, int)

YES

setParameter(String, String)

YES

ContainerFormatControl

getEstimatedBitRate()

NO

getFormat()

YES

getIntParameterValue(String)

NO

getMetadataOverride()

YES

getMetadataSupportMode()

YES

getStrParameterValue(String)

YES

getSupportedFormats()

YES

getSupportedIntParameterRange(String)

NO

getSupportedIntParameters()

NO

getSupportedMetadataKeys()

NO

getSupportedStrParameters()

YES

getSupportedStrParameterValues(String)

YES

setFormat(String)

NO

setMetadata(String, String)

NO

setMetadataOverride(boolean)

NO

setParameter(String, int)

YES

setParameter(String, String)

NO

 


[1] Source: JSR-234 JavaDocs available at  http://jcp.org/aboutJava/communityprocess/mrel/jsr234/index.html

Advanced Multimedia Supplement API is used to access advanced camera features on the BlackBerry platform.  As of BlackBerry OS 6.1 none of the audio capabilities of AMMS has been implemented, with the exception of AudioFormatControl and VideoFormatControl which have been implemented only so far as to support their stated features for the video and still image capture.  Conversely many of the camera capabilities have been implemented.

AMMS by definition allows implementers to implement only some of the API.  Specifically, only the relevant ‘parts’ to the destination platform need to be implemented, with each ‘part’ consisting of a set of classes to implement.  The guarantee AMMS does make however is that any part that is implemented must be fully implemented.  However, each class that must be implemented as a part may itself be only partially implemented enough to fulfill that part with what the device is capable of.  Still following? 

To put it another way, within each class the level of implementation depends on what the device can actually do. When an AMMS class is implemented the BlackBerry platform will guarantee to support the invocation (meaning an app that attempts to call an unsupported feature will compile and, if properly written, will fail gracefully and not crash) but not necessarily the implementation.

This is why developers who have used the AMMS API classes have found that not every portion of a class is fully implemented.  For example the CameraControl class is an implemented AMMS class on the Blackberry platform.  If an application were to call its isShutterFeedbackEnabled() method, it would always return true since that feature is supported on all platforms (a ‘click’ sound is heard when a picture is taken).  However if that same application called its enableShutterFeedback(boolean) method a MediaException would be thrown with the message “Setting shutter feedback is not possible” because although the feature is supported, the ability to toggle it is not.

For some classes in the AMMS API there are built-in methods to query the level of support of that class, but this was not done consistently.  In some cases the AMMS JavaDoc will state the behaviour of the platform if the particular feature or method is not supported on the implementing platform.  For example, in the case of the MediaException mentioned in the example above, there is no method to query if toggling shutter feedback is supported but the documentation states that the method “throws  javax.microedition.media.MediaException - if setting of the shutter feedback is not possible”.[1]

What’s Supported

Once your application has created a player for still image capture, the controls available depend largely on the context of the player (still image capture vs. audio capture for example).  The following is a list of controls that are implemented for at least one context:

*      javax.microedition.amms.control.camera.FlashControl

*      javax.microedition.amms.control.camera.SnapshotControl

*      javax.microedition.amms.control.camera.ZoomControl

*      javax.microedition.amms.control.camera.FocusControl

*      net.rim.device.api.amms.control.camera.EnhancedFocusControl

*      javax.microedition.amms.control.camera.ImageFormatControl

*      javax.microedition.amms.control.camera.CameraControl

*      AudioFormatControl

*      VideoFormatControl

*      ContainerFormatControl

Similarly, the following controls are not implemented at all on the BlackBerry media platform:

*      javax.microedition.amms.EffectOrderControl

*      javax.microedition.amms.MIDIChannelControl

*      javax.microedition.amms.PanControl

*      javax.microedition.amms.PriorityControl

*      javax.microedition.amms.control.camera.ExposureControl

*      None of the controls in javax.microedition.amms.control.audio3d

*      None of the controls in javax.microedition.amms.control.audioeffect

*      None of the controls in javax.microedition.amms.control.tuner

*      None of the controls in javax.microedition.amms.control.imageeffect

Within each implemented class, there are varying levels of implemented methods, as previously explained.  Appendix B – Implemented Methods in AMMS shows a list of which methods are implemented for each AMMS Control.  Note that for the AudioFormatControl and the VideoFormatControl, new support to get and set bitrates of playing video were added for BlackBerry OS 6.1.  Table 10 in Appendix B includes this support, but your application can programmatically check for support of various AMMS features using the getSupported* methods on each control.

Users Online
Currently online: 26 members 3,653 guests
Please welcome our newest community members: