[Theora-dev] libogg2 branch->trunk (deadline: 5/30)
arc at Xiph.org
Thu May 26 21:23:48 PDT 2005
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:
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.
More information about the Theora-dev