[Theora-dev] decoder init/clear

[Michael Smith]

On 8/5/05, Timothy B. Terriberry <tterribe at xiph.org> wrote:
> Michael Smith wrote:
> > Where practical, I think the library shouldn't crash due to bad input.
> >  Fix the library.
> 
> My personal opinion is that if you do stupid things, the library should
> blow up (and severely) as soon as possible. So crashing seems perfectly
> reasonable to me.

Perhaps. I guess that the tendency of programmers to never bother
actually checking return values is a point against trying to just
return an error value.

> 
> Now, about redesigning the API to allocate structures for you (to make
> such blowups happen in an easier-to-check-for place, etc.), well, I
> think that's a fantastic idea. In fact theora-exp already does this for
> structures that are not solely data containers. It has the other nice
> benefit that you can change the internal size and workings without
> having to rev the API version and dynamically linked code still works.
> But Ralph and others currently want to punt on introducing API changes
> until after 1.0. I believe I've already expressed my own opinion that
> beta1 is the best opportunity to give libtheora a sane API.
> 

Agreed - the "alpha" designation pretty clearly says "this isn't
stable, and things might change", at least to me. I think at the very
least we should provide variants that allocate these structures for
you, and deprecate the existing functions (but still keep them, unless
there's a compelling reason not to) - but keep them up to and
including the final 1.0 release. Perhaps a documentation note saying
that binary incompatibilities may be introduced if you use the
deprecated versions?

I guess there's a fair bit of work to be done to make that truly
useful, though - the theora_info struct, for instance, has lots of
encode-side parameters that a future encoder revision might want to
remove or add to, but given the current API this needs to be a public
structure (rather than merely an opaque pointer) for access to the
decode-side members like width/height/etc. So I'm guessing there'd be
a fair bit of internal reorganisation to do to really get to the point
where we can revise all these structures without badly breaking binary
compatibility.


Mike