## SDL Integration SDL Integration — Integration api for the Simple DirectMedia Layer library. |

## Synopsis

    CoglContext *       cogl_sdl_context_new                (int type,
                                                             CoglError **error);
    void                cogl_sdl_renderer_set_event_type    (CoglRenderer *renderer,
                                                             int type);
    int                 cogl_sdl_renderer_get_event_type    (CoglRenderer *renderer);
    void                cogl_sdl_handle_event               (CoglContext *context,
                                                             SDL_Event *event);
    void                cogl_sdl_idle                       (CoglContext *context);
    SDL_Window *        cogl_sdl_onscreen_get_window        (CoglOnscreen *onscreen);

## Description

Cogl is a portable graphics api that can either be used standalone or alternatively integrated with certain existing frameworks. This api enables Cogl to be used in conjunction with the Simple DirectMedia Layer library.

Using this API a typical SDL application would look something like this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    MyAppData data;
    CoglError *error = NULL;

    data.ctx = cogl_sdl_context_new (SDL_USEREVENT, &error);
    if (!data.ctx)
      {
        fprintf (stderr, "Failed to create context: %s\n",
                 error->message);
        return 1;
      }

    my_application_setup (&data);

    data.redraw_queued = TRUE;
    while (!data.quit)
      {
        while (!data.quit)
          {
            if (!SDL_PollEvent (&event))
              {
                if (data.redraw_queued)
                  break;

                cogl_sdl_idle (ctx);
                if (!SDL_WaitEvent (&event))
                  {
                    fprintf (stderr, "Error waiting for SDL events");
                    return 1;
                  }
              }

             handle_event (&data, &event);
             cogl_sdl_handle_event (ctx, &event);
           }

        data.redraw_queued = redraw (&data);
      }

## Details

### cogl_sdl_context_new ()

    CoglContext *       cogl_sdl_context_new                (int type,
                                                             CoglError **error);

This is a convenience function for creating a new CoglContext for use with SDL and specifying what SDL user event type Cogl can use as a way to interrupt `SDL_WaitEvent()`.

This function is equivalent to the following code:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    CoglRenderer *renderer = cogl_renderer_new ();
    CoglDisplay *display;

    cogl_renderer_set_winsys_id (renderer, COGL_WINSYS_ID_SDL);

    cogl_sdl_renderer_set_event_type (renderer, type);

    if (!cogl_renderer_connect (renderer, error))
      return NULL;

    display = cogl_display_new (renderer, NULL);
    if (!cogl_display_setup (display, error))
      return NULL;

    return cogl_context_new (display, error);

### Note

SDL applications are required to either use this API or to manually create a CoglRenderer and call `cogl_sdl_renderer_set_event_type()`.

`type` : | An SDL user event type between `SDL_USEREVENT` and `SDL_NUMEVENTS` - 1
`error` : | A CoglError return location.

Since 2.0

Stability Level: Unstable

### cogl_sdl_renderer_set_event_type ()

    void                cogl_sdl_renderer_set_event_type    (CoglRenderer *renderer,
                                                             int type);

Tells Cogl what SDL user event type it can use as a way to interrupt `SDL_WaitEvent()` to ensure that `cogl_sdl_handle_event()` will be called in a finite amount of time.

### Note

This should only be called on an un-connected `renderer`.

### Note

For convenience most simple applications can use `cogl_sdl_context_new()` if they don't want to manually create CoglRenderer and CoglDisplay objects during initialization.

`renderer` : | A CoglRenderer
`type` : | An SDL user event type between `SDL_USEREVENT` and `SDL_NUMEVENTS` - 1

Since 2.0

Stability Level: Unstable

### cogl_sdl_renderer_get_event_type ()

    int                 cogl_sdl_renderer_get_event_type    (CoglRenderer *renderer);

Queries what SDL user event type Cogl is using as a way to interrupt `SDL_WaitEvent()`. This is set either using cogl_sdl_context_new or by using `cogl_sdl_renderer_set_event_type()`.

`renderer` : | A CoglRenderer

Since 2.0

Stability Level: Unstable

### cogl_sdl_handle_event ()

    void                cogl_sdl_handle_event               (CoglContext *context,
                                                             SDL_Event *event);

Passes control to Cogl so that it may dispatch any internal event callbacks in response to the given SDL `event`. This function must be called for every SDL event.

`context` : | A CoglContext
`event` : | An SDL event

Since 2.0

Stability Level: Unstable

### cogl_sdl_idle ()

    void                cogl_sdl_idle                       (CoglContext *context);

Notifies Cogl that the application is idle and about to call `SDL_WaitEvent()`. Cogl may use this to run low priority book keeping tasks.

`context` : | A CoglContext

Since 2.0

Stability Level: Unstable

### cogl_sdl_onscreen_get_window ()

    SDL_Window *        cogl_sdl_onscreen_get_window        (CoglOnscreen *onscreen);

`onscreen` : | A CoglOnscreen
Returns : | the underlying SDL_Window associated with an onscreen framebuffer.

Since 2.0

Stability Level: Unstable