Update the documentation for theora_encode_comment().
authorTim Terriberry <tterribe@xiph.org>
Fri, 20 May 2011 21:27:08 +0000 (21:27 +0000)
committerTim Terriberry <tterribe@xiph.org>
Fri, 20 May 2011 21:27:08 +0000 (21:27 +0000)
It wrongly claimed the returned buffer was owned by libtheora, when
 in reality libtheora was creating a temporary buffer and not
 storing the pointer to the returned packet anywhere.
Since there's no encoder parameter passed to this function, it
 doesn't even have a place to store it.
This situation is sub-optimal, but can be solved by migrating to
 the 1.0 API, which does require an encoder instance to encode a
 comment, and thus does not have this problem.

Fixes #726.

svn path=/trunk/theora/; revision=17994

examples/player_example.c
include/theora/theora.h

index db49cb1..96df249 100644 (file)
@@ -654,14 +654,14 @@ int main(int argc,char *const *argv){
     th_decode_ctl(td,TH_DECCTL_SET_PPLEVEL,&pp_level,sizeof(pp_level));
     pp_inc=0;
 
-    /*{
+    {
       int arg = 0xffff;
       th_decode_ctl(td,TH_DECCTL_SET_TELEMETRY_MBMODE,&arg,sizeof(arg));
       th_decode_ctl(td,TH_DECCTL_SET_TELEMETRY_MV,&arg,sizeof(arg));
       th_decode_ctl(td,TH_DECCTL_SET_TELEMETRY_QI,&arg,sizeof(arg));
       arg=10;
       th_decode_ctl(td,TH_DECCTL_SET_TELEMETRY_BITS,&arg,sizeof(arg));
-    }*/
+    }
   }else{
     /* tear down the partial theora setup */
     th_info_clear(&ti);
@@ -766,8 +766,8 @@ int main(int argc,char *const *argv){
              keyframing.  Soon enough libtheora will be able to deal
              with non-keyframe seeks.  */
 
-          if(videobuf_time>=get_time())
             videobuf_ready=1;
+          if(videobuf_time>=get_time());
           else{
             /*If we are too slow, reduce the pp level.*/
             pp_inc=pp_level>0?-1:0;
index 5592e90..a729a76 100644 (file)
@@ -496,7 +496,11 @@ extern int theora_encode_header(theora_state *t, ogg_packet *op);
  * \param op An ogg_packet structure to fill. libtheora will set all
  *           elements of this structure, including a pointer to the encoded
  *           comment data. The memory for the comment data is owned by
- *           libtheora.
+ *           the application, and must be freed by it using _ogg_free().
+ *           On some systems (such as Windows when using dynamic linking), this
+ *           may mean the free is executed in a different module from the
+ *           malloc, which will crash; there is no way to free this memory on
+ *           such systems.
  * \retval 0 Success
  */
 extern int theora_encode_comment(theora_comment *tc, ogg_packet *op);