<p>EGL is an adhesive layer between OpenGL ES and the underlying native platform window system. EGL communicates with the Window system to get information on the application window, creates the drawing surface, and manages rendering context and resources.</p>\r
\r
<p class="figure">Figure: OpenGL ES structure</p> \r
- <p align="center"><img alt="OpenGL® ES structure" src="../../images/opengl1.png" /></p> \r
+ <p align="center"><img alt="OpenGL ES structure" src="../../images/opengl1.png" /></p> \r
\r
<h2 id="tizen" name="tizen">OpenGL ES in Tizen</h2>\r
\r
<p>Tizen native applications do not depend on the Window system, because the Window system is an internal Tizen module, which can be enhanced or replaced. EFL provides a method that draws the OpenGL ES content and encapsulates the EGL and the native Window system.</p>\r
\r
<p class="figure">Figure: OpenGL ES and EFL</p> \r
- <p align="center"><img alt="OpenGL® ES and EFL" src="../../images/opengl2.png" /></p> \r
+ <p align="center"><img alt="OpenGL ES and EFL" src="../../images/opengl2.png" /></p> \r
\r
<p>A GLView creates a drawable GL surface for the application, and sets up all the required callbacks. The application can use GLView with various UI components, such as toolbar or button.</p>\r
\r
\r
<h3>EvasGL vs. GLView</h3>\r
\r
-<p>While it is possible to create an OpenGL application by just using EvasGL, it could be difficult to comprehend due to the low-level nature of these APIs. However, it enables detailed operations.</p>\r
+<p>While it is possible to create an OpenGL ES application by just using EvasGL, it could be difficult to comprehend due to the low-level nature of these APIs. However, it enables detailed operations.</p>\r
\r
<h2 id="glview" name="glview">GLView Programming Guide</h2>\r
\r
\r
<p>The easiest way to use OpenGL ES within a Tizen application is to rely on the GLView component.</p>\r
\r
-<p>GLView is a simple Elementary UI component that sets up an OpenGL ES target surface and a context, and allows you to embed it in any Tizen application. GLView is basically a wrapper around EvasGL, the OpenGL-ES/EGL abstraction layer of EFL.</p>\r
+<p>GLView is a simple Elementary UI component that sets up an OpenGL ES target surface and a context, and allows you to embed it in any Tizen application. GLView is basically a wrapper around EvasGL, the OpenGL ES/EGL abstraction layer of EFL.</p>\r
\r
-<p>To create a basic application:</p>\r
+<h3>To create a basic application:</h3>\r
\r
-<p>To develop a GL application, you have to call <span style="font-family: Courier New,Courier,monospace">elm_config_accel_preference_set</span> before creating a window. It makes an application to use GPU. To use the Direct Rendering mode since Tizen 2.4, you have to set the same option values (depth, stencil, and MSAA) to a rendering engine and a GLView object. You can set the option values to a rendering engine using the <span style="font-family: Courier New,Courier,monospace">elm_config_accel_preference_set()</span> function and to a GLView object using the <span style="font-family: Courier New,Courier,monospace">elm_glview_mode_set()</span> function. If the GLView object option values are bigger or higher than the rendering engine's, the Direct Rendering mode is disabled.</p>\r
-\r
-<p>First, you should declare the global variable using <span style="font-family: Courier New,Courier,monospace">ELEMENTARY_GLVIEW_GLOBAL_DEFINE()</span>, then create a GLView object and use <span style="font-family: Courier New,Courier,monospace">ELEMENTARY_GLVIEW_GLOBAL_USE(glview)</span>. Now, you can call GL functions.</p>\r
+<p>First, you can declare the global variable using ELEMENTARY_GLVIEW_GLOBAL_DEFINE(), then create a GLView object and use ELEMENTARY_GLVIEW_GLOBAL_USE(glview). These macro help that you can call GL functions directly. Now, you can call GL functions. If you want to know that detail, refer Elementary_GL_Helpers.h, please.</p>\r
\r
<pre class="prettyprint">\r
#include <app.h>\r
#include <Elementary_GL_Helpers.h>\r
\r
-ELEMENTARY_GLVIEW_GLOBAL_DEFINE()\r
+/*\r
+ * This code to place at the beginning of any function using GLES 2.0 APIs.\r
+ * When using this macro, developers can then call all glFunctions without changing their code.\r
+ * If you want to know that detail, refer Elementary_GL_Helpers.h.\r
+ */\r
\r
-typedef struct appdata \r
-{\r
- Evas_Object *win;\r
- Evas_Object *glview;\r
- unsigned int program;\r
- unsigned int vtx_shader;\r
- unsigned int fgmt_shader;\r
- unsigned int vbo;\r
-} appdata_s;\r
+ELEMENTARY_GLVIEW_GLOBAL_DEFINE()\r
+</pre>\r
\r
-static Evas_Object *glview_create(Evas_Object *win);\r
-static void glview_start(Evas_Object *glview);\r
+<ol>\r
+ <li>HW acceleration</li>\r
+ <p>To develop a GL application, you have to call <span style="font-family: Courier New,Courier,monospace">elm_config_accel_preference_set</span> before creating a window. It makes an application to use GPU. This function is supported since Tizen 2.3.</p>\r
+ <p>To use the Direct Rendering mode of EvasGL or EFL WebKit(EWK), you have to set the same option values (depth, stencil and MSAA) to a rendering engine and a GLView object. EWK's options are depth24 and stencil8. You can set the option values to a rendering engine using the <span style="font-family: Courier New,Courier,monospace">elm_config_accel_preference_set()</span> function and to a GLView object using the <span style="font-family: Courier New,Courier,monospace">elm_glview_mode_set()</span> function. If the GLView object option values are bigger or higher than the rendering engine's, the Direct Rendering mode is disabled or abnormal rendering occurs. These special options will be supported since Tizen 2.3.1.</p>\r
\r
-// GLView callback functions\r
-static void draw_gl(Evas_Object *obj);\r
-static void init_gl(Evas_Object *obj);\r
-static void resize_gl(Evas_Object *obj);\r
-static void del_gl(Evas_Object *obj);\r
\r
+<pre class="prettyprint">\r
static bool app_create(void *data) \r
{\r
appdata_s *ad = data;\r
ad->win = elm_win_util_standard_add("GLView example", "GLView example");\r
evas_object_show(ad->win);\r
ad->glview = ad->glview_create(ad->win);\r
+/*\r
+ * This macro will set the global variable holding the GL API,\r
+ * so that it's available to the application.\r
+ * It should be used right after setting up the GL context object.\r
+ * If you want to know that detail, refer Elementary_GL_Helpers.h\r
+ */\r
ELEMENTARY_GLVIEW_GLOBAL_USE(ad->glview);\r
glview_start(ad->glview);\r
\r
return true;\r
}</pre>\r
\r
-<p>Add the OpenGL ES view to the application:</p>\r
+<li>Add the OpenGL ES view to the application</li>\r
\r
<pre class="prettyprint">\r
// This is the GL initialization function\r
\r
return glview;\r
}</pre>\r
+</ol>\r
\r
<h3>Setting up the Callbacks</h3>\r
\r
\r
<ol>\r
<li>Callback for initialization\r
- <p>The initialization callback will be called when the GLView is created, after a valid openGL ES context and surface are created. Initialization, resizing, drawing, and deleting callback are called in the main loop.</p>\r
+ <p>The initialization callback is called when the GLView is created, after a valid OpenGL ES context and surface have been created. This is called from the main loop, just as the 3 other callbacks.</p>\r
\r
<pre class="prettyprint">\r
// GL Init function\r
static void init_gl(Evas_Object *glview)\r
{\r
- glClearColor(0, 0, 0, 0);\r
- glClear(GL_COLOR_BUFFER_BIT);\r
+ glClearColor(0.0, 0.0, 0.0, 1.0);\r
+ glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT);\r
\r
// Do any form of OpenGL ES initialization here\r
// init_shaders();\r
}</pre>\r
</li>\r
<li>Callback for drawing\r
- <p>The drawing callback is called whenever a new frame has to be drawn. The exact moment when this function is called depends on the policy.</p>\r
+ <p>The drawing callback is called whenever a new frame has to be drawn. The exact moment when this function is called depends on the policy set when calling.</p>\r
\r
<pre class="prettyprint">\r
elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);</pre>\r
}</pre>\r
</li>\r
<li>Add an animator.\r
- <p>The application above is technically working but the scene does not get updated unless the frame is marked as dirty. Game applications might need to use an animator to obtain continuous update of the scenes. Here is an example for a default update refresh rate:</p>\r
+ <p>The application above is technically working but the scene does not get updated unless the frame is marked as such. Games might want to use an animator to have a regular update of the scene. Here is an example for a default update refresh rate:</p>\r
\r
<pre class="prettyprint">\r
static Eina_Bool anim_cb(void *data)\r
\r
<pre class="prettyprint">\r
Evas_GL *evgl = elm_glview_evas_gl_get(glview);\r
-// Then it is possible to call any evas_gl function with it, for example:\r
-Evas_GL_Context *ctx = evas_gl_current_context_get(evgl);\r
-Evas_GL_Surface *pbuf = evas_gl_pbuffer_surface_create(evgl, cfg, w, h, NULL);</pre>\r
+// Then it is possible to call any evas_gl function with it, for example:</pre>\r
\r
\r
<table class="note"> \r
\r
<p>This guide assumes that the application uses EvasGL directly instead of using the GLView. (If the application uses a GLView, EvasGL is created internally.)</p>\r
\r
+<p>First, you can declare the global variable using EVAS_GL_GLOBAL_GLES2_DEFINE(), then create a EvasGL and use EVAS_GL_GLOBAL_GLES2_USE(evasgl, evasgl’s context). It is similar to the GLView’s macro. These macro help that you can call GL functions directly. Now, you can call GL functions. If you want to know that detail, refer Evas_GL_GLES2_Helpers.h.</p>\r
+\r
+<pre class="prettyprint">\r
+#include <app.h>\r
+#include <Evas_GL_GLES2_Helpers.h>\r
+...\r
+/*\r
+ * This code to place at the beginning of any function using GLES 2.0 APIs.\r
+ * When using this macro, developers can then call all glFunctions without changing their code\r
+ * If you want to know that detail, refer Evas_GL_GLES2_Helpers.h.\r
+ */\r
+EVAS_GL_GLOBAL_GLES2_DEFINE();\r
+</pre>\r
+\r
<h3>Declaration of EvasGL Objects</h3>\r
\r
<p>This is how to define the application data structure to hold all the objects for your EvasGL application:</p>\r
\r
-<ul>\r
- <li><span style="font-family: Courier New,Courier,monospace">Evas_Object *win</span>: Application window.</li>\r
- <li><span style="font-family: Courier New,Courier,monospace">Evas_Object *img</span>: OpenGL ES canvas.</li>\r
- <li><span style="font-family: Courier New,Courier,monospace">Evas_GL *evasgl</span>: EvasGL Object for rendering gl in Evas.</li>\r
- <li><span style="font-family: Courier New,Courier,monospace">Evas_GL_API *glapi</span>: EvasGL API object that contains the GL APIs to be used in Evas GL.</li>\r
- <li><span style="font-family: Courier New,Courier,monospace">Evas_GL_Context *ctx</span>: EvasGL Context object, a GL rendering context in Evas GL.</li>\r
- <li><span style="font-family: Courier New,Courier,monospace">Evas_GL_Surface *sfc</span>: EvasGL Surface object, a GL rendering target in Evas GL.</li>\r
- <li><span style="font-family: Courier New,Courier,monospace">Evas_GL_Config *cfg</span>: EvasGL Surface configuration object for surface creation.</li>\r
-</ul>\r
-\r
<pre class="prettyprint">\r
typedef struct appdata \r
{\r
unsigned int vbo;\r
} appdata_s;</pre>\r
\r
-<h3>Creating EvasGL</h3>\r
+<ul>\r
+ <li><span style="font-family: Courier New,Courier,monospace">Evas_Object *win</span>: Application window.</li>\r
+ <li><span style="font-family: Courier New,Courier,monospace">Evas_Object *img</span>: OpenGL ES canvas.</li>\r
+ <li><span style="font-family: Courier New,Courier,monospace">Evas_GL *evasgl</span>: EvasGL Object for rendering gl in Evas.</li>\r
+ <li><span style="font-family: Courier New,Courier,monospace">Evas_GL_API *glapi</span>: EvasGL API object that contains the GL APIs to be used in Evas GL.</li>\r
+ <li><span style="font-family: Courier New,Courier,monospace">Evas_GL_Context *ctx</span>: EvasGL Context object, a GL rendering context in Evas GL.</li>\r
+ <li><span style="font-family: Courier New,Courier,monospace">Evas_GL_Surface *sfc</span>: EvasGL Surface object, a GL rendering target in Evas GL.</li>\r
+ <li><span style="font-family: Courier New,Courier,monospace">Evas_GL_Config *cfg</span>: EvasGL Surface configuration object for surface creation.</li>\r
+</ul>\r
+\r
+<h3>Creating Elm window and EvasGL</h3>\r
\r
-<p>We can create our EvasGL handler using <span style="font-family: Courier New,Courier,monospace">evas_gl_new(Evas * e)</span>. This initializer takes the Evas canvas that OpenGL ES is to be used on as a parameter. When developing an application with Elementary, we can use the canvas of our window:</p>\r
+<ol>\r
+ <li>\r
+ HW acceleration\r
+ <p>To develop a GL application, you have to call elm_config_accel_preference_set() before creating a window. It makes an application to use GPU. This function is supported since Tizen 2.3.</p>\r
+ <p>To use the Direct Rendering mode of EvasGL or EFL WebKit (EWK), you have to set the same option values (depth, stencil, and MSAA) to a rendering engine and a GLView object. EWK’s options are depth24 and stencil8. You can set the option values to a rendering engine using the elm_config_accel_preference_set() function and to a GLView object using the elm_glview_mode_set() function. If the GLView object option values are bigger or higher than the rendering engine's, the Direct Rendering mode is disabled or abnormal rendering occurs. These Special options will be supported since Tizen 2.3.1.</p>\r
\r
<pre class="prettyprint">\r
+Evas_Object *win;\r
+/*\r
+ * To use OpenGL ES, the application should turn on hardware acceleration\r
+ * To enable that, elm_config_accel_preference_set() with "opengl&quat;\r
+ * should be called before createing Elm window\r
+ * This function is supported since 2.3.\r
+ */\r
+elm_config_accel_preference_set("opengl");\r
+/* Creating Elm Window */\r
ad->win = elm_win_util_standard_add("Evas_GL Example", "Evas_GL Example");\r
-ad->evasgl = evas_gl_new(evas_object_evas_get(ad->win));</pre>\r
+</pre>\r
\r
-<p>To free the memory allocated to this handler, use <span style="font-family: Courier New,Courier,monospace">evas_gl_free(Evas_GL *evas_gl)</span>.</p>\r
+ <p>We can create our EvasGL handler using <span style="font-family: Courier New,Courier,monospace">evas_gl_new(Evas * e)</span>. This initializer takes the Evas canvas that OpenGL ES is to be used on as a parameter. When developing an application with Elementary, we can use the canvas of our window:</p>\r
\r
-<h3>Getting OpenGL ES APIs</h3>\r
+ <pre class="prettyprint">ad->evasgl = evas_gl_new(evas_object_evas_get(ad->win));</pre>\r
\r
-<p>You can get the API for rendering OpenGL ES with <span style="font-family: Courier New,Courier,monospace">evas_gl_api_get(Evas_GL *evas_gl_)</span>. This function returns a structure that contains all the OpenGL ES functions you can use to render in Evas. These functions consist of all the standard OpenGL ES2.0 functions and any extra ones Evas has decided to provide in addition. If you have your code ported to OpenGL ES 2.0, it is easy to render to Evas. (OpenGL ES 3.0 will be supported in the next Tizen version.)</p>\r
+ <p>To free the memory allocated to this handler, use <span style="font-family: Courier New,Courier,monospace">evas_gl_free(Evas_GL *evas_gl)</span>.</p>\r
+ </li>\r
\r
-<pre class="prettyprint">\r
-ad->glapi = evas_gl_api_get(ad->evasgl);</pre>\r
+ <li>Creating a Surface\r
\r
-<h3>Creating a Surface</h3>\r
-\r
-<p>We must allocate a new config object to fill it out using <span style="font-family: Courier New,Courier,monospace">evas_gl_config_new()</span>. As long as Evas creates a config object for the user, it takes care of the backward compatibility issue. Once we have our config object, we can specify the surface settings:</p>\r
+ <p>We must allocate a new config object to fill it out using <span style="font-family: Courier New,Courier,monospace">evas_gl_config_new()</span>. As long as Evas creates a config object for the user, it takes care of the backward compatibility issue. Once we have our config object, we can specify the surface settings:</p>\r
\r
<pre class="prettyprint">\r
appdata_s *ad;\r
ad->cfg->color_format = EVAS_GL_RGBA_8888; // Surface Color Format\r
ad->cfg->depth_bits = EVAS_GL_DEPTH_BIT_24; // Surface Depth Format\r
ad->cfg->stencil_bits = EVAS_GL_STENCIL_NONE; // Surface Stencil Format\r
-ad->cfg->options_bits = EVAS_GL_OPTIONS_NONE; // Configuration options (here, no extra options)</pre>\r
+ad->cfg->options_bits = EVAS_GL_OPTIONS_NONE; // Configuration options (here, no extra options)\r
+</pre>\r
\r
-<p>Once we have configured the surface behavior, we must initialize the surface using <span style="font-family: Courier New,Courier,monospace">evas_gl_surface_create(Evas_GL* evas_gl, Evas_GL_Config * cfg, int w, int h)</span>. This function takes the given Evas_GL object as the first parameter and the pixel format, and configuration of the rendering surface as the second parameter. The last two parameters are the width and height of the surface, which we recover directly from the window.</p>\r
+
<p>Once we have configured the surface behavior, we must initialize the surface using <span style="font-family: Courier New,Courier,monospace">evas_gl_surface_create(Evas_GL* evas_gl, Evas_GL_Config * cfg, int w, int h)</span>. This function takes the given Evas_GL object as the first parameter and the pixel format, and configuration of the rendering surface as the second parameter. The last two parameters are the width and height of the surface, which we recover directly from the window.</p>
\r \r
<pre class="prettyprint">\r
Evas_Coord w, h;\r
evas_object_geometry_get(ad->win, NULL, NULL, &w, &h);\r
-ad->sfc = evas_gl_surface_create(ad->evasgl, ad->cfg, w, h);</pre>\r
+ad->sfc = evas_gl_surface_create(ad->evasgl, ad->cfg, w, h);\r
+</pre>\r
\r
-<p>To manually delete a GL surface, use <span style="font-family: Courier New,Courier,monospace">evas_gl_surface_destroy(Evas_GL *evas_gl, Evas_GL_Surface *surf)</span>.</p>\r
+ <p>To manually delete a GL surface, use <span style="font-family: Courier New,Courier,monospace">evas_gl_surface_destroy(Evas_GL *evas_gl, Evas_GL_Surface *surf)</span>.</p>\r
+ </li>\r
\r
-<h3>Creating Context</h3>\r
+ <li>Creating a Context\r
\r
-<p>Here, we create a context for Evas_GL using <span style="font-family: Courier New,Courier,monospace">evas_gl_context_create(Evas_GL * evas_gl, Evas_GL_Context * share_ctx)</span>. You can merge the context with a higher context definition you must pass as a second parameter.</p>\r
+
<p>Here, we create a context for Evas_GL using <span style="font-family: Courier New,Courier,monospace">evas_gl_context_create(Evas_GL * evas_gl, Evas_GL_Context * share_ctx)</span>. You can merge the context with a higher context definition you must pass as a second parameter.</p>
\r \r
<pre class="prettyprint">\r
-ad->ctx = evas_gl_context_create(ad->evasgl, NULL);</pre>\r
+ad->ctx = evas_gl_context_create(ad->evasgl, NULL);\r
+/*\r
+ * This macro will set the global variable holding the GL API,\r
+ * so that it's available to the application.\r
+ * It should be used right after setting up the GL context object.\r
+ * If you want to know that detail, refer Evas_GL_GLES2_Helpers.h.\r
+ */\r
+EVAS_GL_GLOBAL_GLES2_USE(ad->evasgl, ad->ctx);\r
+</pre>\r
+\r
+ <p>To delete the context later, use <span style="font-family: Courier New,Courier,monospace">evas_gl_context_destroy(Evas_GL *evas_gl, Evas_GL_Context *ctx)</span>. To delete the entire configuration object, use <span style="font-family: Courier New,Courier,monospace">evas_gl_config_free(Evas_GL_Config *cfg)</span> instead.</p>\r
+ </li>\r
+</ol>\r
\r
-<p>To delete the context later, use <span style="font-family: Courier New,Courier,monospace">evas_gl_context_destroy(Evas_GL *evas_gl, Evas_GL_Context *ctx)</span>. To delete the entire configuration object, use <span style="font-family: Courier New,Courier,monospace">evas_gl_config_free(Evas_GL_Config *cfg)</span> instead.</p>\r
+<h3>Getting OpenGL ES APIs</h3>\r
+\r
+<p>If you want to get the API of OpenGL ES, You can get the API for rendering OpenGL ES with <span style="font-family: Courier New,Courier,monospace">evas_gl_api_get(Evas_GL *evas_gl_)</span>. This function returns a structure that contains all the OpenGL ES functions you can use to render in Evas. These functions consist of all the standard OpenGL ES 2.0 functions and any extra ones Evas has decided to provide in addition. If you have your code ported to OpenGL ES 2.0, it is easy to render to Evas. (OpenGL ES 3.0 will be supported in the next Tizen version.)</p>\r
+\r
+<p>If you already use global macro as a EVAS_GL_GLOBAL_GLES2_XXX, you need not get the APIs.</p>\r
+\r
+<pre class="prettyprint">\r
+ad->glapi = evas_gl_api_get(ad->evasgl);</pre>\r
\r
<h3>Callbacks</h3>\r
\r
Evas_Native_Surface ns;\r
evas_gl_native_surface_get(ad->evasgl, ad->sfc, &ns);\r
evas_object_image_native_surface_set(ad->img, &ns);</pre>\r
-\r
\r
<script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>\r
<script type="text/javascript" src="../../scripts/showhide.js"></script>\r
projects / sdk / online-doc.git / commitdiff