[SDL] iOS System Callback

[Jared Maddox]

> Date: Sun, 1 Apr 2012 00:42:20 -0400
> From: Brian Barnes <ggadwa at charter.net>
> To: sdl at lists.libsdl.org
> Subject: [SDL]  iOS System Callback
> Message-ID: <A7BDF1A0-D857-46B7-BA7E-46AC5243C3BA at charter.net>
> Content-Type: text/plain; charset=us-ascii
>
> Eric wrote:
>

> As I said before, I'm not married to any solution, and this one is also
> fine, and there's nothing to stop us from adding the new events, but one
> important note:  Some will be SPECIFIC to iOS.  iOS has a lot of messages
> dealing with sending applications to the back and forward that have to be
> dealt with at the correct place, so we will be filling up the regular event
> system with very iOS specific events (and in the future, Android specific
> ones, etc.)
>
> I just want to see something getting done ASAP :)
>
> While you solution is good, I do see it as a lot more work; the reason being
> is that if you only implement the 6 messages needed here, then it's easier,
> but then it's also a confusing API because it won't function as a
> replacement for ALL the events when the API is named that way and targetted
> that way.
>
> The other thing -- and this is the one that could be a very big deal -- is
> turning this on can be a either/or thing.  If I start receiving events by
> callbacks, it would interfere how I receive them by polling, which would
> kind of force it to be either/or.  If I just handle the iOS specific calls
> by callback, then I can leave my polling code in.  Going to this means I
> need to begin to receive all events through this mechanism, and that would
> mean MASSIVE changes in a lot of code.
>
> (That is if I am getting your proposal right.)
>
> [>] Brian
>

Good points. I suggest a slight modification:

enum SDL_callbackstage
{
	SDL_initialcallback,
	
	SDL_queuecallback,
	
	SDL_finishcallback
};
void SDL_SetEventCallback( int (*sdl_event_callback_function)(
SDL_Event* event, void* userdata, SDL_callbackstage stage ), void*
userdata );


The basic concept is based on Aspect-oriented programming. With
Aspect-orientation, you basically replace calls to specific functions
with a set of 3 functions: one that happens before the call; one that
happens after the call; and one in between that decides whether the
original function is called at all, gets to modify the arguments
before they get passed to the original function, and gets to modify
the return before it gets returned to the original caller.

I propose that the final implementation be based on that, with the
'aspect' specifically applying to the places in the library where OS
events are placed onto the SDL event queue (so that this doesn't
affect user events).

SDL_callbackstage is used to signal which position the callback was
called from: SDL_initialcallback and SDL_finishcallback are both
self-explanatory, they happen at the beginning and end of set of
callback invocations, and their return value is ignored.
SDL_queuecallback is used to control whether the event is added to the
event queue (-1 for default (presumably "yes", but see the final
paragraph of this post), 0 for no, 1 for yes).

The behavior would be something like this:

OS event comes in
Pass user initial callback
Pass user queue callback & react to return value
Suspend/resume SDL (*)
Pass user final callback

*The exact order of the queue call & SDL being suspended/resumed
should be event-dependent.

I think that the basic outline above is correct. A callback to control
whether SDL gets suspended/resumed might be useful on some platforms,
but I doubt it. Conveniently, this variant of the patch wouldn't be
too different than the current one, it just involves a switch
statement (for the queue), two more callback invocations, an enum, and
an extra argument. Applying this to events in general might involve
more effort (I haven't checked), but that's effort that a callback
system would require anyways.

Note: I haven't received the digest for the following post yet.

> From Brian Barnes ggadwa at charter.net
> At Sun Apr 1 12:20:14 PDT 2012
> Subject: [SDL] iOS System Callback
>
> NOTE: Eric, this solution is *not* the same solution you proposed
> (unless I am completely mis-reading it.)  Piotr's solution is SPECIFICALLY
> for callback-required OS events, NOT for generic OS events.  It can be
> tailored that way, but I think this is really where you might be getting
> confused.  If you only implement it for OS stuff, then later implement
> it for everything else, it WILL break almost everybody's code.
>

Fortunately, my proposed variant doesn't have this problem. No mode
switching, no magically knowing which generic events are hooked by
callback & which aren't, just a simple add-in system where the
callback can effectively say "pretend I don't exist". It provides an
implementation route for Eric's future-proofing, without requiring
SDL's maintainers to keep track of when a particular event was moved
to the callback system.

In all cases of my proposed variant, returning -1 if the callback
doesn't recognize either the SDL_callbackstage value or the event type
is correct, because it basically means "do the default". Thus, if the
callback either doesn't know about or care about some particular
SDL_callbackstage or event (or combination of the two) then it simply
does nothing other than return -1, and (one way or another) SDL will
do the default action.