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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 













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
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 













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

Generated by GTK-Doc V1.19.1