## SDL Integration

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

## Functions

CoglContext * | cogl_sdl_context_new ()
void | cogl_sdl_renderer_set_event_type ()
int | cogl_sdl_renderer_get_event_type ()
void | cogl_sdl_handle_event ()
void | cogl_sdl_idle ()
SDL_Window * | cogl_sdl_onscreen_get_window ()

## 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);
      }

## Functions

### 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);

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

#### Parameters

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.

This should only be called on an un-connected `renderer`.
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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

context | A CoglContext |

Since: 2.0

Stability Level: Unstable

### cogl_sdl_onscreen_get_window ()

    SDL_Window *
    cogl_sdl_onscreen_get_window (CoglOnscreen *onscreen);

#### Parameters

onscreen | A CoglOnscreen |

#### Returns

the underlying SDL_Window associated with an onscreen framebuffer.

Since: 2.0

Stability Level: Unstable