Some OpenAL reflections
Posted Thursday, 13 March, 2008 - 20:49 by objarni inHi 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
Re: Some OpenAL reflections
Yeah, it's a pain in the a-e to copy/paste the same comment for 3 different overloads, and maintaining the soup it becomes. It would be much simpler if you could "name" comments and refer to them in other summaries..
Have anyone heard if there is any such support in any of the C# compilers?
Re: Some OpenAL reflections
There is support for using external files with the "include" tag. I'm not sure if that's more maintainable though.
Re: Some OpenAL reflections
Here is an example of an include we use for IXmlSerializable. We have had much less trouble with includes than trying to keep common documentation in sync when contained in the source files.
/// <include file='../CommonDocumentation.xml' path='CommonDocs/IXmlSerializable/member[@name="ReadXml"]/*'/>Re: Some OpenAL reflections
Looks Microsoft-ish, but it's better than copy-paste :)
Re: Some OpenAL reflections
OpenAL doesn't have so many functions that it becomes a problem, it's just confusing (because I like to memorize a code sections shape rather than reading it over and over again when looking for something). I'm using #regions heavily to keep the code somewhat grouped, but personally I'd be more happy with a non-CLS-Compliant-"ref uint"-only subset of the bindings. It was discussed to use preprocessor directives to allow users to build OpenTK.dll in their favorite type flavor, but I'll write some more OpenAL apps before making any comments on whether the required amount of work is worth the gain. Once you know the functions and their overloads it's much simpler to just type the whole parameters in and don't bother with Intellisense.
However for the OpenGL documentation it might be best to use an external file to pull the documentation from. 1500 funcs+overloads is quite a bit.
P.S. The "new" overloads pose another problem:
...will compile without error or warning.
Re: Some OpenAL reflections
Not really, the compiler would complain on "Use of unassigned local variable 'MySource'".
The "old ones" would allow:
No errors or warnings here.
Re: Some OpenAL reflections
You'll get an access violation at runtime. Using the 1-handle-at-a-time overload will never ever complain though.
Doesn't look very suspicious. Will compile. Will run. Will not work.
P.S. Your example is horrible coding practice though, the compiler should slap people who hardcode 2 magic numbers in 2 consecutive lines by default ;)
Re: Some OpenAL reflections
Offtopic:
I think it is possible to generate the OpenTK.GL Intellisense doc automatically with a tool, which would parse the OpenGL manpages. They are all written in a defined layout with a defined document name (e.g. http://www.opengl.org/sdk/docs/man/xhtml/glGetString.xml, ...). Maybe a tool isn't really needed for this and a XSL-transformation would be sufficient.
Re: Some OpenAL reflections
Methods that return values, also known as functions, is a fairly popular "design pattern". I don't think it will get in the way nearly as much as writing:
The latter way of writing is not very popular in C#. For example, compare how many of the built-in .NET APIs use
outorrefto the number of APIs that use pass-by-value and return-by-value. But all of this has been stated previously in this thread.Re: Some OpenAL reflections
@teichgraf: offtopic, but I've been thinking about this. I won't time to play with that in the foreseeable future, but I think it's possible (and would be quite awesome). MathML aside, an xslt should be sufficient (that's how the pages are created on opengl.org). 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?
It looks like the PyOpenGL guys have actually managed to do this, and their manpages are quite nice.