[Openal-devel] 1.1 draft spec

[Joe Tennies]

On Sun, 2005-02-20 at 14:02 -0800, Garin Hiebert wrote:
> Great feedback -- comments below (I'm not dismissing the ones I don't 
> comment on -- I just don't have anything to say on those yet):
> 
> > Overall, I find the omission of "AL" and "al" more ugly than it's 
> > worth for saving some characters. Especially since it's inconsistently 
> > done throughout the docs. I know GL does it, but I don't think we 
> > should, especially since some names clash with other APIs (e.g. 
> > Windows' GetProcAddress).
> 
> I agree -- I was trying to switch the entire document over to 
> explicitly listing the actual API call names.  I'll need to track down 
> the remaining omissions.
> 

I believe I actually did this in the update I sent Garin (may have
missed a couple)

> > 1.4
> > Implementations of 1.1 shouldn't support the extensions listed as 
> > extensions - they should be rolled into the core. Either that or keep 
> > them as extensions, in which case an implementation wouldn't have to 
> > support them.
> 
> A restructuring of the document is probably a good idea.  It should 
> probably have all the listed extensions in the core document, perhaps 
> with a short "extensions" section saying how an application written to 
> AL 1.0 can query for the 1.1 extensions properly.  It will take some 
> thought to make sure that it doesn't cause any problems to do things 
> this way, but it should work...

I disagree completely.  I think the 1.1 specification should have only 2
goals
      * Clarify the things that were not explicitly defined in the 1.0
        spec (like the doppler effect)
      * Define the direction in which the library is heading by
        standardizing certain extensions to be implemented

There is really only one reason for this... backwards compatibility and
forwards compatibility.  If OpenAL 2.0 ever comes about, then please
redo what needs to be redone.  In the mean time OpenAL 1.0 code should
work on an OpenAL 1.1 library.  OpenAL is quite extensible.  The 1.1
spec adds only several functions and a probably somewhere in the teens
of new tokens (which many 1.0 implementations already implement).  I
also think you should be able to code a 1.1 program to easily work on a
1.0 library.

I believe this is the way OpenGL does it, and I really commend them for
it.  I can write code and just ask for the things I need and not really
care which version of the library it is.  Let's say I need the Capture
extension (new icculus version, not old Sierra one) but not the Linear
model.  Should a person with a 1.0 library that implements the Capture
extension not work?

So I guess I'm saying "OpenAL finally has decent momentum should we put
the user through the issues of keeping both a 1.0 library and 1.1
library around?"

In the spec, a "required extensions" and "non-required extensions"
section would be quite useful.

> 
> > 4.3.2
> > AL_SOURCE_RELATIVE explicitly only applies to positions, not 
> > velocities. There should be a way to specify source velocities 
> > relative to the listener's orientation and velocity if there is one 
> > for positions. Consider deprecating the name and adding 
> > AL_SOURCE_RELATIVE_POSITION and AL_SOURCE_RELATIVE_VELOCITY. In fact 
> > shouldn't these actually be called listener-relative anyway?
> 
> I've never liked these names either -- comments from anyone else?
> 
> > 4.3.4
> > Should only have "v" "Get"s.
> 
> > 5.3.2
> > Should only have vector forms of "Get" commands.
> 
> I'm not so sure about this.  People who like use the "v" functions for 
> everything can do so if they wish, but it's going to seem silly to many 
> existing AL 1.0 programmers...  Comments from anyone else?

I agree completely with leaving the non-vector versions in.  But that
should be obvious as I want backwards compatibility.  This is especially
true as OpenGL has these (I believe) and there are plenty of occasions
where non-vector values will be requested (most potentially in
extensions).

> 
> > 9
> > Extension naming should match OpenGL (even though I think that's 
> > uglier). e.g. ALC_EXT_enumeration and ALC_EXT_capture. In general, 
> > should these even be defined here? The GL spec lists ARB extensions, 
> > but once those have been rolled into the core they're no longer 
> > documented here. However since we're producing a new core revision at 
> > the same time, is there any need to produce extensions for these 
> > things (like linear distance?) Any implementation that wants to 
> > support these is likely to be upgraded to a 1.1 implementation anyway, 
> > in which case we may as well just add them to the core as new features 
> > instead of producing extensions for them. Also, if these are to stay 
> > as extensions, the identifiers need to have EXT added to them as 
> > appropriate.
> 
> I picked all-caps for the names only because I thought it looked 
> better, but I have no problem going either way on that decision.  Like 
> I said above, I don't immediately have any objection to killing all 
> these as "extensions" if nobody can come up with a reason why that's 
> bad (although we may still want to have it both ways -- "core" _and_ 
> exposed as extensions).
> 
> > 10
> > Not much point having these in the spec, they're 
> > implementation-specific and are likely to be out of date before long. 
> > Plus they're obviously in a state of flux from the embedded comments 
> > :-)
> 
> Probably true -- I dumped them in there to see if there were any 
> comments pro or con...  Now there's one comment "con"!
> 
> Thanks!  I'll be incorporating all the feedback early next week and get 
> a new draft up quickly...

I'll second leaving them out.  I think an appendix of all the functions
and tokens would be much more useful.

> 
> Garin
> 
> _______________________________________________
> openal-devel mailing list
> openal-devel at opensource.creative.com
> http://opensource.creative.com/mailman/listinfo/openal-devel
>