[xiph-commits] r14352 - in trunk/theora: . include/theora lib/dec

[giles at svn.xiph.org]

Author: giles
Date: 2008-01-04 11:33:42 -0800 (Fri, 04 Jan 2008)
New Revision: 14352

Modified:
   trunk/theora/CHANGES
   trunk/theora/include/theora/theora.h
   trunk/theora/lib/dec/state.c
Log:
Clarify the behaviour of theora_granule_frame() and 
theora_granule_time() to return a frame index and
the end of the presentation interval, respectively.

We believe this to be the most useful combination.
In 1.0beta1 and beta2 theora_granule_frame() returned 
the count, not the index. There is no change in the
behaviour of theora_granule_time().


Modified: trunk/theora/CHANGES
===================================================================
--- trunk/theora/CHANGES	2008-01-04 18:37:36 UTC (rev 14351)
+++ trunk/theora/CHANGES	2008-01-04 19:33:42 UTC (rev 14352)
@@ -2,6 +2,10 @@
 
  - Build new libtheoradec and libtheoraenc libraries
    supporting the new API from theora-exp.
+ - Change granule_frame() to return an index as documented.
+   This is a change of behaviour from 1.0beta1.
+ - Document that granule_time() returns the end of the 
+   presentation interval. 
  - Fix a problem with decoder quantizer initialization
  - Fix a page queue problem with png2theora.
  - Dropped build support for Microsoft VS2003.

Modified: trunk/theora/include/theora/theora.h
===================================================================
--- trunk/theora/include/theora/theora.h	2008-01-04 18:37:36 UTC (rev 14351)
+++ trunk/theora/include/theora/theora.h	2008-01-04 19:33:42 UTC (rev 14352)
@@ -698,12 +698,17 @@
 int theora_granule_shift(theora_info *ti);
 
 /**
- * Convert a granulepos to an absolute frame number. The granulepos is
+ * Convert a granulepos to an absolute frame index. The granulepos is
  * interpreted in the context of a given theora_state handle.
+ * 
+ * Note that while the granulepos encodes the frame count (i.e. starting
+ * from 1) this call returns the frame index, starting from zero. Thus
+ * One can calculate the presentation time by multiplying the index by
+ * the rate.
  *
  * \param th A previously initialized theora_state handle (encode or decode)
  * \param granulepos The granulepos to convert.
- * \returns The frame number corresponding to \a granulepos.
+ * \returns The frame index corresponding to \a granulepos.
  * \retval -1 The given granulepos is undefined (i.e. negative)
  *
  * Thus function was added in the 1.0alpha4 release.
@@ -712,7 +717,9 @@
 
 /**
  * Convert a granulepos to absolute time in seconds. The granulepos is
- * interpreted in the context of a given theora_state handle.
+ * interpreted in the context of a given theora_state handle, and gives
+ * the end time of a frame's presentation as used in Ogg mux ordering.
+ *
  * \param th A previously initialized theora_state handle (encode or decode)
  * \param granulepos The granulepos to convert.
  * \returns The absolute time in seconds corresponding to \a granulepos.

Modified: trunk/theora/lib/dec/state.c
===================================================================
--- trunk/theora/lib/dec/state.c	2008-01-04 18:37:36 UTC (rev 14351)
+++ trunk/theora/lib/dec/state.c	2008-01-04 19:33:42 UTC (rev 14352)
@@ -1255,9 +1255,9 @@
     /* 3.2.0 streams mark the frame index instead of the frame count
      * this was changed with stream version 3.2.1 */ 
     if(state->info.version_subminor < 1) {
-      return iframe+pframe + 1;
+      return iframe+pframe;
     } else {
-      return iframe+pframe;
+      return iframe+pframe - 1;
     }
   }
   return -1;
@@ -1267,7 +1267,7 @@
   oc_theora_state *state;
   state=(oc_theora_state *)_encdec;
   if(_granpos>=0){
-      return th_granule_frame(_encdec, _granpos)*((double)state->info.fps_denominator/state->info.fps_numerator);
+      return (th_granule_frame(_encdec,_granpos)+1)*((double)state->info.fps_denominator/state->info.fps_numerator);
   }
   return -1;
 }