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.
objarni's picture

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?

the Fiddler's picture

There is support for using external files with the "include" tag. I'm not sure if that's more maintainable though.

djk's picture

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"]/*'/>
objarni's picture

Looks Microsoft-ish, but it's better than copy-paste :)

Inertia's picture

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:

int[] MySource;
AL.GenSources(5);
AL.Source(....

...will compile without error or warning.

objarni's picture

Not really, the compiler would complain on "Use of unassigned local variable 'MySource'".

The "old ones" would allow:

uint[] sources = new uint[1];
AL.GenBuffers(10, out sources[0]);

No errors or warnings here.

Inertia's picture

You'll get an access violation at runtime. Using the 1-handle-at-a-time overload will never ever complain though.

AL.GenSources();

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 ;)

teichgraf's picture

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.

objarni's picture
int source = AL.GenSources(); // I'd prefer GenSource() but you're the boss..

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:

int source;
AL.GenSources(out source);

The latter way of writing is not very popular in C#. For example, compare how many of the built-in .NET APIs use out or ref to the number of APIs that use pass-by-value and return-by-value. But all of this has been stated previously in this thread.

the Fiddler's picture

@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.