Merge "Public API changes for CameraProfile and CamcorderProfile classes" into froyo

2010-04-01 10:33:45 -07:00
parent 33eb7767fb e64d9a236e
commit ccc17b34fe
5 changed files with 284 additions and 198 deletions
--- a/api/current.xml
+++ b/api/current.xml
@@ -82509,163 +82509,151 @@
 deprecated="not deprecated"
 visibility="public"
 >
-<parameter name="quality" type="android.media.CamcorderProfile.Quality">
+<parameter name="quality" type="int">
 </parameter>
 </method>
-<method name="getMmsRecordingDurationInSeconds"
- return="int"
- abstract="false"
- native="false"
- synchronized="false"
+<field name="QUALITY_HIGH"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="1"
 static="true"
 final="true"
 deprecated="not deprecated"
 visibility="public"
 >
-</method>
-<field name="mAudioBitRate"
+</field>
+<field name="QUALITY_LOW"
 type="int"
 transient="false"
 volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mAudioChannels"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mAudioCodec"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mAudioSampleRate"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mFileFormat"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mQuality"
- type="android.media.CamcorderProfile.Quality"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mVideoBitRate"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mVideoCodec"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mVideoFrameHeight"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mVideoFrameRate"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="mVideoFrameWidth"
- type="int"
- transient="false"
- volatile="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-</class>
-<class name="CamcorderProfile.Quality"
- extends="java.lang.Enum"
- abstract="false"
+ value="0"
 static="true"
 final="true"
 deprecated="not deprecated"
 visibility="public"
 >
-<method name="valueOf"
- return="android.media.CamcorderProfile.Quality"
- abstract="false"
- native="false"
- synchronized="false"
- static="true"
+</field>
+<field name="audioBitRate"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
 final="false"
 deprecated="not deprecated"
 visibility="public"
 >
-<parameter name="name" type="java.lang.String">
-</parameter>
-</method>
-<method name="values"
- return="android.media.CamcorderProfile.Quality[]"
- abstract="false"
- native="false"
- synchronized="false"
- static="true"
- final="true"
+</field>
+<field name="audioChannels"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
 deprecated="not deprecated"
 visibility="public"
 >
-</method>
+</field>
+<field name="audioCodec"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="audioSampleRate"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="duration"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="fileFormat"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="quality"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="videoBitRate"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="videoCodec"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="videoFrameHeight"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="videoFrameRate"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="videoFrameWidth"
+ type="int"
+ transient="false"
+ volatile="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 </class>
 <class name="CameraProfile"
 extends="java.lang.Object"
@@ -82683,8 +82671,8 @@
 visibility="public"
 >
 </constructor>
-<method name="getImageEncodingQualityLevels"
- return="int[]"
+<method name="getJpegEncodingQualityParameter"
+ return="int"
 abstract="false"
 native="false"
 synchronized="false"
@@ -82693,7 +82681,42 @@
 deprecated="not deprecated"
 visibility="public"
 >
+<parameter name="quality" type="int">
+</parameter>
 </method>
+<field name="QUALITY_HIGH"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="2"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="QUALITY_LOW"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="0"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="QUALITY_MEDIUM"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="1"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 </class>
 <class name="ExifInterface"
 extends="java.lang.Object"
@@ -84608,6 +84631,19 @@
 <parameter name="sv" type="android.view.Surface">
 </parameter>
 </method>
+<method name="setProfile"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="profile" type="android.media.CamcorderProfile">
+</parameter>
+</method>
 <method name="setVideoEncoder"
 return="void"
 abstract="false"
--- a/include/media/MediaProfiles.h
+++ b/include/media/MediaProfiles.h
@@ -24,8 +24,8 @@
 namespace android {

 enum camcorder_quality {
-    CAMCORDER_QUALITY_HIGH = 0,
-    CAMCORDER_QUALITY_LOW  = 1
+    CAMCORDER_QUALITY_LOW  = 0,
+    CAMCORDER_QUALITY_HIGH = 1
 };

 enum video_decoder {
--- a/media/java/android/media/CamcorderProfile.java
+++ b/media/java/android/media/CamcorderProfile.java
@@ -19,17 +19,19 @@ package android.media;
 /**
 * The CamcorderProfile class is used to retrieve the
 * predefined camcorder profile settings for camcorder applications.
+ * These settings are read-only.
+ *
 * The compressed output from a recording session with a given
 * CamcorderProfile contains two tracks: one for auido and one for video.
 *
 * <p>Each profile specifies the following set of parameters:
 * <ul>
- * <li> The file output format, @see android.media.MediaRecorder.OutputFormat
- * <li> Video codec format, @see android.media.MediaRecorder.VideoEncoder
+ * <li> The file output format
+ * <li> Video codec format
 * <li> Video bit rate in bits per second
 * <li> Video frame rate in frames per second
 * <li> Video frame width and height,
- * <li> Audio codec format, @see android.media.MediaRecorder.AudioEncoder
+ * <li> Audio codec format
 * <li> Audio bit rate in bits per second,
 * <li> Audio sample rate
 * <li> Number of audio channels for recording.
@@ -37,98 +39,95 @@ package android.media;
 */
 public class CamcorderProfile
 {
-    private final int mDuration;  // Recording duration in seconds
-
    /**
-     * The Quality class represents the quality level of each CamcorderProfile.
+     * The output from camcorder recording sessions can have different quality levels.
     *
-     * The output from recording sessions with high quality level usually may have
-     * larger output bit rate, better video and/or audio recording quality, and
-     * laerger video frame resolution and higher audio sampling rate, etc, than those
-     * with low quality level.
+     * Currently, we define two quality levels: high quality and low quality.
+     * A camcorder recording session with high quality level usually has higher output bit
+     * rate, better video and/or audio recording quality, larger video frame
+     * resolution and higher audio sampling rate, etc, than those with low quality
+     * level.
+     *
+     * Do not change these values/ordinals without updating their counterpart
+     * in include/media/MediaProfiles.h!
     */
-    public enum Quality {
-       /* Do not change these values/ordinals without updating their counterpart
-        * in include/media/MediaProfiles.h!
-        */
-        HIGH,
-        LOW
-    };
+    public static final int QUALITY_LOW  = 0;
+    public static final int QUALITY_HIGH = 1;

    /**
-     * Returns the recording duration in seconds for LOW quality CamcorderProfile
-     * used by the MMS application.
+     * Default recording duration in seconds before the session is terminated.
+     * This is useful for applications like MMS has limited file size requirement.
     */
-    public static final int getMmsRecordingDurationInSeconds() {
-        return get(Quality.LOW).mDuration;
-    }
+    public int duration;

    /**
     * The quality level of the camcorder profile
-     * @see android.media.CamcorderProfile.Quality
     */
-    public final Quality mQuality;
+    public int quality;

    /**
     * The file output format of the camcorder profile
     * @see android.media.MediaRecorder.OutputFormat
     */
-    public final int mFileFormat;
+    public int fileFormat;

    /**
     * The video encoder being used for the video track
     * @see android.media.MediaRecorder.VideoEncoder
     */
-    public final int mVideoCodec;
+    public int videoCodec;

    /**
     * The target video output bit rate in bits per second
     */
-    public final int mVideoBitRate;
+    public int videoBitRate;

    /**
     * The target video frame rate in frames per second
     */
-    public final int mVideoFrameRate;
+    public int videoFrameRate;

    /**
     * The target video frame width in pixels
     */
-    public final int mVideoFrameWidth;
+    public int videoFrameWidth;

    /**
     * The target video frame height in pixels
     */
-    public final int mVideoFrameHeight;
+    public int videoFrameHeight;

    /**
     * The audio encoder being used for the audio track.
     * @see android.media.MediaRecorder.AudioEncoder
     */
-    public final int mAudioCodec;
+    public int audioCodec;

    /**
     * The target audio output bit rate in bits per second
     */
-    public final int mAudioBitRate;
+    public int audioBitRate;

    /**
     * The audio sampling rate used for the audio track
     */
-    public final int mAudioSampleRate;
+    public int audioSampleRate;

    /**
     * The number of audio channels used for the audio track
     */
-    public final int mAudioChannels;
+    public int audioChannels;

    /**
-     * Returns the camcorder profile for the given quality.
+     * Returns the camcorder profile for the given quality level.
     * @param quality the target quality level for the camcorder profile
-     * @see android.media.CamcorderProfile.Quality
     */
-    public static CamcorderProfile get(Quality quality) {
-        return native_get_camcorder_profile(quality.ordinal());
+    public static CamcorderProfile get(int quality) {
+        if (quality < QUALITY_LOW || quality > QUALITY_HIGH) {
+            String errMessage = "Unsupported quality level: " + quality;
+            throw new IllegalArgumentException(errMessage);
+        }
+        return native_get_camcorder_profile(quality);
    }

    static {
@@ -150,18 +149,18 @@ public class CamcorderProfile
                             int audioSampleRate,
                             int audioChannels) {

-        mDuration         = duration;
-        mQuality          = Quality.values()[quality];
-        mFileFormat       = fileFormat;
-        mVideoCodec       = videoCodec;
-        mVideoBitRate     = videoBitRate;
-        mVideoFrameRate   = videoFrameRate;
-        mVideoFrameWidth  = videoWidth;
-        mVideoFrameHeight = videoHeight;
-        mAudioCodec       = audioCodec;
-        mAudioBitRate     = audioBitRate;
-        mAudioSampleRate  = audioSampleRate;
-        mAudioChannels    = audioChannels;
+        this.duration         = duration;
+        this.quality          = quality;
+        this.fileFormat       = fileFormat;
+        this.videoCodec       = videoCodec;
+        this.videoBitRate     = videoBitRate;
+        this.videoFrameRate   = videoFrameRate;
+        this.videoFrameWidth  = videoWidth;
+        this.videoFrameHeight = videoHeight;
+        this.audioCodec       = audioCodec;
+        this.audioBitRate     = audioBitRate;
+        this.audioSampleRate  = audioSampleRate;
+        this.audioChannels    = audioChannels;
    }

    // Methods implemented by JNI
--- a/media/java/android/media/CameraProfile.java
+++ b/media/java/android/media/CameraProfile.java
@@ -16,6 +16,8 @@

 package android.media;

+import java.util.Arrays;
+
 /**
 * The CameraProfile class is used to retrieve the pre-defined still image
 * capture (jpeg) quality levels (0-100) used for low, medium, and high
@@ -25,23 +27,52 @@ package android.media;
 public class CameraProfile
 {
    /**
-     * Returns a list of the pre-defined still image capture (jpeg) quality levels
-     * used for low, medium and high quality settings in the Camera application.
+     * Define three quality levels for JPEG image encoding.
     */
-    public static int[] getImageEncodingQualityLevels() {
-        int nLevels = native_get_num_image_encoding_quality_levels();
-        if (nLevels == 0) return null;
+    /*
+     * Don't change the values for these constants unless getImageEncodingQualityLevels()
+     * method is also changed accordingly.
+     */
+    public static final int QUALITY_LOW    = 0;
+    public static final int QUALITY_MEDIUM = 1;
+    public static final int QUALITY_HIGH   = 2;

-        int[] levels = new int[nLevels];
-        for (int i = 0; i < nLevels; ++i) {
-            levels[i] = native_get_image_encoding_quality_level(i);
+    /*
+     * Cache the Jpeg encoding quality parameters
+     */
+    private static final int[] sJpegEncodingQualityParameters;
+
+    /**
+     * Returns a pre-defined still image capture (jpeg) quality level
+     * used for the given quality level in the Camera application.
+     *
+     * @param quality The target quality level
+     */
+    public static int getJpegEncodingQualityParameter(int quality) {
+        if (quality < QUALITY_LOW || quality > QUALITY_HIGH) {
+            throw new IllegalArgumentException("Unsupported quality level: " + quality);
        }
-        return levels;
+        return sJpegEncodingQualityParameters[quality];
    }

    static {
        System.loadLibrary("media_jni");
        native_init();
+        sJpegEncodingQualityParameters = getImageEncodingQualityLevels();
+    }
+
+    private static int[] getImageEncodingQualityLevels() {
+        int nLevels = native_get_num_image_encoding_quality_levels();
+        if (nLevels != QUALITY_HIGH + 1) {
+            throw new RuntimeException("Unexpected Jpeg encoding quality levels " + nLevels);
+        }
+
+        int[] levels = new int[nLevels];
+        for (int i = 0; i < nLevels; ++i) {
+            levels[i] = native_get_image_encoding_quality_level(i);
+        }
+        Arrays.sort(levels);  // Lower quality level ALWAYS comes before higher one
+        return levels;
    }

    // Methods implemented by JNI
--- a/media/java/android/media/MediaRecorder.java
+++ b/media/java/android/media/MediaRecorder.java
@@ -16,6 +16,7 @@

 package android.media;

+import android.media.CamcorderProfile;
 import android.hardware.Camera;
 import android.os.Handler;
 import android.os.Looper;
@@ -258,6 +259,25 @@ public class MediaRecorder
    public native void setVideoSource(int video_source)
            throws IllegalStateException;

+    /**
+     * Uses the settings from a CamcorderProfile object for recording. This method should
+     * be called after the video AND audio sources are set, and before setOutputFile().
+     *
+     * @param profile the CamcorderProfile to use
+     * @see android.media.CamcorderProfile
+     */
+    public void setProfile(CamcorderProfile profile) {
+        setOutputFormat(profile.fileFormat);
+        setVideoFrameRate(profile.videoFrameRate);
+        setVideoSize(profile.videoFrameWidth, profile.videoFrameHeight);
+        setVideoEncodingBitRate(profile.videoBitRate);
+        setAudioEncodingBitRate(profile.audioBitRate);
+        setAudioChannels(profile.audioChannels);
+        setAudioSamplingRate(profile.audioSampleRate);
+        setVideoEncoder(profile.videoCodec);
+        setAudioEncoder(profile.audioCodec);
+    }
+
    /**
     * Sets the format of the output file produced during recording. Call this
     * after setAudioSource()/setVideoSource() but before prepare().