src/lib/elm_glview.h

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