2 * @defgroup GLView GLView
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.
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
16 typedef void (*Elm_GLView_Func_Cb)(Evas_Object *obj);
18 typedef enum _Elm_GLView_Mode
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 */
28 * Defines a policy for the glview resizing.
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
37 * @note Default is ELM_GLVIEW_RESIZE_POLICY_RECREATE
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;
46 * Defines a policy for gl rendering.
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.
53 * @note Default is ELM_GLVIEW_RENDER_POLICY_ON_DEMAND
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;
62 * Add a new glview to the parent
64 * @param parent The parent object
65 * @return The new object or NULL if it cannot be created
69 EAPI Evas_Object *elm_glview_add(Evas_Object *parent);
72 * Sets the size of the glview
74 * @param obj The glview object
75 * @param w width of the glview object
76 * @param h height of the glview object
80 EAPI void elm_glview_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
83 * Gets the size of the glview.
85 * @param obj The glview object
86 * @param w width of the glview object
87 * @param h height of the glview object
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
96 EAPI void elm_glview_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
99 * Gets the gl api struct for gl rendering
101 * @param obj The glview object
102 * @return The api object or NULL if it cannot be created
106 EAPI Evas_GL_API *elm_glview_gl_api_get(const Evas_Object *obj);
109 * Set the mode of the GLView. Supports alpha, depth, stencil.
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.
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
122 EAPI Eina_Bool elm_glview_mode_set(Evas_Object *obj, Elm_GLView_Mode mode);
125 * Set the resize policy for the glview object.
127 * @param obj The glview object.
128 * @param policy The scaling policy.
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.
138 EAPI Eina_Bool elm_glview_resize_policy_set(Evas_Object *obj, Elm_GLView_Resize_Policy policy);
141 * Set the render policy for the glview object.
143 * @param obj The glview object.
144 * @param policy The render policy.
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.
154 EAPI Eina_Bool elm_glview_render_policy_set(Evas_Object *obj, Elm_GLView_Render_Policy policy);
157 * Set the init function that runs once in the main loop.
159 * @param obj The glview object.
160 * @param func The init function to be registered.
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.
169 EAPI void elm_glview_init_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
172 * Set the render function that runs in the main loop.
174 * @param obj The glview object.
175 * @param func The delete function to be registered.
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.
184 EAPI void elm_glview_del_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
187 * Set the resize function that gets called when resize happens.
189 * @param obj The glview object.
190 * @param func The resize function to be registered.
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.
199 EAPI void elm_glview_resize_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
202 * Set the render function that runs in the main loop.
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()
208 * @param obj The glview object.
209 * @param func The render function to be registered.
213 EAPI void elm_glview_render_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
216 * Notifies that there has been changes in the GLView.
218 * @param obj The glview object.
222 EAPI void elm_glview_changed_set(Evas_Object *obj);