BlendELF, Tutorial 8, C++ SDK

This tutorial should give you the basic idea of how to use the BlendELF C++ API. Note that this tutorial is meant for only those that want to use BlendELF with C++. The C++ API for BlendELF is by no means any more complete than the Lua API, so the C++ is by no means to be considered "the advanced API". The APIs are almost identical as you can see from this tutorial.

Only thing needed is the BlendELF Development Kit. Download it from http://blendelf.com if you haven't already.

Here is a short description how to setup VSE 2008 for BlendELF SDK. Pardon me for the briefness of this part. Might rework it with pictures and all when I find to time to do that ;).

Create a new Console Project in Visual Studio
Go to the project settings (probably in Project -> Project Properties)
Go to C++ -> General (before Visual Studio lets you into the C++ section of the settings, you must have a .cpp file in your project) and add a path pointing to the cppsdk folder to Additional Include Directories so that the include file blendelf.h will be found
Go to Linker -> General and add a path pointing to the cppsdk folder to Additional Library Directories so that the library file BlendELF_DLL.lib will be found
Go to Linker -> Input and add a the library BlendELF_DLL.lib to the Additional Dependencies so that the library will be linked to your executable
Copy BlendELF_DLL.dll file into the folder where you run the compiled .exe from (typically Debug or Release folder inside your project folder). The .exe will complain of not finding the file if you do not do so.
Just like in the previous step, please copy all of the .dll files found in the BlendELF Development Kit root folder to where your .exe is, BlendELF_DLL.dll needs to find them.

If you are compiling with linux and using g++ for that, you might want to add the option "-Wl,-rpath,./" to your compile. This way you can just drop libblendelf.so into your projects root folder and the binary will find it. So your command for compiling an application with blendelf would probably become something like this:

g++ main.cpp -Wl,-rpath,./ -L. -lblendelf

Also take into account that you have to tell the compiler where blendelf.h and libblendelf.os are. In the upper example I assumed that both of them are in the same folder that main.cpp is. You can specify separate include paths and library paths with -I and -L flags. The following line: -I/home/myname/blendelf/cppsdk would tell the compiler to search for include files at /home/myname/blendelf/cppsdk .

The C++ API of BlendELF is almost identical with the Lua API, so the API doc of Lua api is pretty much the API doc of C++ too. There are a few easy to remember differences between the C++ and Lua APIs. Lets take a look at a sample BlendELF C++ program.

#include "blendelf.h" int main() { elfInitWithConfig("config.txt"); elf_handle scn = elfLoadScene("level1.pak"); elf_handle cam = elfGetCameraByName(scn, "Camera"); elfHideMouse(true); while(elfRun()) { if(elfGetKeyState(ELF_KEY_W) == ELF_DOWN) elfMoveActorLocal(cam, 0.0, 0.0, -12.0); if(elfGetKeyState(ELF_KEY_S) == ELF_DOWN) elfMoveActorLocal(cam, 0.0, 0.0, 12.0); if(elfGetKeyState(ELF_KEY_A) == ELF_DOWN) elfMoveActorLocal(cam, -12.0, 0.0, 0.0); if(elfGetKeyState(ELF_KEY_D) == ELF_DOWN) elfMoveActorLocal(cam, 12.0, 0.0, 0.0); elf_vec2i mf = elfGetMouseForce(); elfRotateActor(cam, 0.0, 0.0, -mf.x*10.0); elfRotateActorLocal(cam, -mf.y*10.0, 0.0, 0.0); if(elfGetKeyState(ELF_KEY_ESC) == ELF_PRESSED) elfQuit(); } elfDeinit(); return 0; }

Now the first difference that you notice is probably the first function we call, elfInitWithConfig. In Lua we didn't call any init functions, but in C++ we have to since the init function isn't called for us. The next difference is that there is no dot between elf and the name of the function. So elf.GetFps becomes elfGetFps. Also the flags don't have the dot either, and the elf is capitalised. So elf.KEY_W becomes ELF_KEY_W. The variables in C++ have types, so scn = elf.LoadScene("level1.pak") becomes elf_handle scn = elfLoadScene("level1.pak");. Also mf = elf.GetMouseForce() becomes elf_vec2i mf = elfGetMouseForce();, etc... Finally, in C++ programs we have to call elfDeinit manually at the end of our program, because like with elfInitWithConfig, this function isn't called for us.

Thats it! I hope you enjoyed the tutorial, and if you have any comments about it, please post to the forums.