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