1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2012 Intel Corporation. 7 * 8 * Permission is hereby granted, free of charge, to any person 9 * obtaining a copy of this software and associated documentation 10 * files (the "Software"), to deal in the Software without 11 * restriction, including without limitation the rights to use, copy, 12 * modify, merge, publish, distribute, sublicense, and/or sell copies 13 * of the Software, and to permit persons to whom the Software is 14 * furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 23 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 24 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 25 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 26 * SOFTWARE. 27 * 28 * 29 */ 30 31 #ifndef __COGL_SDL_H__ 32 #define __COGL_SDL_H__ 33 34 /* NB: this is a top-level header that can be included directly but we 35 * want to be careful not to define __COGL_H_INSIDE__ when this is 36 * included internally while building Cogl itself since 37 * __COGL_H_INSIDE__ is used in headers to guard public vs private api 38 * definitions 39 */ 40 #ifndef COGL_COMPILATION 41 42 /* Note: When building Cogl .gir we explicitly define 43 * __COGL_H_INSIDE__ */ 44 #ifndef __COGL_H_INSIDE__ 45 #define __COGL_H_INSIDE__ 46 #define __COGL_SDL_H_MUST_UNDEF_COGL_H_INSIDE__ 47 #endif 48 49 #endif /* COGL_COMPILATION */ 50 51 #include <cogl/cogl-context.h> 52 #include <cogl/cogl-onscreen.h> 53 #include <SDL.h> 54 55 COGL_BEGIN_DECLS 56 57 /** 58 * SECTION:cogl-sdl 59 * @short_description: Integration api for the Simple DirectMedia 60 * Layer library. 61 * 62 * Cogl is a portable graphics api that can either be used standalone 63 * or alternatively integrated with certain existing frameworks. This 64 * api enables Cogl to be used in conjunction with the Simple 65 * DirectMedia Layer library. 66 * 67 * Using this API a typical SDL application would look something like 68 * this: 69 * |[ 70 * MyAppData data; 71 * CoglError *error = NULL; 72 * 73 * data.ctx = cogl_sdl_context_new (SDL_USEREVENT, &error); 74 * if (!data.ctx) 75 * { 76 * fprintf (stderr, "Failed to create context: %s\n", 77 * error->message); 78 * return 1; 79 * } 80 * 81 * my_application_setup (&data); 82 * 83 * data.redraw_queued = TRUE; 84 * while (!data.quit) 85 * { 86 * while (!data.quit) 87 * { 88 * if (!SDL_PollEvent (&event)) 89 * { 90 * if (data.redraw_queued) 91 * break; 92 * 93 * cogl_sdl_idle (ctx); 94 * if (!SDL_WaitEvent (&event)) 95 * { 96 * fprintf (stderr, "Error waiting for SDL events"); 97 * return 1; 98 * } 99 * } 100 * 101 * handle_event (&data, &event); 102 * cogl_sdl_handle_event (ctx, &event); 103 * } 104 * 105 * data.redraw_queued = redraw (&data); 106 * } 107 * ]| 108 */ 109 110 /** 111 * cogl_sdl_context_new: 112 * @type: An SDL user event type between <constant>SDL_USEREVENT</constant> and 113 * <constant>SDL_NUMEVENTS</constant> - 1 114 * @error: A CoglError return location. 115 * 116 * This is a convenience function for creating a new #CoglContext for 117 * use with SDL and specifying what SDL user event type Cogl can use 118 * as a way to interrupt SDL_WaitEvent(). 119 * 120 * This function is equivalent to the following code: 121 * |[ 122 * CoglRenderer *renderer = cogl_renderer_new (); 123 * CoglDisplay *display; 124 * 125 * cogl_renderer_set_winsys_id (renderer, COGL_WINSYS_ID_SDL); 126 * 127 * cogl_sdl_renderer_set_event_type (renderer, type); 128 * 129 * if (!cogl_renderer_connect (renderer, error)) 130 * return NULL; 131 * 132 * display = cogl_display_new (renderer, NULL); 133 * if (!cogl_display_setup (display, error)) 134 * return NULL; 135 * 136 * return cogl_context_new (display, error); 137 * ]| 138 * 139 * <note>SDL applications are required to either use this API or 140 * to manually create a #CoglRenderer and call 141 * cogl_sdl_renderer_set_event_type().</note> 142 * 143 * Since: 2.0 144 * Stability: unstable 145 */ 146 CoglContext * 147 cogl_sdl_context_new (int type, CoglError **error); 148 149 /** 150 * cogl_sdl_renderer_set_event_type: 151 * @renderer: A #CoglRenderer 152 * @type: An SDL user event type between <constant>SDL_USEREVENT</constant> and 153 * <constant>SDL_NUMEVENTS</constant> - 1 154 * 155 * Tells Cogl what SDL user event type it can use as a way to 156 * interrupt SDL_WaitEvent() to ensure that cogl_sdl_handle_event() 157 * will be called in a finite amount of time. 158 * 159 * <note>This should only be called on an un-connected 160 * @renderer.</note> 161 * 162 * <note>For convenience most simple applications can use 163 * cogl_sdl_context_new() if they don't want to manually create 164 * #CoglRenderer and #CoglDisplay objects during 165 * initialization.</note> 166 * 167 * Since: 2.0 168 * Stability: unstable 169 */ 170 void 171 cogl_sdl_renderer_set_event_type (CoglRenderer *renderer, int type); 172 173 /** 174 * cogl_sdl_renderer_get_event_type: 175 * @renderer: A #CoglRenderer 176 * 177 * Queries what SDL user event type Cogl is using as a way to 178 * interrupt SDL_WaitEvent(). This is set either using 179 * cogl_sdl_context_new or by using 180 * cogl_sdl_renderer_set_event_type(). 181 * 182 * Since: 2.0 183 * Stability: unstable 184 */ 185 int 186 cogl_sdl_renderer_get_event_type (CoglRenderer *renderer); 187 188 /** 189 * cogl_sdl_handle_event: 190 * @context: A #CoglContext 191 * @event: An SDL event 192 * 193 * Passes control to Cogl so that it may dispatch any internal event 194 * callbacks in response to the given SDL @event. This function must 195 * be called for every SDL event. 196 * 197 * Since: 2.0 198 * Stability: unstable 199 */ 200 void 201 cogl_sdl_handle_event (CoglContext *context, SDL_Event *event); 202 203 /** 204 * cogl_sdl_idle: 205 * @context: A #CoglContext 206 * 207 * Notifies Cogl that the application is idle and about to call 208 * SDL_WaitEvent(). Cogl may use this to run low priority book keeping 209 * tasks. 210 * 211 * Since: 2.0 212 * Stability: unstable 213 */ 214 void 215 cogl_sdl_idle (CoglContext *context); 216 217 #if SDL_MAJOR_VERSION >= 2 218 219 /** 220 * cogl_sdl_onscreen_get_window: 221 * @onscreen: A #CoglOnscreen 222 * 223 * Returns: the underlying SDL_Window associated with an onscreen framebuffer. 224 * 225 * Since: 2.0 226 * Stability: unstable 227 */ 228 SDL_Window * 229 cogl_sdl_onscreen_get_window (CoglOnscreen *onscreen); 230 231 #endif /* SDL_MAJOR_VERSION */ 232 233 COGL_END_DECLS 234 235 /* The gobject introspection scanner seems to parse public headers in 236 * isolation which means we need to be extra careful about how we 237 * define and undefine __COGL_H_INSIDE__ used to detect when internal 238 * headers are incorrectly included by developers. In the gobject 239 * introspection case we have to manually define __COGL_H_INSIDE__ as 240 * a commandline argument for the scanner which means we must be 241 * careful not to undefine it in a header... 242 */ 243 #ifdef __COGL_SDL_H_MUST_UNDEF_COGL_H_INSIDE__ 244 #undef __COGL_H_INSIDE__ 245 #undef __COGL_SDL_H_MUST_UNDEF_COGL_H_INSIDE__ 246 #endif 247 248 #endif /* __COGL_SDL_H__ */ 249