So today was working on more stuff for RocketFrogz, and ran into a tricky situation. Basically I was working with the sprite system which supports animations. You basically do this:

SpriteSheet* s = SpriteSheetType::spriteSheet ("Filename");
s->loadTextures (renderer);
s->signalFrameChanged().connect (functionPointer (this, &Object::frameChanged));
s->setAnimation ("idle");

Whenever the sprite changes frames while running the animation, it notifies you via frameChanged. At the moment, this is a function void f (void) with no parameters. Now i want to load tons of these, but hook
them to the same function. So the signal is going to change to a Signal1 which passes the sprite sheet that changed (this way i can tell which sheet changed, and act acoordingly).

Now the issue:
I have lots of code depending on the old method.

Now I could go back and change all the previous code. I’ve done this before, and generally thats a good thing. However, i’ve ran into this in several places. Timers is another good example : you sometimes want the parameter and sometimes not. So what can i do?

Solutions:
- Deal with it : its a limitation and have to live with it.
- Find some other method to pass stuff around. For example, create an object as a responder, and use that as an identifier.
- Change FP so it can upgrade itself to higher types

I chose the last one.
So what does this mean, upgrade itself? Basically I want a function pointer to be able to represent itself as a higher class of function pointer than what it is, and throw away extra parameters.

As a quick example: basically if i have
void f (void)
i want to be able to do
f (1, 2);
and it just throw away 1 and 2. (using FP, this doesnt help you for direct calls like that)

Doesn’t sound so bad when i put it that way. Qt does something similar with signal/slots, but they have moc to handle those connections : i just have c++, and as you can probably tell : c++ does NOT like flexibility like that.
Its picky enough about regular types, but now i want to relax some of C++’s most fundemental rules about function pointers. Then again, Gail::Core::FunctionPointer was designed completely to work around c++’s rules, so its the place to do it if any!

My key requirements for this:
- No change to previous code. If it worked before with function pointer with direct type matching, it’ll work now.
- Low overhead (if any) in both speed and memory. Function pointers are used everywhere in gail : they slow down, everything slows down. A few bytes can easily add up.
- Ability to upgrade as needed (previously defined)
- Minimal changes to usage : if at all possible, use the exact same syntax as now and just ‘magically’ convert it
- Hopefully no massive rework of FunctionPointer (related to the first point). Its a tad messy atm (mostly because of the power it allows), and i’d rather it not get much worse.

So there were 3 major iterations for this. They mostly did the same thing, but tweaked to fix problems found.

First approach: create the higher level and write the conversion function yourself (cast operator)

This approach was almost perfet. Basically we have a cast operator (operator Type ()) that upgrades a pointer to the higher level pointers. This then points it to the lower level pointer’s ‘run as lower’ function, which then knows how to run the FP as the lower level. So essentially it creates a new FP2 that calls the actual FP1. So run() becomes
FP2.run() -> FP1.run1As2() -> FP1.run() -> <actual call> : pass return back up

Heres the actual return from the operator (just cause i think its one of the coolest lines ever):
return functionPointer<FunctionPointer1<ReturnValue, Param1>, ReturnValue, Param1, NewParam2> (const_cast<FunctionPointer1<ReturnValue, Param1>*>(this), FunctionPointer1<ReturnValue, Param1::runFunctionPointer2As2<NewParam2>);

Little more overhead on the call, but no more memory needed and is essentially the same as what people have to do now. Theirs only one issue. Since your creating and returning the FP2 as the final type, the FP1 is left destroyed on the stack. So if you wait long enough, the FP1 would be destroyed and randomly it would crash on calls. So the problem becomes the lifetime of the original FP1, since it wasnt needed. Other than that, this approach was exactly what i wanted. But you cant deal with FP’s crashing half the time on calls, so something else is needed.

Second approach: use constructors and more helpers to convert types appropriately.

This exploits the fact that a function pointer of a type is always the same size as another function pointer of the same type, even if they have different amount of parameters. We allow a function pointer of a higher level to use a function pointer of a lower level, copies all the parameters into the higher level like normal, but when it runs it switches to the lower level and runs accordingly. So internally, this is something like:
FunctionPointer2 (Return (*function) (Param1))
: internalPointer ( cast<(Return (*) (Param1, Param2))>(function)), numOfParams (1)
{}

Then on run, you check the number of params and run accordingly:
Return run (Param1 p, Param2 p2)
{
if (numOfParams == 2) { return this->operator(); } // normal
else if (numOfParams == 1 ) { return (internalFP1*)(run()); } // degraded pointer
}

Cost becomes an integer pointer per FP, and an int lookup + jump table for figuring out how to run it. Not that bad. So now public side we add more helpers to functionPointer to create these hybrid pointers…
Except c++ cant tell the difference between the various helpers we have now. It cant tell these two are different functions, and requires you to specify.
FunctionPointer2<Return, Param1, Param2> functionPointer (Int8* null, Return (*function) (Param1))
FunctionPointer1<Return, Param1> functionPointer (Int8* null, Return (*function) (Param1))

Ouch. So rename them all to have the number in the name (such as functionPointer2), and reserve ‘functionPointer’ for ones that completely match the type.
Not that bad, but it does require us to think every time we create a function pointer. And everyone knows, thinking about minor details while programming is bad.

So what can we do better? We did have the right usage in the first approach, maybe we can combine them.

Third approach: same as second, but replace helpers with the cast operator in the first approach to simplify the api

So now we keep the constructors and the override from the second approach, but we also add the upcast operators from the first one. Instead of the cast operator setting up another function pointer, it uses the constructors to create the new function pointer : that way all the information is passed, and we dont care if the FP1 gets destroyed. The FP2 then knows its degraded, and youve got a FP2 that can call an FP1. So this is now legal (from Gail/Core/Tests/):

static void funcPointfunc1 ( void ) { funcPointfunc1_ran = true; }

}

Which as a byproduct, means signals accept lower argument functions while still keeping type safety!

– thothonegan

Well, bored and can’t think of anything else to do, so lets talk about Gail’s event programming system! It came up on IRC a few days ago, so thought it might be a good thing to talk about.

So whats event driven programming? Basically its where all of your code is driven by events instead of being strictly linear. A good example of this is a GUI program : it spends most of its time waiting. When you click the mouse on a button or type a key, it responds to the event with an event handler, then goes back to waiting for the next event.

Gail originally had a standard main loop (see some of the really old examples and GAIL_CORE_DEPRECATED_GAILMAIN_WRAPPER_WITH_NAME). The basics of it are still usable since Gail’s insanely good with backwards compatibility, but not much uses it anymore (one day i’ll remove it).

On a side note, best warning ever from clang:

Main.cpp:89:1: warning: 'DeprecatedApplication' is deprecated [-Wdeprecated-declarations]

So anyways, main loop. The big problem with the standard main loop is for any complicated program, you end up putting everything in the main loop (or you write tiny main loops everywhere). If this do these things, if this do this thing, for a couple thousand lines. Becomes a huge mess. So to solve this, you standardize the way stuff is added to the main loop, and have everything else drive itself based on a set of events (generally with Gail that is signals, file descriptors, and timers). So how do you handle events? Theirs a few ways to solve this : the two main ways i’ll mention are event passing and signaling (which is what gail uses).

Event passing basically allows objects to register for events and they got notified when they occur. A good example of this is WinAPI which every event comes in this form. WM_PAINT is when your app needs to be repainted, WM_LMOUSEDOWN is when the mouse is pressed down, etc. This system can work, but has some issues for me. Namely three things.

1. The event system requires you to add a new identifier every time you want to post a new event. If you only have a few events or limit it to a specific set, it works well enough, but if you have lots of events it quickly can add up.
2. Tricky to do event storage. Every event type has its own data it needs to store, whether its numbers, strings, whatever. Probably i would have done something like InterpolationTimer’s userdata pointer which takes any gail object if i went this route, but you have to package/unpackage the data every time you plan to use it. Not fun.
3. An event system like this is inherently global. If thats what you need (like the window example), great! Sometimes you want one object to be able to notify an object indirectly though, such as a TextGroup getting notified when Text’s color change (which by the way was added today for all you TextGroup users). While you probably could shoehorn local messages into a system, its a mess.

text->signalColorChanged().connect (Gail::Core::functionPointer (this, &TextGroup::childTextNodeChangedColor));

This line says to get the signal for coloring changing from text, and add the function for this->TextGroup::childTextNodeChangedColor to it. When the signal is emitted (the color was changed), it’ll automatically call childTextNodeChangedColor() which in this case, tells the text group it will need to rebuild.

Now notice something important: text has no knowledge of text group. All text knows is when its color changes. it emits the color changed signal. Anyone who cares about when that occurs can register their own functions. This is a very powerful concept.

Now some of you might be saying ‘what about delegates?’. Delegates serve the same purpose, and Gail uses them heavily too. Delegates though force a specific protocol between the two classes, and generally is limited to a single delegate per object. Works great in a lot of places, but signals are a bit more flexible. Generally, I use delegates when an object would be interested in a lot of different events, providing data to the host object, or would be easier. Signals are a lot better for one off events where an object might only care about one or two, or not at all.

So one more thing : function pointers! You may have noticed when i connected the signal to my function, I used a weird function in between. Here’s the important part:

Gail::Core::functionPointer (this, &TextGroup::childTextNodeChangedColor)

Gail::Core::functionPointer() is a template meta function. Essentially what it does is it converts any given object/method pair into a common format that can be easily called. So why do we need such an object? First you need to remember how function pointers work.

So lets start with C function pointers. For all of these examples, i’m using the function:

double pow(double)

as an example function. In C, a function pointer is simply a pointer to a function. Its represented by the weird type ‘return (*name) (params)’ so for our example, its of type:

double (*p) (double)

Not the nicest format, but it gets the job done. The address is directly pointing to the function, so to use it, you would just do the following:

a = (*p)(20) OR a = p(20);

So to c++! With C++, a member function is relative to the object its a part of, and NOT an absolute address. So first, the type is encoded in the pointer type. Lets say our pow() is a member of the class Math. So the pointer type would be:

double (Math::*p) (double)

Now as i mentioned, this pointer is relative to an object. Which means to use it, you need an instance to call it on. So assuming with had Math* m; you could call it like:

a = m->*p (12)

Starting to get really really messy. Now notice that the type is encoded directly in the pointer. Which means we cant for example, use a ‘double (*) (double)’ there or even a ‘double (SomeOtherObject::*) (double)’ there. It has to be for Math, and Math only. Which considering the signaling i mentioned earlier has no class dependency, is a huge problem. Plus if you want to connect to a static function, you cant since thats a normal C function pointer, which isn’t compatible with C++ member pointers! So how do we get around this?

Theirs two major parts to this, Gail::Core::FunctionPointerX<> and Gail::Core::functionPointer (notice the case difference). The first is a class that can handle the differences between various pointer types, and puts them in a common format. So for our pow example, our FunctionPointer would be of type:

Gail::Core::FunctionPointer1<double, double> p;

This is true if its a global function, or if its a member function. In the case of a member function, it records the object tied to it, otherwise it remembers its a global function. FunctionPointer has a few helper methods on it, namely being able to run() it and compare two pointers. So to run our pointer, we just do:

a = p.run(20);

Nice and simple as it should be. Of course having to define the entire type of a function pointer every time is annoying (especially since under the hood it might use multiple classes such as GlobalFunctionPointer0 and MemberFunctionPointer0). So thats where Gail::Core::functionPointer comes in. This template function automatically determines the type of pointer given, and passes it on correctly to the FunctionPointer constructor, making any function pointer as simple as:

Gail::Core::functionPointer (NULL, &pow)

Once you can represent a function pointer easily, a signal then just takes a list of these. connect() adds to the list, disconnect() removes from the list, and emit() calls .run() on every function pointer of the list.

So an example of why this is awesome! Introducing, Gail::Core::InterpolationTimer! Basically, InterpolationTimer is a timer that calls a function over time for a given range. So for example, you want a smooth animation of an object moving from one place to another. Normally you’d need to listen every loop, figure out how much to move, move by that much, see if you finished, etc. With signals and InterpolationTimer though, it becomes really easy! From a current project:

// Interpolate current UI
Gail::Core::InterpolationTimer<Gail::Core::Point2D>* timer = new Gail::Core::InterpolationTimer<Gail::Core::Point2D>;
timer->setStartValue (position());
timer->setEndValue (newPosition);
timer->signalSetValue().connect (Gail::Core::functionPointer (this, &UI::setPosition));
timer->setDuration (duration);
timer->setAnimationCurve(animation);
timer->signalFinished().connect (Gail::Core::FunctionPointer1<void, Gail::Core::InterpolationTimer<Gail::Core::Point2D>* >(this, &UI::enableUIInput));
timer->start();
timer->release();

Every frame, the timer will call UI::setPosition with the new position, smoothly animating. Once its finished, it’ll call enableUIInput. 9 lines of code, compared to the few hundred some of my previous animations took that did the same thing.

So thats essentially Gail’s event system (+ function pointers). Little long, but its a very simple concept that makes a lot of things easier!

–thothonegan

Welcome to our new site. This is a very large platform and we have a lot to show off, so please bear with us as we continue to add content and explain how exactly things work.

As you can see from the (very rough) architecture diagram above, there are a number of key elements that make Gail an excellent piece of technology to aid in game development.

Our future posts will concentrate on specific features of Gail, how they work, and how they benefit a developer using the platform. We’ll also post site updates as the detail pages are modified to be more clear. (We know they’re a mess now!)