Feedback on page SDL_SetEventFilter about sdlwiki

[icculus]

Is this an unfinished part of SDL2?

Not understanding something yet is not the same thing as it being incomplete.

I even tried looking through the headers and cannot find where SDL_EventFilter is defined, just where it was used.

It's defined here ... In case this is where the confusion is, this isn't a function, it's a function pointer. You set up a function of your own that matches that signature, and give it to SDL_SetEventFilter to call later.

userdata is whatever you want to be passed to your function (and if you don't need it, you can pass NULL there and ignore it).

Here's a small example program that uses it. Basically every event that SDL intends to pass to the application will go through the my_event_filter function, which can veto them, or change them. It uses the userdata arg to change a variable when the user presses the space bar, and that variable decides what color the window will be.

All of this said: the best documentation for event filters is probably "don't use them." They add confusion and complexity to things that often have cleaner solutions elsewhere, and have the ability to really break things when misused.

#include "SDL.h"

static int SDLCALL my_event_filter(void *userdata, SDL_Event * event)
{
    if ((event->type == SDL_KEYDOWN) && (event->key.keysym.sym == SDLK_SPACE)) {
        Uint8 *blue = (Uint8 *) userdata;
        if (*blue == 0) {
            *blue = 255;
        } else {
            *blue = 0;
        }
    }
    return 1;  // let all events be added to the queue since we always return 1.
}

int main(int argc, char **argv)
{
    Uint8 blue = 0;
    int quit = 0;

    // just get a window on the screen and clear it to black.
    // you _should_ check these for errors!
    SDL_Init(SDL_INIT_VIDEO);
    SDL_Window *window = SDL_CreateWindow("Hello SDL", SDL_WINDOWPOS_UNDEFINED,
                                          SDL_WINDOWPOS_UNDEFINED, 640, 480, 0);
    SDL_Renderer *renderer = SDL_CreateRenderer(window, -1, SDL_RENDERER_PRESENTVSYNC);
    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
    SDL_RenderClear(renderer);
    SDL_RenderPresent(renderer);

    // Set up an event filter...
    SDL_SetEventFilter(my_event_filter, &blue);

    // Now run the event loop mostly forever. Each event goes through the
    //  my_event_filter function before it lands here. Each frame, we fill
    //  in the window with whatever color `blue` is set to, which might be
    //  changed by the filter function.
    while (!quit) {
        SDL_Event e;
        while (SDL_PollEvent(&e)) {
            if (e.type == SDL_QUIT) {
                quit = 1;
            }
        }

        SDL_SetRenderDrawColor(renderer, 0, 0, blue, 255);
        SDL_RenderClear(renderer);
        SDL_RenderPresent(renderer);
    }

    SDL_Quit();
    return 0;
}

[MystycCheez]

Thank you, this actually does clear things up. Now I see that I really don't need to setup filters for what I want to do.

Yes, I am still new to programming and there are still things I don't understand, like function pointers. The straightforwardness and clarity of the SDL documentation is helping me to learn how to program, it just baffled me when I got to this page.

[icculus]

(I added the code example to the wiki here, so it won't be lost.)

Yes, I am still new to programming and there are still things I don't understand, like function pointers.

Any day we learn something new is an awesome day. :)