src/lib/elm_glview.h

   1 /**
   2  * @defgroup GLView GLView
   3  *
   4  * A GLView widget allows for simple GL rendering in elementary environment.
   5  * GLView hides all the complicated evas_gl details so that the user only
   6  * has to deal with registering a few callback functions for rendering
   7  * to a surface using OpenGL APIs.
   8  *
   9  * Below is an illustrative example of how to use GLView and and OpenGL
  10  * to render in elementary environment.
  11  * @ref glview_example_01_page
  12  *
  13  */
  14
  15 typedef void (*Elm_GLView_Func_Cb)(Evas_Object *obj);
  16
  17 typedef enum _Elm_GLView_Mode
  18 {
  19    ELM_GLVIEW_NONE    = 0,
  20    ELM_GLVIEW_ALPHA   = (1<<1), /**< Alpha channel enabled rendering mode */
  21    ELM_GLVIEW_DEPTH   = (1<<2), /**< Depth buffer enabled rendering mode */
  22    ELM_GLVIEW_STENCIL = (1<<3), /**< Stencil buffer enabled rendering mode */
  23    ELM_GLVIEW_DIRECT  = (1<<4)  /**< Direct rendering optimization hint */
  24 } Elm_GLView_Mode;
  25
  26 /**
  27  * Defines a policy for the glview resizing.
  28  *
  29  * The resizing policy tells glview what to do with the underlying
  30  * surface when resize happens. ELM_GLVIEW_RESIZE_POLICY_RECREATE
  31  * will destroy the current surface and recreate the surface to the
  32  * new size.  ELM_GLVIEW_RESIZE_POLICY_SCALE will instead keep the
  33  * current surface but only display the result at the desired size
  34  * scaled.
  35  *
  36  * @note Default is ELM_GLVIEW_RESIZE_POLICY_RECREATE
  37  */
  38 typedef enum
  39 {
  40    ELM_GLVIEW_RESIZE_POLICY_RECREATE = 1, /**< Resize the internal surface along with the image */
  41    ELM_GLVIEW_RESIZE_POLICY_SCALE    = 2  /**< Only resize the internal image and not the surface */
  42 } Elm_GLView_Resize_Policy;
  43
  44 /**
  45  * Defines a policy for gl rendering.
  46  *
  47  * The rendering policy tells glview where to run the gl rendering code.
  48  * ELM_GLVIEW_RENDER_POLICY_ON_DEMAND tells glview to call the rendering
  49  * calls on demand, which means that the rendering code gets called
  50  * only when it is visible.
  51  *
  52  * @note Default is ELM_GLVIEW_RENDER_POLICY_ON_DEMAND
  53  */
  54 typedef enum
  55 {
  56    ELM_GLVIEW_RENDER_POLICY_ON_DEMAND = 1, /**< Render only when there is a need for redrawing */
  57    ELM_GLVIEW_RENDER_POLICY_ALWAYS    = 2  /**< Render always even when it is not visible */
  58 } Elm_GLView_Render_Policy;
  59
  60 /**
  61  * Add a new glview to the parent
  62  *
  63  * @param parent The parent object
  64  * @return The new object or NULL if it cannot be created
  65  *
  66  * @ingroup GLView
  67  */
  68 EAPI Evas_Object *elm_glview_add(Evas_Object *parent);
  69
  70 /**
  71  * Sets the size of the glview
  72  *
  73  * @param obj The glview object
  74  * @param w width of the glview object
  75  * @param h height of the glview object
  76  *
  77  * @ingroup GLView
  78  */
  79 EAPI void         elm_glview_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
  80
  81 /**
  82  * Gets the size of the glview.
  83  *
  84  * @param obj The glview object
  85  * @param w width of the glview object
  86  * @param h height of the glview object
  87  *
  88  * Note that this function returns the actual image size of the
  89  * glview.  This means that when the scale policy is set to
  90  * ELM_GLVIEW_RESIZE_POLICY_SCALE, it'll return the non-scaled
  91  * size.
  92  *
  93  * @ingroup GLView
  94  */
  95 EAPI void         elm_glview_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
  96
  97 /**
  98  * Gets the gl api struct for gl rendering
  99  *
 100  * @param obj The glview object
 101  * @return The api object or NULL if it cannot be created
 102  *
 103  * @ingroup GLView
 104  */
 105 EAPI Evas_GL_API *elm_glview_gl_api_get(const Evas_Object *obj);
 106
 107 /**
 108  * Set the mode of the GLView. Supports alpha, depth, stencil.
 109  *
 110  * @param obj The glview object
 111  * @param mode The mode Options OR'ed enabling Alpha, Depth, Stencil, Direct.
 112  * @return True if set properly.
 113  *
 114  * Direct is a hint for the elm_glview to render directly to the window
 115  * given that the right conditions are met. Otherwise it falls back
 116  * to rendering to an offscreen buffer before it gets composited to the
 117  * window.
 118  *
 119  * @ingroup GLView
 120  */
 121 EAPI Eina_Bool    elm_glview_mode_set(Evas_Object *obj, Elm_GLView_Mode mode);
 122
 123 /**
 124  * Set the resize policy for the glview object.
 125  *
 126  * @param obj The glview object.
 127  * @param policy The scaling policy.
 128  *
 129  * By default, the resize policy is set to ELM_GLVIEW_RESIZE_POLICY_RECREATE.
 130  * When resize is called it destroys the previous surface and recreates the
 131  * newly specified size. If the policy is set to
 132  * ELM_GLVIEW_RESIZE_POLICY_SCALE, however, glview only scales the image
 133  * object and not the underlying GL Surface.
 134  *
 135  * @ingroup GLView
 136  */
 137 EAPI Eina_Bool    elm_glview_resize_policy_set(Evas_Object *obj, Elm_GLView_Resize_Policy policy);
 138
 139 /**
 140  * Set the render policy for the glview object.
 141  *
 142  * @param obj The glview object.
 143  * @param policy The render policy.
 144  *
 145  * By default, the render policy is set to ELM_GLVIEW_RENDER_POLICY_ON_DEMAND.
 146  * This policy is set such that during the render loop, glview is only
 147  * redrawn if it needs to be redrawn. (i.e. when it is visible) If the policy
 148  * is set to ELM_GLVIEWW_RENDER_POLICY_ALWAYS, it redraws regardless of
 149  * whether it is visible or needs redrawing.
 150  *
 151  * @ingroup GLView
 152  */
 153 EAPI Eina_Bool    elm_glview_render_policy_set(Evas_Object *obj, Elm_GLView_Render_Policy policy);
 154
 155 /**
 156  * Set the init function that runs once in the main loop.
 157  *
 158  * @param obj The glview object.
 159  * @param func The init function to be registered.
 160  *
 161  * The registered init function gets called once during the render loop.
 162  * This function allows glview to hide all the rendering context/surface
 163  * details and have the user just call GL calls that they desire
 164  * for initialization GL calls.
 165  *
 166  * @ingroup GLView
 167  */
 168 EAPI void         elm_glview_init_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
 169
 170 /**
 171  * Set the render function that runs in the main loop.
 172  *
 173  * @param obj The glview object.
 174  * @param func The delete function to be registered.
 175  *
 176  * The registered del function gets called when GLView object is deleted.
 177  * This function allows glview to hide all the rendering context/surface
 178  * details and have the user just call GL calls that they desire
 179  * when delete happens.
 180  *
 181  * @ingroup GLView
 182  */
 183 EAPI void         elm_glview_del_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
 184
 185 /**
 186  * Set the resize function that gets called when resize happens.
 187  *
 188  * @param obj The glview object.
 189  * @param func The resize function to be registered.
 190  *
 191  * The resize function gets called during the render loop.
 192  * This function allows glview to hide all the rendering context/surface
 193  * details and have the user just call GL calls that they desire
 194  * when resize happens.
 195  *
 196  * @ingroup GLView
 197  */
 198 EAPI void         elm_glview_resize_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
 199
 200 /**
 201  * Set the render function that runs in the main loop.
 202  *
 203  * The render function gets called in the main loop but whether it runs
 204  * depends on the rendering policy and whether elm_glview_changed_set()
 205  * gets called.
 206  *
 207  * @param obj The glview object.
 208  * @param func The render function to be registered.
 209  *
 210  * @ingroup GLView
 211  */
 212 EAPI void         elm_glview_render_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
 213
 214 /**
 215  * Notifies that there has been changes in the GLView.
 216  *
 217  * @param obj The glview object.
 218  *
 219  * @ingroup GLView
 220  */
 221 EAPI void         elm_glview_changed_set(Evas_Object *obj);
 222
 223 /**
 224  * @}
 225  */