objarni's picture

Some OpenAL reflections

Hi there!

I tried out the new AL API of OpenTK tonight, it stopped when downloading alut.dll was not enough to kickstart a simple Alut.Init()/OpenTK0.9 windows forms application.

I'm new to OpenAL, so I'm approaching the AL API with a "C#/OpenTK"-mindset.

Sorry if I sound rant-ish! I just want to express my opinion. Here we go:

1. AL.GenBuffers(out uint bufferid): maybe GenBuffer without 's' is better name..? Same with GenSources(out uint sourceid) and DeleteSources(..)
2. IntelliSense-documentation refers to "ALuint"'s and not uint, which are used in reality. In general,
the IntelliSense seems more "c-ish" than "OpenTK-ish" to me :)
3. Is it really necessary to error-check everything all the time..? Could we not have some kind of exception system? I think error-polling is so tedious, it gets really tempting to either
a) skip it altogether (not good)
b) write a thin AL-wrapper around the OpenTK-AL class (not nice either)
4. Alut.Init() returns a strange enum type called "AL.Bool" -- why not use .NET's bool type instead?
5. Why does AL.DeleteSources() take a ref to an uint instead of just an uint? If I want to set the id to 0, I'll rather do it myself.
6. I would like GenSource() to take no out parameter, just return a uint.
7. I would like GenSources(int) to take the number of source id's to generate, and return a uint[].
8. 6-7 applies to Buffers too. This is more C#-idiomatic, out and ref feel very C-idiomatic.


Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
teichgraf's picture

The other issue is how to download all the xml files in the first place - write a script that visits http://opengl.org/sdk/docs/man/ and retrieves any link that ends with .xml?

There are some tools out there, which can download whole webpages and directories. So searching has only to be performed on the local harddrive.

But no one wants to reinvent the wheel and maybe it is possible to ask the guys from PyOpenGL to get their tool or the people at OpenGL.org how they build their XHtmls?

Inertia's picture

The stuff from opengl.org has a tag "DocBook XSL Stylesheets V1.69.1" http://docbook.sourceforge.net/

There's 2 major problems to solve though:
1) The pages use custom fonts for equations. (PyOpenGL docu keeps this font requirement. Bad thing, won't be of any use for IDE inline docu - and if you have to fire up the webbrowser anyway, why not go directly to opengl.org?)
2.a) OpenTK's enums are not considered by those docs and require special treatment.
2.b) Keep GL_FOO or format it to Foo?

the Fiddler's picture

1) Ok, so we drop the remarks section and only add summary and parameters in the inline docs. The remarks aren't visible inline anyway.

2.a) This is a problem. Possible solution: lookup the GL_XYZ tokens in the specs and find the correct enough. This won't work with xslt though.

2.b) Replace it with Foo. The rules aren't very complicated, but I don't know if they are possible with xslt either.

I think the generator will be able to handle these transforms, but I don't really want to touch that program right now (it could really use a heavy update with LINQ).

BlueMonkMN's picture

C-like languages (and VB come to think of it) do not allow functions with the same name and parameter list to return different types because the compiler would not know which "overload" to call in cases where the return value is ignored. I would suggest keeping the CLSCompliant version because I don't think anyone cares if the value is signed or unsigned; it's just a black box value to refer to a texture (I'd almost suggest using the type IntPtr to convey that because IntPtr is intended for handle values like these) so might as well stick to a return type that all CLS compliant languages/clients can handle.

the Fiddler's picture

C-like languages (and VB come to think of it) do not allow functions with the same name and parameter list to return different types because the compiler would not know which "overload" to call in cases where the return value is ignored.
That's a design decision that I'm not sure I agree with. The compiler already generates an error for ambiguous overloads:

void Foo(Stream s) { }
void Foo(FileStream s) { }
 
Foo(null);             // compiler error - ambiguous 
Foo((FileStream)null); // works ok

By the same token, there's no reason why this shouldn't work:

int Foo() { }
uint Foo() { }
 
int i = Foo();
uint j = Foo();
Foo();         // compiler error - ambiguous
(uint)Foo();   // no error

In any case, I agree: we should keep the CLS-compliant methods for return values.

Actually, in most cases it doesn't matter if you pass an int or uint, as the (uint)(int)(uint) conversion is non-destructive. The CLS-compliant overloads only matter in a few functions like GL.LineStipple, where the conversion from (u)int->ushort may yield different results than (u)int->short.