Merge "media: change final fields to accessors in MediaTimestamp" into mnc-dev

5 files changed, 52 insertions, 40 deletions

diff --git a/api/current.txt b/api/current.txt
index 5efa685..6dcb733 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -16459,9 +16459,9 @@ package android.media {
   }
 
   public final class MediaTimestamp {
-    field public final float clockRate;
-    field public final long mediaTimeUs;
-    field public final long nanoTime;
+    method public long getAnchorMediaTimeUs();
+    method public long getAnchorSytemNanoTime();
+    method public float getMediaClockRate();
   }
 
   public final class NotProvisionedException extends android.media.MediaDrmException {
diff --git a/api/system-current.txt b/api/system-current.txt
index 119295d..72c2f56 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -17699,9 +17699,9 @@ package android.media {
   }
 
   public final class MediaTimestamp {
-    field public final float clockRate;
-    field public final long mediaTimeUs;
-    field public final long nanoTime;
+    method public long getAnchorMediaTimeUs();
+    method public long getAnchorSytemNanoTime();
+    method public float getMediaClockRate();
   }
 
   public final class NotProvisionedException extends android.media.MediaDrmException {
diff --git a/media/java/android/media/MediaPlayer.java b/media/java/android/media/MediaPlayer.java
index 256ab29..27423d6 100644
--- a/media/java/android/media/MediaPlayer.java
+++ b/media/java/android/media/MediaPlayer.java
@@ -1481,23 +1481,22 @@ public class MediaPlayer implements SubtitleController.Listener
     public native void seekTo(int msec) throws IllegalStateException;
 
     /**
-     * Get current playback position.
+     * Get current playback position as a {@link MediaTimestamp}.
      * <p>
      * The MediaTimestamp represents how the media time correlates to the system time in
-     * a linear fashion. It contains the media time and system timestamp of an anchor frame
-     * ({@link MediaTimestamp#mediaTimeUs} and {@link MediaTimestamp#nanoTime})
-     * and the speed of the media clock ({@link MediaTimestamp#clockRate}).
+     * a linear fashion using an anchor and a clock rate. During regular playback, the media
+     * time moves fairly constantly (though the anchor frame may be rebased to a current
+     * system time, the linear correlation stays steady). Therefore, this method does not
+     * need to be called often.
      * <p>
-     * During regular playback, the media time moves fairly constantly (though the
-     * anchor frame may be rebased to a current system time, the linear correlation stays
-     * steady). Therefore, this method does not need to be called often.
-     * <p>
-     * To help users to get current playback position, this method always returns the timestamp of
-     * just-rendered frame, i.e., {@link System#nanoTime} and its corresponding media time. They
-     * can be used as current playback position.
+     * To help users get current playback position, this method always anchors the timestamp
+     * to the current {@link System#nanoTime system time}, so
+     * {@link MediaTimestamp#getAnchorMediaTimeUs} can be used as current playback position.
      *
      * @return a MediaTimestamp object if a timestamp is available, or {@code null} if no timestamp
      *         is available, e.g. because the media player has not been initialized.
+     *
+     * @see MediaTimestamp
      */
     @Nullable
     public MediaTimestamp getTimestamp()
diff --git a/media/java/android/media/MediaSync.java b/media/java/android/media/MediaSync.java
index d9e554c..851471c 100644
--- a/media/java/android/media/MediaSync.java
+++ b/media/java/android/media/MediaSync.java
@@ -524,24 +524,23 @@ public final class MediaSync {
     }
 
    /**
-    * Get current playback position.
-    * <p>
-    * The MediaTimestamp represents how the media time correlates to the system time in
-    * a linear fashion. It contains the media time and system timestamp of an anchor frame
-    * ({@link MediaTimestamp#mediaTimeUs} and {@link MediaTimestamp#nanoTime})
-    * and the speed of the media clock ({@link MediaTimestamp#clockRate}).
-    * <p>
-    * During regular playback, the media time moves fairly constantly (though the
-    * anchor frame may be rebased to a current system time, the linear correlation stays
-    * steady). Therefore, this method does not need to be called often.
-    * <p>
-    * To help users to get current playback position, this method always returns the timestamp of
-    * just-rendered frame, i.e., {@link System#nanoTime} and its corresponding media time. They
-    * can be used as current playback position.
-    *
-    * @return a MediaTimestamp object if a timestamp is available, or {@code null} if no timestamp
-    *         is available, e.g. because the media sync has not been initialized.
-    */
+     * Get current playback position.
+     * <p>
+     * The MediaTimestamp represents how the media time correlates to the system time in
+     * a linear fashion using an anchor and a clock rate. During regular playback, the media
+     * time moves fairly constantly (though the anchor frame may be rebased to a current
+     * system time, the linear correlation stays steady). Therefore, this method does not
+     * need to be called often.
+     * <p>
+     * To help users get current playback position, this method always anchors the timestamp
+     * to the current {@link System#nanoTime system time}, so
+     * {@link MediaTimestamp#getAnchorMediaTimeUs} can be used as current playback position.
+     *
+     * @return a MediaTimestamp object if a timestamp is available, or {@code null} if no timestamp
+     *         is available, e.g. because the media player has not been initialized.
+     *
+     * @see MediaTimestamp
+     */
     @Nullable
     public MediaTimestamp getTimestamp()
     {
diff --git a/media/java/android/media/MediaTimestamp.java b/media/java/android/media/MediaTimestamp.java
index d3d5618..5ea6bbe 100644
--- a/media/java/android/media/MediaTimestamp.java
+++ b/media/java/android/media/MediaTimestamp.java
@@ -37,22 +37,36 @@ package android.media;
 public final class MediaTimestamp
 {
     /**
-     * Media time in microseconds.
+     * Get the media time of the anchor in microseconds.
      */
-    public final long mediaTimeUs;
+    public long getAnchorMediaTimeUs() {
+        return mediaTimeUs;
+    }
 
     /**
-     * The {@link java.lang.System#nanoTime system time} corresponding to the media time
+     * Get the {@link java.lang.System#nanoTime system time} corresponding to the media time
      * in nanoseconds.
      */
-    public final long nanoTime;
+    public long getAnchorSytemNanoTime() {
+        return nanoTime;
+    }
 
     /**
-     * The rate of the media clock in relation to the system time.
+     * Get the rate of the media clock in relation to the system time.
+     * <p>
      * It is 1.0 if media clock advances in sync with the system clock;
      * greater than 1.0 if media clock is faster than the system clock;
      * less than 1.0 if media clock is slower than the system clock.
      */
+    public float getMediaClockRate() {
+        return clockRate;
+    }
+
+    /** @hide - accessor shorthand */
+    public final long mediaTimeUs;
+    /** @hide - accessor shorthand */
+    public final long nanoTime;
+    /** @hide - accessor shorthand */
     public final float clockRate;
 
     /** @hide */