Horde3D

I'm not a member of the fanclub for these prefixes in the enums, I think they obfuscate and clutter the simplicity of the engine:



My suggestion would be to split it up:



But I really think these enums should be changed to defines or consts altogether, some languages don't support enums so a binding needs
to define all these values as constants anyway.

I would rather see a more traditional:

#define H3D_ParticleEffectResElems_ParticleEffect 800
#define H3D_ParticleEffectResElems_ChanMoveVel 801
...

or even

const int h3d_ParticleEffectResElems_ParticleEffect = 800;
const int h3d_ParticleEffectResElems_ChanMoveVel = 801;
...

The primary issue is that there are names that appear in more than one parameter list, and the prefix allows one to cleanly differentiate between them.

I am not sure what the big deal is (but obviously it is a big deal, since you are the third person to bring this issue up). Enums like this are a convention for C++ software, and most other engines do the same:

#defines for constants are just bad, and you won't see them recommended much these days, because of the way they fail to respect scoping rules, and overwrite tokens in inner contexts.

As for binding to other languages, many languages don't support #defines or const int's either, so I don't see what we would gain there. I mean, enums are just a convenient way to organise integer values, so you are free to bind them however you like:

_________________
Tristam MacDonald - [swiftcoding]

The enums are surely the most elegant way to define the values in C/C++,
but current struct+enum has some disadvantages in my opinion targeting other languages than C++:

- SWIG can't cope with the duplicate names.
- It's using structs as a namespacing workaround.
- The struct definitions are in the global namespace, the functions in the Horde3D namespace.

Looking at the Ogre and Irrlicht enums, they prefix all values with the shortened "enum name" as well.

So this might be a possibility:


It's also more simple to write a converter for this to another language.

I agree with swiftcoder. Enums are certainly more modern than constants or defines that have no type safety at all. I think it is just a bit nicer to have the enums wrapped in a struct than having the long enum names. It gives a better impression of grouping and is more suitable for code completion (like intellisense).

Regarding portability to other languages: Most modern languages have some way to express that "grouping". If some language does not, just use the group name as prefix with an underscore. I think it is not a problem if the API syntax is slightly different in different programming languages. Furthermore, the API is quite small and easy to port by hand, so automatic conversion using SWIG should not be the main argument for a style decision.

I agree that the prefixes won't win the price for the most beautiful syntax but I don't think that they clutter the API. They make clear which parameter can be used with which function (e.g. setParamI or setParamF), so they improve the clearness. Another option would be to put all different parameters in different enums (like MaterialDataFloatParams) but that gives even longer names and makes programming less convenient since you always need to know in which enum the desired parameter is.
Instead of using the prefixes, we could also choose a more verbose syntax like:



But that increases the length of the names again and I think the other variant is a bit clearer once you know what the prefixes mean.

Slightly different idea: Elements get the suffix Elem, streams the suffix Stream and parameters just get the type as suffix (I, F, Str).



This makes clear what an enum member may be used for, the average name length is not much more and it looks a bit nicer than the prefix+underscore approach.

It may look nicer (not bothered personally), but it isn't nearly as easy to read.

_________________
Tristam MacDonald - [swiftcoding]

I like it! It also matches more with the function name scheme (getResourceParamI/F/Str etc).

Whatever naming convention we use for the resources should probably be taken over for the scene node params as well. In the end it is mostly an aesthetic thing, however I think it is worth spending some thougts on the decision (we want a nice, efficient and easy to use API for Horde ). To summarize, we have the following options:


I would probably prefer 6. It is the option which makes the type info least dominant.

Option 3 is probably too similar to the C++ convention for naming abstract interfaces.
On the flip side, the type information is pretty important - it isn't exposed in any other way for most of these.

_________________
Tristam MacDonald - [swiftcoding]

Yes but I think it is rather required as a hint. If you use Horde for some time you know what parameters have what type. Furthermore, it is quite clear for many parameters anyway (e.g. it is clear that names are string and something with "count" is int).

Actually I really like the suffix (without underscore) convention. It gives the required info and does not clutter the API's look&feel. So to bring that long discussion to a good end I have finally changed all the enums in the svn now. The struct names are shorter as well and everything got the prefix H3D.

EDIT:
Here is the updated documentation.
Feedback and suggestions are still possible until we bring out the API with the next point release.

looks great to me, thanks. Only one issue, the getNodeParamF/setNodeParamF now take an extra argument compIdx,
is this only for the ColorF3 ? I like the H3DLight::Col_RI Col_GI Col_BI params better, you can easily set them independently and no need to clutter the float functions (the I variant doesn't have compIdx).

I kind of think a separate setNodeParam3f wouldn't go amiss for this situation. Would save the complaints from the Ogre guys

_________________
Tristam MacDonald - [swiftcoding]

There is still another parameter that takes a vector and the resources have a few vector params as well. The reason that only the F functions have the component index is that only floats can have vector semantics. BTW, of course you can still set the color components idependently.


Yeah that would be an option as well. But what about getNodeParam3F? It would require pointers to store the values which is also not so nice, especially for non-C languages.

I don't think it would be so bad - python/ctypes allows pointers to be passed very cleanly, at least.

_________________
Tristam MacDonald - [swiftcoding]