1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2007,2008,2009 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 #if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION) 30 #error "Only <cogl/cogl.h> can be included directly." 31 #endif 32 33 #ifndef __COGL_RENDERER_H__ 34 #define __COGL_RENDERER_H__ 35 36 #include <cogl/cogl-types.h> 37 #include <cogl/cogl-onscreen-template.h> 38 #include <cogl/cogl-error.h> 39 #include <cogl/cogl-output.h> 40 41 #ifdef COGL_HAS_GTYPE_SUPPORT 42 #include <glib-object.h> 43 #endif 44 45 COGL_BEGIN_DECLS 46 47 /** 48 * SECTION:cogl-renderer 49 * @short_description: Choosing a means to render 50 * 51 * A #CoglRenderer represents a means to render. It encapsulates the 52 * selection of an underlying driver, such as OpenGL or OpenGL-ES and 53 * a selection of a window system binding API such as GLX, or EGL or 54 * WGL. 55 * 56 * A #CoglRenderer has two states, "unconnected" and "connected". When 57 * a renderer is first instantiated using cogl_renderer_new() it is 58 * unconnected so that it can be configured and constraints can be 59 * specified for how the backend driver and window system should be 60 * chosen. 61 * 62 * After configuration a #CoglRenderer can (optionally) be explicitly 63 * connected using cogl_renderer_connect() which allows for the 64 * handling of connection errors so that fallback configurations can 65 * be tried if necessary. Applications that don't support any 66 * fallbacks though can skip using cogl_renderer_connect() and leave 67 * Cogl to automatically connect the renderer. 68 * 69 * Once you have a configured #CoglRenderer it can be used to create a 70 * #CoglDisplay object using cogl_display_new(). 71 * 72 * <note>Many applications don't need to explicitly use 73 * cogl_renderer_new() or cogl_display_new() and can just jump 74 * straight to cogl_context_new() and pass a %NULL display argument so 75 * Cogl will automatically connect and setup a renderer and 76 * display.</note> 77 */ 78 79 80 /** 81 * COGL_RENDERER_ERROR: 82 * 83 * An error domain for exceptions reported by Cogl 84 */ 85 #define COGL_RENDERER_ERROR cogl_renderer_error_quark () 86 87 uint32_t 88 cogl_renderer_error_quark (void); 89 90 typedef struct _CoglRenderer CoglRenderer; 91 92 #ifdef COGL_HAS_GTYPE_SUPPORT 93 /** 94 * cogl_renderer_get_gtype: 95 * 96 * Returns: a #GType that can be used with the GLib type system. 97 */ 98 GType cogl_renderer_get_gtype (void); 99 #endif 100 101 /** 102 * cogl_is_renderer: 103 * @object: A #CoglObject pointer 104 * 105 * Determines if the given @object is a #CoglRenderer 106 * 107 * Return value: %TRUE if @object is a #CoglRenderer, else %FALSE. 108 * Since: 1.10 109 * Stability: unstable 110 */ 111 CoglBool 112 cogl_is_renderer (void *object); 113 114 /** 115 * cogl_renderer_new: 116 * 117 * Instantiates a new (unconnected) #CoglRenderer object. A 118 * #CoglRenderer represents a means to render. It encapsulates the 119 * selection of an underlying driver, such as OpenGL or OpenGL-ES and 120 * a selection of a window system binding API such as GLX, or EGL or 121 * WGL. 122 * 123 * While the renderer is unconnected it can be configured so that 124 * applications may specify backend constraints, such as "must use 125 * x11" for example via cogl_renderer_add_constraint(). 126 * 127 * There are also some platform specific configuration apis such 128 * as cogl_xlib_renderer_set_foreign_display() that may also be 129 * used while the renderer is unconnected. 130 * 131 * Once the renderer has been configured, then it may (optionally) be 132 * explicitly connected using cogl_renderer_connect() which allows 133 * errors to be handled gracefully and potentially fallback 134 * configurations can be tried out if there are initial failures. 135 * 136 * If a renderer is not explicitly connected then cogl_display_new() 137 * will automatically connect the renderer for you. If you don't 138 * have any code to deal with error/fallback situations then its fine 139 * to just let Cogl do the connection for you. 140 * 141 * Once you have setup your renderer then the next step is to create a 142 * #CoglDisplay using cogl_display_new(). 143 * 144 * <note>Many applications don't need to explicitly use 145 * cogl_renderer_new() or cogl_display_new() and can just jump 146 * straight to cogl_context_new() and pass a %NULL display argument 147 * so Cogl will automatically connect and setup a renderer and 148 * display.</note> 149 * 150 * Return value: (transfer full): A newly created #CoglRenderer. 151 * 152 * Since: 1.10 153 * Stability: unstable 154 */ 155 CoglRenderer * 156 cogl_renderer_new (void); 157 158 /* optional configuration APIs */ 159 160 /** 161 * CoglWinsysID: 162 * @COGL_WINSYS_ID_ANY: Implies no preference for which backend is used 163 * @COGL_WINSYS_ID_STUB: Use the no-op stub backend 164 * @COGL_WINSYS_ID_GLX: Use the GLX window system binding API 165 * @COGL_WINSYS_ID_EGL_XLIB: Use EGL with the X window system via XLib 166 * @COGL_WINSYS_ID_EGL_NULL: Use EGL with the PowerVR NULL window system 167 * @COGL_WINSYS_ID_EGL_GDL: Use EGL with the GDL platform 168 * @COGL_WINSYS_ID_EGL_WAYLAND: Use EGL with the Wayland window system 169 * @COGL_WINSYS_ID_EGL_KMS: Use EGL with the KMS platform 170 * @COGL_WINSYS_ID_EGL_ANDROID: Use EGL with the Android platform 171 * @COGL_WINSYS_ID_EGL_MIR: Use EGL with the Mir server 172 * @COGL_WINSYS_ID_WGL: Use the Microsoft Windows WGL binding API 173 * @COGL_WINSYS_ID_SDL: Use the SDL window system 174 * 175 * Identifies specific window system backends that Cogl supports. 176 * 177 * These can be used to query what backend Cogl is using or to try and 178 * explicitly select a backend to use. 179 */ 180 typedef enum 181 { 182 COGL_WINSYS_ID_ANY, 183 COGL_WINSYS_ID_STUB, 184 COGL_WINSYS_ID_GLX, 185 COGL_WINSYS_ID_EGL_XLIB, 186 COGL_WINSYS_ID_EGL_NULL, 187 COGL_WINSYS_ID_EGL_GDL, 188 COGL_WINSYS_ID_EGL_WAYLAND, 189 COGL_WINSYS_ID_EGL_KMS, 190 COGL_WINSYS_ID_EGL_ANDROID, 191 COGL_WINSYS_ID_EGL_MIR, 192 COGL_WINSYS_ID_WGL, 193 COGL_WINSYS_ID_SDL 194 } CoglWinsysID; 195 196 /** 197 * cogl_renderer_set_winsys_id: 198 * @renderer: A #CoglRenderer 199 * @winsys_id: An ID of the winsys you explicitly want to use. 200 * 201 * This allows you to explicitly select a winsys backend to use instead 202 * of letting Cogl automatically select a backend. 203 * 204 * if you select an unsupported backend then cogl_renderer_connect() 205 * will fail and report an error. 206 * 207 * This may only be called on an un-connected #CoglRenderer. 208 */ 209 void 210 cogl_renderer_set_winsys_id (CoglRenderer *renderer, 211 CoglWinsysID winsys_id); 212 213 /** 214 * cogl_renderer_get_winsys_id: 215 * @renderer: A #CoglRenderer 216 * 217 * Queries which window system backend Cogl has chosen to use. 218 * 219 * This may only be called on a connected #CoglRenderer. 220 * 221 * Returns: The #CoglWinsysID corresponding to the chosen window 222 * system backend. 223 */ 224 CoglWinsysID 225 cogl_renderer_get_winsys_id (CoglRenderer *renderer); 226 227 /** 228 * cogl_renderer_get_n_fragment_texture_units: 229 * @renderer: A #CoglRenderer 230 * 231 * Queries how many texture units can be used from fragment programs 232 * 233 * Returns: the number of texture image units. 234 * 235 * Since: 1.8 236 * Stability: Unstable 237 */ 238 int 239 cogl_renderer_get_n_fragment_texture_units (CoglRenderer *renderer); 240 241 /** 242 * cogl_renderer_check_onscreen_template: 243 * @renderer: A #CoglRenderer 244 * @onscreen_template: A #CoglOnscreenTemplate 245 * @error: A pointer to a #CoglError for reporting exceptions 246 * 247 * Tests if a given @onscreen_template can be supported with the given 248 * @renderer. 249 * 250 * Return value: %TRUE if the @onscreen_template can be supported, 251 * else %FALSE. 252 * Since: 1.10 253 * Stability: unstable 254 */ 255 CoglBool 256 cogl_renderer_check_onscreen_template (CoglRenderer *renderer, 257 CoglOnscreenTemplate *onscreen_template, 258 CoglError **error); 259 260 /* Final connection API */ 261 262 /** 263 * cogl_renderer_connect: 264 * @renderer: An unconnected #CoglRenderer 265 * @error: a pointer to a #CoglError for reporting exceptions 266 * 267 * Connects the configured @renderer. Renderer connection isn't a 268 * very active process, it basically just means validating that 269 * any given constraint criteria can be satisfied and that a 270 * usable driver and window system backend can be found. 271 * 272 * Return value: %TRUE if there was no error while connecting the 273 * given @renderer. %FALSE if there was an error. 274 * Since: 1.10 275 * Stability: unstable 276 */ 277 CoglBool 278 cogl_renderer_connect (CoglRenderer *renderer, CoglError **error); 279 280 /** 281 * CoglRendererConstraint: 282 * @COGL_RENDERER_CONSTRAINT_USES_X11: Require the renderer to be X11 based 283 * @COGL_RENDERER_CONSTRAINT_USES_XLIB: Require the renderer to be X11 284 * based and use Xlib 285 * @COGL_RENDERER_CONSTRAINT_USES_EGL: Require the renderer to be EGL based 286 * @COGL_RENDERER_CONSTRAINT_SUPPORTS_COGL_GLES2: Require that the 287 * renderer supports creating a #CoglGLES2Context via 288 * cogl_gles2_context_new(). This can be used to integrate GLES 2.0 289 * code into Cogl based applications. 290 * 291 * These constraint flags are hard-coded features of the different renderer 292 * backends. Sometimes a platform may support multiple rendering options which 293 * Cogl will usually choose from automatically. Some of these features are 294 * important to higher level applications and frameworks though, such as 295 * whether a renderer is X11 based because an application might only support 296 * X11 based input handling. An application might also need to ensure EGL is 297 * used internally too if they depend on access to an EGLDisplay for some 298 * purpose. 299 * 300 * Applications should ideally minimize how many of these constraints 301 * they depend on to ensure maximum portability. 302 * 303 * Since: 1.10 304 * Stability: unstable 305 */ 306 typedef enum 307 { 308 COGL_RENDERER_CONSTRAINT_USES_X11 = (1 << 0), 309 COGL_RENDERER_CONSTRAINT_USES_XLIB = (1 << 1), 310 COGL_RENDERER_CONSTRAINT_USES_EGL = (1 << 2), 311 COGL_RENDERER_CONSTRAINT_SUPPORTS_COGL_GLES2 = (1 << 3) 312 } CoglRendererConstraint; 313 314 315 /** 316 * cogl_renderer_add_constraint: 317 * @renderer: An unconnected #CoglRenderer 318 * @constraint: A #CoglRendererConstraint to add 319 * 320 * This adds a renderer selection @constraint. 321 * 322 * Applications should ideally minimize how many of these constraints they 323 * depend on to ensure maximum portability. 324 * 325 * Since: 1.10 326 * Stability: unstable 327 */ 328 void 329 cogl_renderer_add_constraint (CoglRenderer *renderer, 330 CoglRendererConstraint constraint); 331 332 /** 333 * cogl_renderer_remove_constraint: 334 * @renderer: An unconnected #CoglRenderer 335 * @constraint: A #CoglRendererConstraint to remove 336 * 337 * This removes a renderer selection @constraint. 338 * 339 * Applications should ideally minimize how many of these constraints they 340 * depend on to ensure maximum portability. 341 * 342 * Since: 1.10 343 * Stability: unstable 344 */ 345 void 346 cogl_renderer_remove_constraint (CoglRenderer *renderer, 347 CoglRendererConstraint constraint); 348 349 /** 350 * CoglDriver: 351 * @COGL_DRIVER_ANY: Implies no preference for which driver is used 352 * @COGL_DRIVER_NOP: A No-Op driver. 353 * @COGL_DRIVER_GL: An OpenGL driver. 354 * @COGL_DRIVER_GL3: An OpenGL driver using the core GL 3.1 profile 355 * @COGL_DRIVER_GLES1: An OpenGL ES 1.1 driver. 356 * @COGL_DRIVER_GLES2: An OpenGL ES 2.0 driver. 357 * @COGL_DRIVER_WEBGL: A WebGL driver. 358 * 359 * Identifiers for underlying hardware drivers that may be used by 360 * Cogl for rendering. 361 * 362 * Since: 1.10 363 * Stability: unstable 364 */ 365 typedef enum 366 { 367 COGL_DRIVER_ANY, 368 COGL_DRIVER_NOP, 369 COGL_DRIVER_GL, 370 COGL_DRIVER_GL3, 371 COGL_DRIVER_GLES1, 372 COGL_DRIVER_GLES2, 373 COGL_DRIVER_WEBGL 374 } CoglDriver; 375 376 /** 377 * cogl_renderer_set_driver: 378 * @renderer: An unconnected #CoglRenderer 379 * 380 * Requests that Cogl should try to use a specific underlying driver 381 * for rendering. 382 * 383 * If you select an unsupported driver then cogl_renderer_connect() 384 * will fail and report an error. Most applications should not 385 * explicitly select a driver and should rely on Cogl automatically 386 * choosing the driver. 387 * 388 * This may only be called on an un-connected #CoglRenderer. 389 * 390 * Since: 1.10 391 * Stability: unstable 392 */ 393 void 394 cogl_renderer_set_driver (CoglRenderer *renderer, 395 CoglDriver driver); 396 397 /** 398 * cogl_renderer_get_driver: 399 * @renderer: A connected #CoglRenderer 400 * 401 * Queries what underlying driver is being used by Cogl. 402 * 403 * This may only be called on a connected #CoglRenderer. 404 * 405 * Since: 1.10 406 * Stability: unstable 407 */ 408 CoglDriver 409 cogl_renderer_get_driver (CoglRenderer *renderer); 410 411 /** 412 * CoglOutputCallback: 413 * @output: The current display output being iterated 414 * @user_data: The user pointer passed to 415 * cogl_renderer_foreach_output() 416 * 417 * A callback type that can be passed to 418 * cogl_renderer_foreach_output() for iterating display outputs for a 419 * given renderer. 420 * 421 * Since: 1.14 422 * Stability: Unstable 423 */ 424 typedef void (*CoglOutputCallback) (CoglOutput *output, void *user_data); 425 426 /** 427 * cogl_renderer_foreach_output: 428 * @renderer: A connected #CoglRenderer 429 * @callback: (scope call): A #CoglOutputCallback to be called for 430 * each display output 431 * @user_data: A user pointer to be passed to @callback 432 * 433 * Iterates all known display outputs for the given @renderer and 434 * passes a corresponding #CoglOutput pointer to the given @callback 435 * for each one, along with the given @user_data. 436 * 437 * Since: 1.14 438 * Stability: Unstable 439 */ 440 void 441 cogl_renderer_foreach_output (CoglRenderer *renderer, 442 CoglOutputCallback callback, 443 void *user_data); 444 445 COGL_END_DECLS 446 447 #endif /* __COGL_RENDERER_H__ */ 448 449