[Theora-dev] libogg2 branch->trunk (deadline: 5/30)

[Arc]

Ok guys and gals

Monty assigned me as libogg2 maintainer a few weeks ago, with the 
provision that I get consensus on API changes from everyone.  In order 
to facilitate discussion, and to "move on" vs letting this stalemate 
hold development at a stand still, I'm setting an initial deadline of 
this comming Monday, May 30th.

If nobody has a strong objection why these API changes should not be 
made, noting fully that libogg2 is still *ALPHA* and only really used by 
py-ogg2 and my own development code in it's current state, these changes 
will be pushed to trunk and further work will continue on branch.

If anyone has a strong objection it should be sent to the [ogg-dev list] 
by Monday May 30th 23:59 GMT along with an full explaination.  Said 
person should also specify a time Wednesday to discuss it on IRC either 
before or after Xiph's monthly meeting. 

This is not to say that such changes cannot be reverted.  libogg2 is not 
released yet and there will be pleanty of time for more debate for those 
who are interested in debating the nuts and bolts.  However, this *WILL* 
represent the direction and basis for development to continue toward the 
goal of getting a public release, so if you have an objection, it would 
be appreciated to state it now.

Again, discussion should continue on the ogg-dev list.  Not vorbis-dev, 
#Vorbis, etc.  Any IRC discussion on this should be in #Xiphmeet at an 
advertised time and logged for everyone who couldn't attend to read.  If 
you are not on ogg-dev already and are interested in libogg2 development 
you should join it now at http://lists.xiph.org/mailman/listinfo/ogg-dev

In order to further facilitate everyone's ability to be informed I'm 
laying out an outline of which changes are actually being made:

I. Debated API elements:
 A. To my last knowledge there was *STILL* a debate going on re discont. 
    codecs, even though these have been published by Monty months ago.  
    A part of this debate the following API additions have been debated:

    within ogg2_packet struct:
     ogg_int64_t    top_granule;
     ogg_int64_t    end_granule;
    vs 
     ogg_int64_t    granulepos;

    This, Monty proposed, allows for smarter packet->page handling than
    just having the meaning of granulepos differ for different streams.
    *THIS IS NOT* a change to the Ogg bitstream, only one granulepos is 
    actually recorded in the resulting page header, providing both of 
    these is just for libogg2's and the codec's internal use.

 B. Discont. function added:
     extern int      ogg2_stream_setdiscont(ogg2_stream_state *os);
  
    This simply sets a flag which turns a stream to discontinuous mode,
    meaning the packet's top_granule value, not end_granule, will be the
    one which is used in the page header. Even if the packet were to use
    just one granulepos value this is nessesary as we want to use the 
    first packet's granulepos, not the last, when multiple packets are 
    in a single page.  This is only usable before Packet#1 is processed,
    so a codec needs to be able to be detirmined to be cont/discont 
    based only on the information aquired from Page0/Packet0.  An error
    is generated if this change is requested later in the stream.

    The debate is not over wether this is a good way of doing it, but 
    rather, wether treating different codecs/streams differently is a
    good idea.  Before you argue this you had better read Monty's full
    documentation on this since it was published months ago.


II. Undisputed API changes and extentions
 A. Namespace change
   One of the very good ideas to come from the Annodex crew was to 
   provide libogg1 backwards compatability.  Toward this goal all 
   libogg2-specific functions and structures have been renamed so that,
   in the near future, functions and structures with the same name as 
   the libogg1 functions/structs they emulate can be added.

 B. Page header manipulation functions
   In libogg1 doing a quick transform, ie rewritting a stream's serialno
   for chaining to avoid conflicts, simply involved changing a value in
   the ogg_page structure's header buffer.  However, libogg2 doesn't 
   permit such manipulations easy, forcing a transformation to packets
   and back (and decoding for granulepos resetting, etc etc).

   I added a set of ogg2_page_set_* functions to restore this:
    extern void     ogg2_page_set_continued(ogg2_page *og, int value);
    extern void     ogg2_page_set_bos(ogg2_page *og, int value);
    extern void     ogg2_page_set_eos(ogg2_page *og, int value);
    extern void     ogg2_page_set_granulepos(ogg2_page *og, ogg_int64_t value);
    extern void     ogg2_page_set_serialno(ogg2_page *og, ogg_uint32_t value);
    extern void     ogg2_page_set_pageno(ogg2_page *og, ogg_uint32_t value);

 C. Added missing function
   This was simply missing and, thus, added:
    extern ogg2_buffer_state *ogg2_buffer_create(void);

 D. Changed name of include
   To go along with changes in II.A. an ogg/ogg.h would need to be made
   available for backwards compatability.  In order to keep everything 
   tidy I have moved ogg2/ogg.h to ogg/ogg2.h so that the other ogg/*.h
   includes (config_types.h and os_types.h specifically) which are 
   shared don't have to be duplicated.

-- 

Diversity is the Fuel of Evolution, 
 Conformity it's Starvation.
Be Radical.  Be New.  Be Different. 
Feed Evolution with Everything You Are.