Issues with SDL on iOS and Android
30/09/2012
At the office we've just finished working on a C++ game targetting iOS and Android. We've used the up and coming SDL2 release as a cross platform layer. As well as saving us lots of time it has allowed us to get a lot of mileage out of developing on PC.
But there are some serious issues with the abstraction SDL provides for mobile application development. These issues cause a large number of bugs which are both subtle, and very hard to squash. We saw some of the most perculiar symptoms and the debugging process has lead to some very stressful days, tearing into the guts of SDL to work was was happening.
In the end we found the root issue. It was in how SDL does the unification of Desktop and Mobile application structures for games. Let me explain...
A Desktop application (and the structure of SDL programs) looks something like this.
void main(int argc, char** argv) {
Initialise();
while(playing) {
Input();
Update();
Render();
}
Finalise();
}
This works very well for Desktops but writing a Mobile application with this structure would choke the system and run down the battery. The system which manages multitasking is very different. Mobile applications try to do a little work as required, which means they mainly respond to user events.
A Mobile application framework forces you to tie in separate functions for Initalise(), Finalise() and Input(), while providing some other mechanism for calling a regular Update() and/or Render() function. It looks something like this.
class GameApplication implements Application {
public void onConstruction() {
Initialise();
CallEachFrame(Update);
CallEachFrame(Render);
}
public void onDestruction() {
Finalise();
}
public void onInput() {
Input();
}
}
Applying some transformation to the Desktop form such that it acts like the Mobile form is simply impossible to do without major issues. This is because too much information is lost. SDL does not force you to provide Initialise, Finalise, Input, Update or Render separately, and as such can't "extract" them from your program to fit into the Mobile structure.
In fact SDL applications don't even need to have this structure. A valid SDL application might be one which just takes an input and produces an output in a single run. This is a cool aspect of SDL, but it doesn't work well for targetting Mobile operating systems.
iOS
But SDL still tries to fit the desktop structure into the mobile structure. It attempts to do this in a number of horrible ways. On iOS it ties an event to the SDL_GL_SwapBuffers function, which forces control away from your "main" function and allows the rest of the run-loop to continue. This causes weird issues with any OS specific UI elements you use. We noticed unresponsive UIs, missing self-updating behaviour, inability to interface with other iOS frameworks, and lots of crashes too.
And on getting a command to Quit, SDL does a longjmp straight back into your application! This allows it to run itself to a finishing state without the runloop stealing back control. Only then does it jump back into the Operating System code and continue as normal! If also using external iOS objects which need to be destroyed unless you are careful this can cause deadlocks or other issues.
Android
On Android SDL sidesteps some of these issue by running your "main" function in a separate thread. While this may seem like a cleaner solution it has many troubles of its own. First of all it has to be manually syncronised with all the internal android events such as "onResume", "onPause", "surfaceCreated" and "surfaceDestroyed". Any other interactions also must be synchronised. Often these syncronisations require hard mutial exclusion - something that can't always be guaranted. For example OpenGL calls can't be performed between "surfaceDestroyed" and "surfaceCreated" or the application will crash; yet often the main loop must continue at least a cycle in order to poll essential SDL events (such as SDL_QUIT).
A second issue comes via the interaction that is done by the Java Native Interface. In interfacing with other Android Libraries often functionality must be performed on the UI thread, but if this call also needs to be performed on the JNI thread (which by SDL design is a separate thread), you also run into trouble.
The Solution
For developers confident enough to mess around with SDL the solution is simple. What we did was split our game into the separate Initialise, Finalise, Input, Update and Render functions, exposed them to the Mobile layer and tie them to the appropriate callbacks. Providing we made sure SDL still initialised itself properly, this worked perfectly and immediately removed the vast majority of our issues.
I've had some brief communication with the SDL developers and it sounds like they would be happy to accept a patch, but still want to allow for the older method of integration. This is understandable. Doing it this new way would require them to break the illusion that a developer can use SDL to develop both Desktop and Mobile applications just by providing a "main" function. Secondly SDL has always been unprescriptive about what kind of applications are being built. SDL can be used just as effectively for an input-output program using no "while" loop as it can for games.
But personally I think this change is the only way. SDL is a library as well as a layer and could still provide library functions to make the usage on Mobile as painless as possible. Mobile development already requires special setup of one form or another and this change would just make it official that there are multiple entry points.
I feel that the current method simply doesn't work. It is hard for me to give specific examples of issues because we came into many over the course of development and they were often tied to the specifics of the flow of our game. But the fact reminds that it is more or less impossible to interface correctly with many libraries you would expect almost all game developers to use (Game Center, Twitter, Facebook, Swarm).
I can only give thanks to the SDL developers for all the awesome work they have put into such a great resource, but I strongly suggest this change if it at all appears viable.
Edit: Specific Changes
I've been asked in a couple of e-mails about what specific changes we made to the SDL structure to get the above behavior. Here is a reply I've been using.
So for both iOS and Android we didn't provide a main function and instead separated our code out into three functions. Init, Finish, Update (the Update function included the render code).
Android
On Android we modified the SDLActivity to remove the creation of a new thread which runs SDL_main.
We then added Init to run after the first time surfaceChanged is called on the SurfaceView. This ensures that when you transition to C++ code you will be able to construct an OpenGL context and call OpenGL correctly.
We added a callback to the Update function after running Init. We used the Handler class which comes with android. In the callback, before running the Update function it is important to check that the SurfaceView is not invalid, otherwise OpenGL calls will crash the application. To do this we added a flag and made it change on the surfaceCreated and surfaceDestroyed functions.
The Finish function we put in the Activity onDestroy method.
This didn't really require any hacking inside of SDL other than this Java file.
iOS
For iOS we edited some files inside: SDL\src\video\uikit
In didFinishLaunchingWithOptions we disabled the iPhone event pump
using SDL_iPhoneSetEventPump(SDL_FALSE);. We then called our Init function.
In applicationDidBecomeActive we used the CADisplayLink class to add a run loop. This run loop consisted of a callback to our Update function every frame.
In applicationWillResignActive we invalidated this framelink, to stop the update running when no OpenGL context was available.
In applicationWillTerminate we added our Finish function, and removed the calls to SDL_SendQuit and the longjmp hack.
Typically SDL_main is called in the postFinishLaunch method. You can remove this call or just set SDL_main to some empty function.
Things may have changed due to update so SDL 2.0 (I hear the longjmp hack is gone), but this was the jist of what we ended up doing. It was quite a straight forward change in the end. Essentially if you pull SDL_main out of the equation, and remove any platform specific hacks, it should work as intended.
___________________________