cogl/cogl-display.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2010 Intel Corporation.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library. If not, see
  20  * <http://www.gnu.org/licenses/>.
  21  *
  22  * Authors:
  23  *  Robert Bragg <robert@linux.intel.com>
  24  *
  25  */
  26
  27 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  28 #error "Only <cogl/cogl.h> can be included directly."
  29 #endif
  30
  31 #ifndef __COGL_DISPLAY_H__
  32 #define __COGL_DISPLAY_H__
  33
  34 #include <cogl/cogl-renderer.h>
  35 #include <cogl/cogl-onscreen-template.h>
  36
  37 G_BEGIN_DECLS
  38
  39 #ifdef COGL_HAS_EGL_PLATFORM_GDL_SUPPORT
  40 #include <libgdl.h>
  41 #endif
  42
  43 /**
  44  * SECTION:cogl-display
  45  * @short_description: Common aspects of a display pipeline
  46  *
  47  * The basic intention for this object is to let the application
  48  * configure common display preferences before creating a context, and
  49  * there are a few different aspects to this...
  50  *
  51  * Firstly there are options directly relating to the physical display
  52  * pipeline that is currently being used including the digital to
  53  * analogue conversion hardware and the screens the user sees.
  54  *
  55  * Another aspect is that display options may constrain or affect how
  56  * onscreen framebuffers should later be configured. The original
  57  * rationale for the display object in fact was to let us handle GLX
  58  * and EGLs requirements that framebuffers must be "compatible" with
  59  * the config associated with the current context meaning we have to
  60  * force the user to describe how they would like to create their
  61  * onscreen windows before we can choose a suitable fbconfig and
  62  * create a GLContext.
  63  */
  64
  65 typedef struct _CoglDisplay           CoglDisplay;
  66
  67 #define COGL_DISPLAY(OBJECT) ((CoglDisplay *)OBJECT)
  68
  69 /**
  70  * cogl_display_new:
  71  * @renderer: A #CoglRenderer
  72  * @onscreen_template: A #CoglOnscreenTemplate
  73  *
  74  * Explicitly allocates a new #CoglDisplay object to encapsulate the
  75  * common state of the display pipeline that applies to the whole
  76  * application.
  77  *
  78  * <note>Many applications don't need to explicitly use
  79  * cogl_display_new() and can just jump straight to cogl_context_new()
  80  * and pass a %NULL display argument so Cogl will automatically
  81  * connect and setup a renderer and display.</note>
  82  *
  83  * A @display can only be made for a specific choice of renderer which
  84  * is why this takes the @renderer argument.
  85  *
  86  * A common use for explicitly allocating a display object is to
  87  * define a template for allocating onscreen framebuffers which is
  88  * what the @onscreen_template argument is for.
  89  *
  90  * When a display is first allocated via cogl_display_new() it is in a
  91  * mutable configuration mode. It's designed this way so we can
  92  * extend the apis available for configuring a display without
  93  * requiring huge numbers of constructor arguements.
  94  *
  95  * When you have finished configuring a display object you can
  96  * optionally call cogl_display_setup() to explicitly apply the
  97  * configuration and check for errors. Alternaitvely you can pass the
  98  * display to cogl_context_new() and Cogl will implicitly apply your
  99  * configuration but if there are errors then the application will
 100  * abort with a message. For simple applications with no fallback
 101  * options then relying on the implicit setup can be fine.
 102  *
 103  * Return value: A newly allocated #CoglDisplay object in a mutable
 104  *               configuration mode.
 105  * Since: 1.10
 106  * Stability: unstable
 107  */
 108 CoglDisplay *
 109 cogl_display_new (CoglRenderer *renderer,
 110                   CoglOnscreenTemplate *onscreen_template);
 111
 112 /**
 113  * cogl_display_get_renderer:
 114  * @display: a #CoglDisplay
 115  *
 116  * Queries the #CoglRenderer associated with the given @display.
 117  *
 118  * Since: 1.10
 119  * Stability: unstable
 120  */
 121 CoglRenderer *
 122 cogl_display_get_renderer (CoglDisplay *display);
 123
 124 /**
 125  * cogl_display_setup:
 126  * @display: a #CoglDisplay
 127  * @error: return location for a #GError
 128  *
 129  * Explicitly sets up the given @display object. Use of this api is
 130  * optional since Cogl will internally setup the display if not done
 131  * explicitly.
 132  *
 133  * When a display is first allocated via cogl_display_new() it is in a
 134  * mutable configuration mode. This allows us to extend the apis
 135  * available for configuring a display without requiring huge numbers
 136  * of constructor arguements.
 137  *
 138  * Its possible to request a configuration that might not be
 139  * supportable on the current system and so this api provides a means
 140  * to apply the configuration explicitly but if it fails then an
 141  * exception will be returned so you can handle the error gracefully
 142  * and perhaps fall back to an alternative configuration.
 143  *
 144  * If you instead rely on Cogl implicitly calling cogl_display_setup()
 145  * for you then if there is an error with the configuration you won't
 146  * get an opportunity to handle that and the application may abort
 147  * with a message.  For simple applications that don't have any
 148  * fallback options this behaviour may be fine.
 149  *
 150  * Return value: Returns %TRUE if there was no error, else it returns
 151  *               %FALSE and returns an exception via @error.
 152  * Since: 1.10
 153  * Stability: unstable
 154  */
 155 gboolean
 156 cogl_display_setup (CoglDisplay *display,
 157                     GError **error);
 158
 159 #ifdef COGL_HAS_EGL_PLATFORM_GDL_SUPPORT
 160 /**
 161  * cogl_gdl_display_set_plane:
 162  * @display: a #CoglDisplay
 163  *
 164  * Request that Cogl output to a specific GDL overlay @plane.
 165  *
 166  * Since: 1.10
 167  * Stability: unstable
 168  */
 169 void
 170 cogl_gdl_display_set_plane (CoglDisplay *display,
 171                             gdl_plane_id_t plane);
 172 #endif
 173
 174 #ifdef COGL_HAS_WAYLAND_EGL_SERVER_SUPPORT
 175 /**
 176  * cogl_wayland_display_set_compositor_display:
 177  * @display: a #CoglDisplay
 178  * @wayland_display: A compositor's Wayland display pointer
 179  *
 180  * Informs Cogl of a compositor's Wayland display pointer. This
 181  * enables Cogl to register private wayland extensions required to
 182  * pass buffers between the clients and compositor.
 183  *
 184  * Since: 1.10
 185  * Stability: unstable
 186  */
 187 void
 188 cogl_wayland_display_set_compositor_display (CoglDisplay *display,
 189                                           struct wl_display *wayland_display);
 190 #endif
 191
 192 /**
 193  * cogl_is_display:
 194  * @object: A #CoglObject pointer
 195  *
 196  * Gets whether the given object references a #CoglDisplay.
 197  *
 198  * Return value: %TRUE if the object references a #CoglDisplay
 199  *   and %FALSE otherwise.
 200  * Since: 1.10
 201  * Stability: unstable
 202  */
 203 gboolean
 204 cogl_is_display (void *object);
 205
 206 G_END_DECLS
 207
 208 #endif /* __COGL_DISPLAY_H__ */
 209