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

Compliant version is not optional, so it has to be int.

Just to make sure we're on the same page here, if you split GL.GenTextures() into GL.GenTexture() and GL.GenTextures(n), this must be consistent throughout the whole API. e.g. Currently alSourcei/alSourcef (1 value) and alSource3f, alSourcefv, etc. (arrays) are compacted into a single function, taking advantage of overloads. We cannot make GenTextures an exception and leave the rest as is. We need AL.Source and AL.Sourcev too. AL.SourcePlay and AL.SourcePlayv aswell. It is by far not restricted to these examples, the changes will be so gigantic that it should probably be a separate branch.

This will also make it more complicated to use the API, and affect the demands for documentation.

At least in my opinion it is not feasible having this inconsistent. If we start making exceptions for 1 function, but not the other we will spend too much time discussing which functions deserve it, and which not. Those kind of philosophic discussions are a waste of time and heavily counter-productive.

Compacting similar functions into 1 and taking advantage of overloads is one of the concepts why people use OpenTK, you cannot just throw it overboard because you're in the mood.

objarni's picture

Personally, I'd like to remove all the array versions, since it is trivial to implement array-functionality ontop of non-array versions. That way it would be very few overloads indeed.

But I think I have to many voices against me there, so what is your opinion on just adding these for each named object type:

         [CLSCompliant(true)]
        public static int[] GenTextures(int n)
        {
          int[] textures = new int[n];
          GL.GenTextures(textures.Length, out textures[0]);
          return textures;
        }
 
        [CLSCompliant(true)]
        public static void DeleteTextures(params int[] textures)
        {
          GL.DeleteTextures(textures.Length, textures);
        }

This would support almost what I'm looking for:

// Single texture name
int tex = GL.GenTextures(1)[0];
GL.DeleteTextures(tex);
// Multiple texture names
int[] texs = GL.GenTextures(5);
GL.DeleteTextures(texs);
Inertia's picture

There is no problem adding overloads like this:

public static int GenTextures();
public static int[] GenTextures(int n); // would prefer uint, but CLS compliance makes Fiddler happy, which outweights preference ;-)

Adding new functions to the API should really be a rare case, and if at all the name must be easier to differentiate e.g. something like GL.GenerateTexture. GenTexture and GenTextures would also be annoying to use with Intellisense.

objarni's picture

Yeah, I'd prefer uint version too :) Fits my C# mind better. But OpenTK is targeting .NET in general, so have to make those VB:ers happy too, I guess.

OK, I'll continue this project tomorrow (I'm writing a code generator to do the hard work for me, so it's no sweat changing how the methods are designed finally.

Inertia's picture

Indeed, uint makes more sense since the returned handle is always >0, and typically you don't want to call GL.GenTextures(-1) either. ;)

You are right that less overloads might not hurt (some GL functions have alot, due to the generator having worse taste than we humans do), but OpenTK really needs to provide the same functionality as the C APIs do. It'd take alot more user contributions to lift the book to a level where it can exist without referencing existing C documentation (no complaint, just a fact) and there's really have no choice but providing all means to the users to be able to turn C code into C#.

Hopefully that doesn't sound like a lecture again, just trying to explain why we cannot go wild on improvements.

objarni's picture

No sweat! I'll try to nagg a just slightly less - I realize a little bit better now how much work it is if we want to be consistent on the API level, now that I've browsed the source code a bit.

What I hope is that we can make the best possible of OpenTK! Finding the right balance between implementation effort and elegance/performance/featurerichness is what it's all about..

objarni's picture

OK, I've kind of given up on this. :)

Changing the Gen/Delete of some/all named objects of GL/AL would require lots of refactoring of the OpenTK library, at least if we try to stay consistent throughout the API, and not clutter IntelliSense too much.

Inertia's picture

Added Gen/Delete overloads in the requested style. CLS Compliant ones only for now, because they are not optional.

Couldn't find any references to ALuint in public documentation, care to specify file/line?

objarni's picture

Thanks!

Yeah I guess we'll have to live without the overloads in uint variants, because of the C# restriction on method signatures only using parameter types, not return types.

Did you add Gen/Delete methods for all mentioned object types above? Textures, Sounds, Queries etc.?

One example of ALuint in the documentation is AL.GenBuffers(). But I am using a binary distribution of OpenTK (0.9.0) -- maybe it's been fixed in the SVN already?

Inertia's picture

Only for AL. I wouldn't recommend doing this for GL, it clutters the function with minimal use overloads. Worst is, there's tons of duplicate summaries which are bloating the documentation. It's quite uncomfortable now navigating in the AL.cs file, because there's tons of code which look identical (i.e. differ only by "ref" or "out").