src/lib/elm_glview.h

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