Sign in to follow this  
Samurai Jack

How to write an API? Design tutorial?

Recommended Posts

Greetings! I was wondering, are there any guidelines on how to create an API? I tried many times to write my own engine but there is allways something I do not like about the interface. For example I do not like Ogre3D or Irrlicht because they almost force you to derive from their baseclases to start an application. Some APIs you just plug in when required and you can use them like plain C. OpenGL for example. You just initialize it and call glBegin() .. glEnd() that's it. No derivations what-so-ever. Because of the object oriented nature of DirectX I do not like that some base variable IDirect3DDevice9 etc.. are lying arround in my global splace of a .lib or .dll. I would like to have them encapsulated. But on the other way, i would like to avoid this:
class CMyRenderDevice : public CMySingleton<CMyRenderDevice>
{
...
public:
bool BeginScene(void);
bool EndScene(void);
}

bool engineBeginScene(void)
{
CMyRenderDevice().GetSingleton().BeginScene();
}

bool engineEndScene(void)
{
CMyRenderDevice().GetSingleton().EndScene();
}
Any suggestions or even better tutorials how to achive souch things in the most elegant way? Thank you in advance!

Share this post


Link to post
Share on other sites
Quick question first, are you trying to get a Graphics API Independet solution, or just something for D3D? If the latter, I have a method to share I was thinking about for a while and started to implement. I don't have time right now to explain, but if you are interested I'll make another post when I'm done with this project plan I have to do right now.

Share this post


Link to post
Share on other sites
Indeed, I just need it for Direct3D. No platform independency no nothing. I just want it to be as simple and efficient as possible. I would just like to avoid to call simple methods that wrap arround classes and do the double work.

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
Consistency is the key, even a bad API becomes much better if it's at least consistent... Decide how to handle things, how to format things, etc. and then stick to it. Should you use exceptions or return values to handle errors? Should names be separated by underscore or CamelCase? Don't mix, it will only become confusing in the end.

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
N00b, learn more about Ogre3D than just looking at the ExampleApplication-Framework.

And one thing, forget about C++ and OOP you're definitely the C-gui and then forget about winapi too, cause it's using an object based approach, something you dislike too (regardin your opinion on directx).

Share this post


Link to post
Share on other sites
Hm, I like Winapi very much, because I do not need to include a lot of stuff to get it working. Just <windows.h> and some simple calls and I can start with a running window. No 10.000 includes, 20 libraries, no utilities no nothing. You just take it and use it - and it works.

Okay, It might have too many parameters, but it is very easy to bypass then with just NULL and that's it when not required.

But I do not like the concept of frame listeners like in Ogre or Irrlicht. I would just like to init, enter the loop and leave, with resource management etc...

In theory the basic idea of an engine is, that you just pass the parameters to the engine and everything else goes by itself - ogre is exactly that, but I would like an API more than OpenGL with functionality like DirectX.

I have written a lot of classes for DirectX but at the end, I almost never reuse them in projects, because I dislike this and that, I do not like the coding convetion, should I use namespaces or not, should it be a Lib or a DLL bla bla. Too much of balast.

I was hoping for a straigt forward idea, a plan I could stick to.

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
something i've always done (and still like to do) is to look at other people's code. try to get hold of SDKs of major game/graphics engines and see how they're doing it. i remember having looked at the unreal public source (that included game code and engine interface code) in the early days of unreal. personally i like how epic is going about designing their interfaces (which favor return values for error detection and a more or less flat hierarchy) so that's a good place to start. also i recommend looking at the stuff being released for the lithtech based games (especially no one lives forever etc). there are articles out there describing the interfaces exposed by lith. lith relies heavily on message passing for almost everything that's going on in the game engine, renderer etc. lith is a good example of how to keep things seperate and let modules communicate via messaging.
you'll see more of the d3d related stuff in the unreal public source, though. i even believe there's d3d and opengl specific code in it, demonstrating the (very shallow) level of abstraction in the unreal engine.
it'll definitely get you inspired at least. i don't recommend copying anything you see there, but to get a feel of how you might go about structuring your apis, looking at those two engines (their public interfaces, that is) is something i suggest. helped me a lot to get a feel of "what should be where".

hope that helps a bit,
cheers, simon.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this