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