I have some requirements :
Be accessible through every language that can call C-style APIs, including script languages.
Have relatively small list of API functions.
Be able to utilize an IDE code completion and restrict the possible options to the current context.
Be restrictive to the parameters and deny compilation if they do not make sense to the context.
The header file should be simple and easily translate-able to other languages, so probably pure C interface like OpenGL, OpenAL etc.
basically I think there are several approaches to such an API design. For example the first one.
include the needed operation in the API function name
SetEntityPosition3f(Entity* ent, float x, float y, float z) ;
this set only the entity position and can't set the entity scale by mistake, but unfortunately leads to very bloated API list - for every single operation -a different function.
Another approach is make something like (OpenAL/OpenGL) etc.
#define AL_POSITION 0x1004
alSource3f( ALuint sid, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3 )
And the usage
alSource3f(0 , AL_POSITION,x,y,z);
But unfortunately the user could make a mistake and write
alSource3f(0 , AL_STOPPED,x,y,z);
which will compile just fine - ALenum is just an int. Also using the code completion would be hard to find the right parameter - AL_...are many and 'global"
Another approach is to use something like :
in the header
struct TransformType
{
enum Param
{
Position,
Rotation,
Scale
};
};
EntitySetTransform3f(Enitity* ent, TransformType trans, float x, float y, float z) ;
And usage
EntitySetTransform3f(entity, TransformType::Position , 10,10,10);
Here code completion will list only the transform parameters, but header is polluted with structs with enums
and I'm not sure how they could be translated to different languages.
Which one do you prefer the most ?