<li><a href="#source">Viewing the Entire Cube Source</a></li>
</ul>
</li>
- <li><a href="#multithread">Using OpenGL ES in Multi-threaded Applications</a></li>
<li><a href="#ext">Using OpenGL ES Extensions</a></li>
<li><a href="#evas_ext">Using EvasGL Extensions</a></li>
<li><a href="#direct">Using Direct Rendering</a></li>
<li><a href="#source">Viewing the Entire Cube Source</a>
<p>View the entire source code of the cube example.</p></li>
</ul> </li>
- <li><a href="#multithread">Using OpenGL ES in Multi-threaded Applications</a>
- <p>Share OpenGL ES data across threads, synchronize data, and pass messages between threads.</p></li>
<li><a href="#ext">Using OpenGL ES Extensions</a>
<p>Check whether an extension is available, and call it.</p></li>
<li><a href="#evas_ext">Using EvasGL Extensions</a>
<h2 id="basic" name="basic">Creating the Basic Application</h2>
-<p>This tutorial demonstrates how you can create a multicolored 3D rotating cube using the OpenGL ES 2.0 API provided by the GLView library. Several concepts are explained, such as the cube geometry, the initialization phase of the model, the adjustment of this very model frame by frame, and the way to design the OpenGL ES rendering loop.</p>
-<p>To create the basic application:</p>
-<ol>
-<li><p>Create a basic application as explained in the Basic application tutorial. The basic UI application skeleton already makes available the window object that contains the GLView canvas.</p>
-</li>
-<li>Build the environment:
-
+<p>This tutorial demonstrates how you can create a multicolored 3D rotating cube using OpenGL ES 2.0 API provided by GLView library. Several concepts are explained, such as the cube geometry, the initialization phase of the model, the adjustment of this very model frame by frame, and the way to design the OpenGL ES rendering loop.</p>
+<p>First create a basic application as explained in the Basic application tutorial. This provides a basic UI application skeleton which already makes available the window object that contains the GLView canvas.</p>
+<h3>Building the Environment</h3>
<p>Define the application data structure that holds all the objects pertinent for the GLView application:</p>
<ul>
<li><span style="font-family: Courier New,Courier,monospace">Evas_Object *win</span>: Application window</li>
Evas_Object *main_box;
Evas_Object *inner_box;
} appdata_s;
-</pre></li>
+</pre>
-<li>
+<h3>OpenGL ES Canvas</h3>
+
+<p>When developing an application with Elementary, you can create a window by using the Elementary utility function as below:</p>
-<p>Create the OpenGL ES canvas:</p>
-<ol type="a">
-<li>
-<p>When developing an application with Elementary, you can create a window by using the Elementary utility function:</p>
<pre class="prettyprint">
elm_config_accel_preference_set("opengl");
ad->win = elm_win_util_standard_add("GLView Example", "GLView Example");</pre>
-</li>
-<li>
-<p>To develop a GL application, you have to call the <span style="font-family: Courier New,Courier,monospace">elm_config_accel_preference_set()</span> function before creating a window which makes an application to use the GPU.</p>
+
+<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 which makes an application to use GPU.</p>
+
<pre class="prettyprint">
ad->glview = elm_glview_add(ad->main_box);</pre>
-<p>There are 2 different methods to call the GL functions:</p>
+<p>There are 2 different methods to call GL functions.</p>
+
+<ul><li>First is to use Elementary GL Helper functions. You have to include <span style="font-family: Courier New,Courier,monospace">Elementary_GL_Helpers.h</span> and define a global variable by using <span style="font-family: Courier New,Courier,monospace">ELEMENTARY_GLVIEW_GLOBAL_DEFINE()</span>. Before calling gl functions, write <span style="font-family: Courier New,Courier,monospace">ELEMENTARY_GLVIEW_GLOBAL_USE()</span>. This tutorial uses this method. The usage is as follows.
-<ul><li>Use the Elementary GL Helper functions. You have to include the <span style="font-family: Courier New,Courier,monospace">Elementary_GL_Helpers.h</span> header file and define a global variable using the <span style="font-family: Courier New,Courier,monospace">ELEMENTARY_GLVIEW_GLOBAL_DEFINE()</span> function. Before calling the gl functions, write the <span style="font-family: Courier New,Courier,monospace">ELEMENTARY_GLVIEW_GLOBAL_USE()</span> function. This tutorial uses this method.
<pre class="prettyprint">
#include <Elementary_GL_Helpers.h>
ELEMENTARY_GLVIEW_GLOBAL_DEFINE();
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
}</pre></li>
-<li><p>Get the Evas_GL instance from the <span style="font-family: Courier New,Courier,monospace">elm_glview_gl_api_get()</span> function, and call the OpenGL ES functions with the instance.</p>
+<li><p>Second, you can get the Evas_GL instance from <span style="font-family: Courier New,Courier,monospace">elm_glview_gl_api_get</span> function, then you can call the OpenGL ES functions with the instance.</p>
<pre class="prettyprint">
ad->glview = elm_glview_add(ad->main_box);
Evas_GL_API *glapi = elm_glview_gl_api_get(ad->glview);
glapi->glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);</pre></li></ul>
-</li>
-<li>
-<p>Set the GLView mode. The <span style="font-family: Courier New,Courier,monospace">elm_glview_mode_set()</span> function supports alpha, depth, stencil, MSAA, and client_side_rotation.</p>
+
+<p>The next thing to do is to set the GLView mode. <span style="font-family: Courier New,Courier,monospace">elm_glview_mode_set(Evas_Object *obj, Elm_GLView_Mode mode)</span> supports alpha, depth, stencil, MSAA, and client_side_rotation.</p>
<pre class="prettyprint">
elm_glview_mode_set(ad->glview, ELM_GLVIEW_DEPTH);</pre>
-</li>
-<li>
-<p>Set up callbacks:</p>
+
+<p>To set up callbacks:</p>
+
+<pre class="prettyprint">
+elm_glview_init_func_set(ad->glview, init_gl);
+elm_glview_resize_func_set(ad->glview, resize_gl);
+elm_glview_render_func_set(ad->glview, draw_gl);
+elm_glview_del_func_set(ad->glview, del_gl);
+ani = ecore_animator_add(animate_cb, ad->glview);</pre>
+
<ul>
<li>Callback for initialization
<p>The initialization callback is called when the GLView is first 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>
- <pre class="prettyprint">
-elm_glview_init_func_set(ad->glview, init_gl);
-</pre>
</li>
<li>Callback for resizing
<p>The resize callback is called whenever the GLView component is resized. A common action to take here is to reset the viewport.</p>
- <pre class="prettyprint">
-elm_glview_resize_func_set(ad->glview, resize_gl);
-</pre>
</li>
<li>Callback for drawing
- <p>The drawing callback is called whenever a new frame has to be drawn.</p>
- <pre class="prettyprint">
-elm_glview_render_func_set(ad->glview, draw_gl);
-</pre>
- <p>The exact moment when this function is called depends on the policy set when calling.</p>
+ <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>
<pre class="prettyprint">
elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);</pre>
- <p>Another policy is <span style="font-family: Courier New,Courier,monospace">ELM_GLVIEW_POLICY_ALWAYS</span>, which requests render always even when it is not visible. So on demand policy is probably what you are looking for. The application can now draw anything using GL primitives when this callback is triggered. All draw operations are restricted to the surface of the GLView object previously created. Here it covers the whole window.</p>
+ <p>Another policy is ELM_GLVIEW_POLICY_ALWAYS, which requests render always even when it is not visible. So on demand policy is probably what you are looking for. The application can now draw anything using GL primitives when this callback is triggered. All draw operations are restricted to the surface of the GLView object previously created. Here it covers the whole window.</p>
</li>
<li>Callback for deleting
<p>The delete callback is triggered when the GLView is being destroyed, from the main loop, and no other callback can be called on the same object afterwards.</p>
- <pre class="prettyprint">
-elm_glview_del_func_set(ad->glview, del_gl);
-</pre>
</li>
<li>Add an animator.
- <p>The application above is technically working but the scene does not get updated unless the object is marked as such. Games want to use an animator to have a regular update of the scene.</p>
- <pre class="prettyprint">
-ani = ecore_animator_add(animate_cb, ad->glview);</pre>
+ <p>The application above is technically working but the scene does not get updated unless the object is marked as such. Games might want to use an animator to have a regular update of the scene.</p>
<p>Any other event can be used to refresh the view, for example user input if the view needs to be updated.</p>
</li>
</ul>
-</li>
-</ol>
-</li>
-</ol>
+
<h2 id="cube" name="cube">Creating the Cube</h2>
-<p>Creating and the coloring the cube can be separated into 2 distinct tasks: define the vertices and then add the colors to the faces.</p>
-<p>To create and color the cube:</p>
+<p>Creating and the coloring the cube can be separated into two distinct tasks: define the vertices and then add the colors to the faces.</p>
+
<p class="figure">Figure: Cube</p>
<p align="center"><img alt="Cube" src="../../images/cube.png" /></p>
-<ol>
-<li><p>Declare an array that stores the vertices of the cube to make it look like the drawing above.</p>
- <pre class="prettyprint">
-static const float vertices[] =
+
+<p>Declare an array that stores the vertices of the cube in order to make it look like the drawing above.</p>
+ <pre class="prettyprint">static const float vertices[] =
{
// Front
-0.5f, 0.5f, 0.5f,
<p class="figure">Figure: Cube matrix</p>
<p align="center"><img alt="Cube matrix" src="../../images/cube_matrix.png" /></p>
-<p>Each triangle is defined with 3 point coordinates, 3 vertices for each triangle, 2 triangles per face and 6 faces. There are 36 vertices is total.</p>
-</li>
-<li>
-<p>Specify a color for each face of the cube. Each color is represented in the RGBA format for the corresponding vertex, where each component is ranged from 0 to 1 where 1 is the maximum value. For example, in 32-byte color space, the RGB color of (16, 147, 237) is translated as (0.0625, 0.57421875, 0.92578125). The A of RGBA stands for the alpha channel, which represents the transparency of the color. All colors defined in this tutorial are opaque to make it simpler, so each alpha value is set to 1.0. In this example, different variants of blue are used for the faces of the cube.</p>
+<p>Each triangle is defined with three point coordinates, three vertices for each triangle, two triangles per face and six faces, so there are 36 vertices is total.</p>
+<p>The next step is to specify a color for each face of the cube. Each color is represented in the RGBA format for the corresponding vertex, where each component is ranged from 0 to 1 where 1 is the maximum value. For example, in 32-byte color space, the RGB color of (16, 147, 237) is translated as (0.0625, 0.57421875, 0.92578125). The A of RGBA stands for the alpha channel, which represents the transparency of the color. All colors defined in this tutorial are opaque to make it simpler, so each alpha value is set to 1.0. In this example, different variants of blue are used for the faces of the cube.</p>
<p>Specify the colors of the cube into an array dedicated to this vertex:</p>
<pre class="prettyprint">static const float colors[] =
{
0.52734375f, 0.76171875f, 0.92578125f, 1.0f
};
</pre>
-</li>
-</ol>
<h2 id="draw" name="draw">Drawing the Cube with GLView</h2>
-<p>After the model is initialized, create functionality to manipulate the scene. OpenGL ES 2.0 provided by GLView requires more preliminary work that the previous version of the library, but it gives you more power and flexibility, although this example does not take much benefit.</p>
-<p>To draw the cube with GLView and use mathematical functions for matrices:</p>
-
-<ol>
-<li>
-<p>Declare additional global variables for tasks specific to OpenGL ES 2.0. A program object is needed, an identifier for the vertices buffer, and another for the colors. Three variables are also required to ensure the connection with the shader language:</p>
+<h3>Mathematical Functions for Matrices</h3>
+<p>After the model is initialized, create functionality to manipulate the scene. OpenGL ES 2.0 provided by GLView requires more preliminary work that the previous version of the library, but gives more power and flexibility, although our example does not take much benefit.</p>
+<p>First, declare additional global variables for tasks specific to OpenGL ES 2.0. A program object is needed, an identifier for the vertices buffer and another for the colors. Three variables are also required to ensure the connection with the shader language:</p>
<ul>
<li><span style="font-family: Courier New,Courier,monospace">mvpLoc</span> is an identifier for model-view-projection matrix.</li>
<li><span style="font-family: Courier New,Courier,monospace">positionLoc</span> is an identifier for the vertex position.</li>
unsigned int colorLoc;
}
</pre>
-</li>
-<li>
-<p>Since OpenGL ES 2.0, some functions for matrix transformations have been removed. Define 3 matrices to use: projection matrix, model-view matrix, and a combination of these allows you to perform any transformations on the initial vertices matrix.</p>
-<ul>
-<li>Create the matrix multiplication function.
-<p>Define a function that is able to return the inner product of 2 matrices. This function reproduces the behavior of the <span style="font-family: Courier New,Courier,monospace">glMultMatrix()</span> function available in OpenGL ES 1.1. This function is very useful since almost every matrix transformation can be translated as multiplications of matrices.</p>
-<p>The function takes 3 parameters, 1 is for the result and the other 2 matrices are operands.</p>
+<p>Since OpenGL ES 2.0, some functions for matrix transformations have been removed. Define three matrices to use: projection matrix, model-view matrix, and a combination of these allows you to perform any transformations on the initial vertices matrix.</p>
+
+<h4>Matrix Multiplication Function (glMultMatrix)</h4>
+<p>First, define a function that is able to return the inner product of two matrices. This function reproduces the behavior of <span style="font-family: Courier New,Courier,monospace">glMultMatrix()</span> available in OpenGL ES 1.1. This function is very useful since almost every matrix transformation can be translated as multiplications of matrices.</p>
+<p>The function takes three arguments, one is for the result and the other 2 matrices are operands:</p>
<pre class="prettyprint">static void
customMutlMatrix(float matrix[16], const float matrix0[16], const float matrix1[16])
{
matrix[i] = temp[i];
}
</pre>
-</li>
-<li>Create the matrix identity function.
-<p>Implement a function equivalent to the <span style="font-family: Courier New,Courier,monospace">glLoadIdentity()</span> function that replaces the current matrix with the identity matrix.</p>
+<h4>Matrix Identity Function (glLoadIdentity)</h4>
+
+<p>Implement a function equivalent to <span style="font-family: Courier New,Courier,monospace">glLoadIdentity()</span> that replaces the current matrix with the identity matrix:</p>
<pre class="prettyprint">const float unit_matrix[] =
{
1.0f, 0.0f, 0.0f, 0.0f,
matrix[i] = unit_matrix[i];
}
</pre>
-</li>
-<li>Create the matrix projection function.
-<p>Since the <span style="font-family: Courier New,Courier,monospace">glFrustum()</span> function has been deprecated, implement a function that produces perspective projection matrices that are used to transform from eye coordinate space to clip coordinate space. This matrix projects a portion of the space (the "frustum") to your screen. Many caveats apply (such as normalized device coordinates and perspective divide), but that is the idea.</p>
+
+<h4>Matrix Projection Function (glFrustum)</h4>
+<p>Since <span style="font-family: Courier New,Courier,monospace">glFrustum</span> has been depreciated, implement a function that produces perspective projection matrices that are used to transform from eye coordinate space to clip coordinate space. This matrix projects a portion of the space (the "fustum") to your screen. Many caveats apply (normalized device coordinates, perspective divide, etc), but that is the idea:</p>
<pre class="prettyprint">static int
customFrustum(float result[16],
const float left, const float right,
return 1;
}
</pre>
-</li>
-<li>Create the matrix scaling function.
-<p>The deprecated <span style="font-family: Courier New,Courier,monospace">glScale()</span> function represents a non-uniform scaling along the x, y, and z axes. The 3 parameters indicate the desired scale factor along each of the 3 axes.</p>
+
+<h4>Matrix Scaling Function (glScale)</h4>
+<p>Depreciated <span style="font-family: Courier New,Courier,monospace">glScale()</span> function represents a non-uniform scaling along the x, y, and z axes. The three parameters indicate the desired scale factor along each of the three axes:</p>
<pre class="prettyprint">const float scale_matrix[] =
{
x, 0.0f, 0.0f, 0.0f,
0.0f, 0.0f, 0.0f, 1.0f
}
</pre>
-<p>The following example shows the implementation of the matrix scaling function:</p>
+<p>Here is the implementation of the matrix scaling function:</p>
<pre class="prettyprint">static void
customScale(float matrix[16], const float sx, const float sy, const float sz)
{
matrix[11] *= sz;
}
</pre>
-</li>
-<li>Create the matrix rotation function.
-<p>Define a function to represent a rotation by the vector (x y z). The current matrix is multiplied by a rotation matrix.</p>
+<h4>Matrix Rotation Function (glRotate)</h4>
+<p>Define a function to represent a rotation by the vector (x y z). The current matrix is multiplied by a rotation matrix:</p>
<pre class="prettyprint">static void
customRotate(float matrix[16], const float anglex, const float angley, const floatanglez)
{
customMultMatrix(matrix, matrix, temp);
}
</pre>
-</li>
-</ul>
-</li>
-<li>Create the shader:
-<ol type="a">
-<li>
-<p>Define the source for the shader using a string array. First comes out vertex shader, which is used to a medium precision for float values. Then build a uniform matrix with dimensions 4x4 intended to hold the model-view-projection matrix. Also create 2 vector attributes which have 4 components for the vertex position and the color. This varying variable <span style="font-family: Courier New,Courier,monospace">v_color</span> can be accessed from the fragment shader.</p>
-<p>In the main function of the shader, initialize the position of the current vertex, <span style="font-family: Courier New,Courier,monospace">gl_Position</span>, with the product of the vertex position and the model-view-projection matrix, to normalize the position for the target screen. The pixel color is calculated by the varying variable from the vertex shader.</p>
-<p>In the fragment shader, declare a varying variable, and set the color of the pixel with this interpolated color.</p>
+
+<h3>Create the Shader</h3>
+<p>Define the source for the shader using a string array. First comes out vertex shader, which is used to a medium precision for float values. Then build a uniform matrix with dimensions 4x4 intended to hold the model-view-projection matrix. Also create two vector attributes which have 4 components for the vertex position and the color. This varying variable <span style="font-family: Courier New,Courier,monospace">v_color</span> can be accessed from the fragment shader. In the main function of the shader, initialize the position of the current vertex, <span style="font-family: Courier New,Courier,monospace">gl_Position</span>, with the product of the vertex position and the model-view-projection matrix, in order to normalize the position for the target screen. The pixel color is calculated by the varying variable from the vertex shader.</p>
+<p>In the fragment shader, declare a varying variable, then set the color of the pixel with this interpolated color.</p>
<pre class="prettyprint">static const char vertex_shader[] =
"precision mediump float;"
"uniform mat4 u_mvpMat;"
"gl_FragColor = v_color;"
"}";
</pre>
-</li>
-<li>
-<p>Create the shaders, attach the source code that is just defined, and compile the program object:</p>
+<p>Create the shaders, attach the source code that is just defined and compile the program object:</p>
<pre class="prettyprint">static void
initShaders(void* data)
{
glShaderSource(ad->fgmt_shader, 1, &p, NULL);
glCompileShader(ad->fgmt_shader);
</pre>
-</li>
-<li>
-<p>Once the shaders are ready, instantiate the program object and link the shaders. If the linking succeeds, you can destroy the shaders afterwards (using the <span style="font-family: Courier New,Courier,monospace">glDeleteShader()</span> function). Since they are inside the program object, it is pointless to keep them in memory.</p>
+<p>Once the shaders are ready, instantiate the program object and link the shaders. If the linking succeeds, you can destroy the shaders afterwards (using <span style="font-family: Courier New,Courier,monospace">glDeleteShader</span>). Since they are inside the program object, so it is pointless to keep them in memory.</p>
<pre class="prettyprint"> ad->program = glCreateProgram();
glAttachShader(ad->program, ad->vtx_shader);
glLinkProgram(ad->program);
</pre>
-</li>
-<li>
-<p>For shader process, create identifiers for the attribute variables used in the shader program. Create an identifier for the model-view-projection matrix, another one for the current vertex position, and a last one for the vertex color.</p>
+
+<p>For shader process, create identifiers for the attribute variables used in the shader program. First create an identifier for the model-view-projection matrix, another one for the current vertex position, and a last one for the vertex color.</p>
<pre class="prettyprint"> ad->mvpLoc = glGetUniformLocation(ad->program, "u_mvpMat");
ad->positionLoc = glGetAttribLocation(ad->program, "a_position");
ad->colorLoc = glGetAttribLocation(ad->program, "a_color");
</pre>
-</li>
-<li>
-<p>Generate the buffers for the vertex positions and colors:</p>
+
+<p>Finally, generate the buffers for the vertex positions and colors.</p>
<pre class="prettyprint">
glGenBuffers(1, &ad->vertexID);
glBindBuffer(GL_ARRAY_BUFFER, ad->vertexID);
glBufferData(GL_ARRAY_BUFFER, sizeof(colors), colors, GL_STATIC_DRAW);
}
</pre>
-</li>
-<li>
-<p>Allocate memory for the matrix and load a unit matrix into it. Define the value that is used to build the perspective projection matrix with the <span style="font-family: Courier New,Courier,monospace">customFrustum()</span> function. Multiply this resulting matrix with a resizing matrix, so the model is correctly adjusted to the screen.</p>
+
+<p>Allocate memory for the matrix and load a unit matrix into it. Then define the value that is used in order to build the perspective projection matrix. The <span style="font-family: Courier New,Courier,monospace">customFrustum()</span> function is used for it. Multiply this resulting matrix with a resizing matrix, so the model is correctly adjusted to the screen.</p>
<pre class="prettyprint">
float aspect;
customLoadIdentity(view);
customFrustum(view, -1.0, 1.0, -1.0 * aspect, 1.0 * aspect, -1.0, 1.0);
}
</pre>
-</li>
-</ol>
-</li>
-</ol>
<h2 id="render" name="render">Rendering the Cube</h2>
-<p>To render the cube:</p>
-<ol>
-<li>
-<p>Set the viewport at 0,0 corresponding to the bottom left edge of the window, and the height and width of the GL surface. Clear the depth and the color buffers to the values that were selected during initialization. Call the <span style="font-family: Courier New,Courier,monospace">glUseProgram()</span> function to trigger the shader program.</p>
+<p>We set the viewport at 0,0 corresponding to the bottom left edge of the window, and the height and width of the GL surface. Clear the depth and the color buffers to the values that were selected during initialization. Then call the <span style="font-family: Courier New,Courier,monospace">glUseProgram()</span> function in order to trigger the shader program.</p>
<pre class="prettyprint">glViewport(0, 0, w, h);
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
glUseProgram(ad->program);
</pre>
-</li>
-<li>
-<p>Bind the position and color identifiers to the buffers defined above:</p>
+
+<p>Also bind the position and color identifiers to the buffers defined above.</p>
<pre class="prettyprint">glEnableVertexAttribArray(ad->positionLoc);
glBindBuffer(GL_ARRAY_BUFFER, ad->vertexID);
glVertexAttribPointer(ad->positionLoc, 3, GL_FLOAT, GL_FALSE, 3 * sizeof(float), 0);
glBindBuffer(GL_ARRAY_BUFFER, ad->colorID);
glVertexAttribPointer(ad->colorLoc, 4, GL_FLOAT, GL_FALSE, 4 * sizeof(float), 0);
</pre>
-</li>
-<li>
-<p>Initialize and calculate the transformation matrix of the model-view matrix by calling the <span style="font-family: Courier New,Courier,monospace">customRotate()</span> function. This makes the cube view rotate a little for a better perspective. Once the model-view matrix is ready to display, multiply the projection matrix with the model-view matrix.</p>
+
+<p>After this, initialize and calculate the transformation matrix of the model-view matrix by calling the <span style="font-family: Courier New,Courier,monospace">customRotate()</span> function. This makes the cube view rotate a little for a better perspective. Once the model-view matrix is ready to display, multiply the projection matrix with the model-view matrix.</p>
<pre class="prettyprint">customLoadIdentity(model);
customRotate(ad->model, 45.0f, 45.0f, 0.0f);
customMutlMatrix(ad->mvp, ad->view, ad->model);
</pre>
-</li>
-<li>
-<p>Load the model-view-projection matrix into the shader and call the <span style="font-family: Courier New,Courier,monospace">glDrawArrays()</span> function to draw the model:</p>
+
+<p>Then load the model-view-projection matrix into the shader and call <span style="font-family: Courier New,Courier,monospace">glDrawArrays()</span> to draw the model.</p>
<pre class="prettyprint">glUniformMatrix4fv(ad->mvpLoc, 1, GL_FALSE, mvp);
glDrawArrays(GL_TRIANGLES, 0, 36);
glFlush();
</pre>
-</li>
-</ol>
+
+<p>You now are the proud owner of a nice cube!</p>
<p class="figure">Figure: Static cube</p>
<p align="center"><img alt="Static cube" src="../../images/static_cube.png" /></p>
<h2 id="animate" name="animate">Animating the Cube</h2>
-<p>To animate the cube:</p>
-<ol>
-<li>
-<p>Use the <span style="font-family: Courier New,Courier,monospace">Ecore_Animator</span> to create an animation:</p>
+<p><span style="font-family: Courier New,Courier,monospace">Ecore_Animator</span> is used to create an animation.</p>
<pre class="prettyprint">static Eina_Bool
animate_cb(void *data)
{
ani = ecore_animator_add(animate_cb, ad->glview);
}
</pre>
-</li>
-<li>
-<p>Define the global variables which are used as parameters of the rendering process. Add parameters to the application data object that are used to control the scaling and the rotation of the cube. To make the cube rotate on 1 axis, take z, and allow the user to interact with the mouse to make the cube rotate on the other axes x and y. To figure out whether the user is holding the mouse down, add a Boolean variable to have this information. Operations such as shader initialization or program compilation are not required at each tick of the animation loop. For better performance, isolate such task from the repetitive rendering loop. For such purpose, add a Boolean variable which tells whether the initialization is already done.</p>
+
+<p>Next define the global variables which are used as parameters of the rendering process. Add parameters to the application data object that are used to control the scaling and the rotation of the cube. To make the cube rotate on one axis, take z, and allow the user to interact with the mouse to make the cube rotate on the two other axes x and y. In order to figure out whether the user is holding the mouse down, add a Boolean variable to have this information. Operations such as shader initialization or program compilation are not required at each tick of the animation loop. For better performance, isolate such task from the repetitive rendering loop. For such purpose, add a Boolean variable which tells whether the initialization is already done.</p>
<pre class="prettyprint">typedef struct appdata
{
float xangle;
Eina_Bool initialized : 1;
} appdata_s;
</pre>
-</li>
-<li><p>Modify the rendering loop for animation.</p>
-<ul>
-<li>
-<p>Lighten the recurrent rendering process by adding an initialization step:</p>
+
+<p>Here are the modifications that must be done to the rendering loop for animation.</p>
+<p>First, lighten the recurrent rendering process by adding an initialization step:</p>
<pre class="prettyprint">if (ad->initialized)
{
initShaders(ad);
ad->initialized = EINA_TRUE;
}
</pre>
-</li>
-<li>
-<p>Before drawing the vertices, the rotation angle for the model-view matrix must be incremented for every tick. This makes the cube rotate automatically.</p>
+
+<p>Before drawing the vertices, the rotation angle for the model-view matrix must be incremented for every tick.</p>
<pre class="prettyprint">customLoadIdentity(ad->model);
customRotate(ad->model, ad->xangle, ad->yangle, ad->zangle++);
customMutlMatrix(ad->mvp, ad->view, ad->model);
</pre>
-</li>
-</ul>
-</li>
-<li>
-<p>Use the mouse to drag the cube around. To do so, add callbacks for mouse events. The first callback defines whether the user is holding the mouse down while moving the cursor around.</p>
+
+<p>This makes the cube rotate automatically. The next thing is to use the mouse to drag the cube around. To do so, add callbacks for mouse events. The first callback defines whether the user is holding the mouse down while moving the cursor around:</p>
<pre class="prettyprint">static void
mouse_down_cb(void *data, Evas *e , Evas_Object *obj , void *event_info)
{
}
}
</pre>
-</li>
-<li>
+
<p>Define the mouse events callbacks when creating the image canvas:</p>
<pre class="prettyprint">evas_object_event_callback_add(ad->glview, EVAS_CALLBACK_MOUSE_DOWN, mouse_down_cb, ad);
evas_object_event_callback_add(ad->glview, EVAS_CALLBACK_MOUSE_UP, mouse_up_cb, ad);
evas_object_event_callback_add(ad->glview, EVAS_CALLBACK_MOUSE_MOVE, mouse_move_cb, ad);
</pre>
-</li>
-</ol>
<h2 id="component" name="component">Implementing UI Component Interaction</h2>
-<p>To implement UI component interaction:</p>
-<ol>
-<li>
-<p>Use the UI component to control some aspects of the rendering, such as some sliders to control the shape of the cube. Declare 3 sliders to play with the scaling coordinates of the cube.</p>
+<p>Consider using UI component to control some aspects of the rendering. For example, use some sliders to control the shape of the cube. Declare 3 sliders to play with the scaling coordinates of the cube.</p>
<pre class="prettyprint">typedef struct appdata
{
Evas_Object *slx;
Evas_Object *slz;
}
</pre>
-</li>
-<li>
-<p>Build and show the sliders when rendering the GUI. The sliders accept values in a range from 0.0 to 1.5. They control the scaling of each axis of the cube.</p>
-<pre class="prettyprint">// Slider for X axis scale
+
+<p>When rendering the GUI, build and show the sliders. Those accept values in a range from 0.0 to 1.5 and control the scaling of each axis of the cube.</p>
+<pre class="prettyprint">// Slider for X-axis scale
ad->slx = elm_slider_add(ad->inner_box);
evas_object_size_hint_align_set(ad->slx, EVAS_HINT_FILL, 0);
elm_slider_horizontal_set(ad->slx, EINA_TRUE);
elm_box_pack_end(ad->inner_box, ad->slz);
evas_object_show(ad->slz);
</pre>
-</li>
-<li>
-<p>Use the actual sliders's values and pass them to the scaling function in the rendering loop:</p>
+
+<p>Then use the actual sliders's values and pass them to the scaling function in the rendering loop:</p>
<pre class="prettyprint">double scalex = elm_slider_value_get(ad->slx);
double scaley = elm_slider_value_get(ad->sly);
double scalez = elm_slider_value_get(ad->slz);
customScale(ad->model, scalex, scaley, scalez);
customMutlMatrix(ad->mvp, ad->view, ad->model);
</pre>
-</li>
-<li>
-<p>Use a colorpicker to change the background by adding a colorselector component:</p>
-<pre class="prettyprint">typedef struct appdata
-{
- Evas_Object *cs;
-}
-</pre>
-</li>
-<li>
-<p>Build the UI component with a default palette and add it to the GUI:</p>
-<pre class="prettyprint">ad->cs = elm_colorselector_add(ad->inner_box);
-elm_colorselector_mode_set(ad->cs, ELM_COLORSELECTOR_BOTH);
-elm_colorselector_palette_name_set(ad->cs, "default");
-elm_box_pack_end(ad->inner_box, ad->cs);
-evas_object_show(ad->cs);
-</pre>
-</li>
-<li>
-<p>When rendering the cube, retrieve the currently selected color to define the color buffer. The colors from the colorselector vary from 0 to 255, which needs to be converted to the color format of OpenGL ES.</p>
-<pre class="prettyprint">int r, g, b, a;
-elm_colorselector_color_get(ad->cs, &r, &g, &b, &a);
-glClearColor(r/255.0, g/255.0, b/255.0, a/255.0);
-glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
-</pre>
-</li>
-</ol>
<h2 id="effect" name="effect">Implementing Effects</h2>
-<p>To implement effects:</p>
-<ol>
-<li>
-<p>Create a button that resets the scene by putting the background color to black and makes the cube bounce back to its original scale. Add the button to the application data object.</p>
+<p>Create a button that resets the scene by putting the background color to black and makes the cube bounce back to its original scale. First add the button to the application data object:</p>
<pre class="prettyprint">typedef struct appdata
{
Evas_Object *button;
}
</pre>
-</li>
-<li>
-<p>Add the button to the GUI:</p>
+
+<p>Then add the button to the GUI:</p>
<pre class="prettyprint">elm_object_text_set(ad->button, "Reset");
elm_box_pack_start(ad->reset_vbox, ad->button);
evas_object_smart_callback_add(ad->button, "clicked", btn_reset_cb, ad);
elm_box_pack_end(ad->inner_box, ad->button);
evas_object_show(ad->button);
</pre>
-</li>
-<li>
-<p>Declare a callback that resets the variables that have influence on the drawing of the cube. In addition, animate the sliders when they get back to their original position using the <span style="font-family: Courier New,Courier,monospace">Ecore_Animator</span>.</p>
+
+<p>Declare a callback that resets the variables that have influence on the drawing of the cube. In addition, animate the sliders when they get back to their original position using <span style="font-family: Courier New,Courier,monospace">Ecore_Animator</span>.</p>
<pre class="prettyprint">
typedef struct appdata
{
ecore_animator_timeline_add(1, animate_reset_cb, ad);
}
</pre>
-</li>
-</ol>
<h2 id="source" name="source">Viewing the Entire Cube Source</h2>
Evas_Object *slx;
Evas_Object *sly;
Evas_Object *slz;
- Evas_Object *cs;
Evas_Object *button;
unsigned int program;
draw_gl(Evas_Object *obj)
{
int w, h;
- int r, g, b, a;
appdata_s *ad = evas_object_data_get(obj, "ad");
double scalex = elm_slider_value_get(ad->slx);
double scalez = elm_slider_value_get(ad->slz);
elm_glview_size_get(obj, &w, &h);
- elm_colorselector_color_get(ad->cs, &r, &g, &b, &a);
glClearDepthf(1.0f);
- glClearColor(r / 255.0, g / 255.0, b / 255.0, a / 255.0);
+ glClearColor(0.0, 0.0, 0.0, 1.0);
glEnable(GL_CULL_FACE);
glViewport(0, 0, w, h);
animate_cb(void *data)
{
elm_glview_changed_set(data);
-
return EINA_TRUE;
}
ecore_animator_timeline_add(1, animate_reset_cb, ad);
}
-static void
-win_resize_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
-{
- Evas_Coord w, h;
- appdata_s *ad = data;
-
- evas_object_geometry_get(obj, NULL, NULL, &w, &h);
-
- if (w > h)
- {
- elm_box_horizontal_set(ad->main_box, EINA_TRUE);
- }
- else
- {
- elm_box_horizontal_set(ad->main_box, EINA_FALSE);
- }
-}
-
-static void
+static void
win_back_cb(void *data, Evas_Object *obj, void *event_info)
{
appdata_s *ad = data;
- // Let the window go to the hidden state
+ // Let window go to hidden state
elm_win_lower(ad->win);
}
elm_win_wm_rotation_available_rotations_set(ad->win, (const int *) (&rots), 4);
}
- evas_object_event_callback_add(ad->win, EVAS_CALLBACK_RESIZE, win_resize_cb, ad);
evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);
elm_glview_mode_set(ad->glview, ELM_GLVIEW_DEPTH);
// The resize policy tells GLView what to do with the surface when it
- // resizes. ELM_GLVIEW_RESIZE_POLICY_RECREATE tells it to
+ // resizes. ELM_GLVIEW_RESIZE_POLICY_RECREATE will tell it to
// destroy the current surface and recreate it to the new size
elm_glview_resize_policy_set(ad->glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
- // The render policy sets how GLView must render GL code.
- // ELM_GLVIEW_RENDER_POLICY_ON_DEMAND has the GL callback
+ // The render policy sets how GLView should render GL code.
+ // ELM_GLVIEW_RENDER_POLICY_ON_DEMAND will have the GL callback
// called only when the object is visible.
- // ELM_GLVIEW_RENDER_POLICY_ALWAYS causes the callback to be
- // called even if the object were hidden
+ // ELM_GLVIEW_RENDER_POLICY_ALWAYS would cause the callback to be
+ // called even if the object were hidden.
elm_glview_render_policy_set(ad->glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
// The initialize callback function gets registered here
elm_box_pack_end(ad->main_box, ad->glview);
evas_object_show(ad->glview);
- // This adds an animator so that the app regularly
- // triggers updates of the GLView using elm_glview_changed_set()
+ // This adds an animator so that the app will regularly
+ // trigger updates of the GLView using elm_glview_changed_set()
//
- // NOTE: If you delete GL, this animator keeps running trying to access
+ // NOTE: If you delete GL, this animator will keep running trying to access
// GL so this animator needs to be deleted with ecore_animator_del()
ani = ecore_animator_add(animate_cb, ad->glview);
evas_object_data_set(ad->glview, "ani", ani);
create_toolbox(appdata_s *ad)
{
ad->inner_box = elm_box_add(ad->main_box);
+ evas_object_size_hint_align_set(ad->inner_box, EVAS_HINT_FILL, 0);
elm_box_horizontal_set(ad->inner_box, EINA_FALSE);
elm_box_homogeneous_set(ad->inner_box, EINA_FALSE);
elm_box_pack_end(ad->main_box, ad->inner_box);
evas_object_show(ad->inner_box);
- // Color selector for the background
- ad->cs = elm_colorselector_add(ad->inner_box);
- elm_colorselector_mode_set(ad->cs, ELM_COLORSELECTOR_BOTH);
- elm_colorselector_palette_name_set(ad->cs, "default");
- elm_box_pack_end(ad->inner_box, ad->cs);
- evas_object_show(ad->cs);
-
// Slider for X axis scale
ad->slx = elm_slider_add(ad->inner_box);
evas_object_size_hint_align_set(ad->slx, EVAS_HINT_FILL, 0);
{
dlog_print(DLOG_ERROR, PACKAGE, "The application failed to start, and returned %d", ret);
}
- return ret;
-}
-</pre>
-
-<h2 id="multithread" name="multithread">Using OpenGL ES in Multi-threaded Applications</h2>
-
-<p>To use OpenGL ES in multi-threaded applications, set up the rendering view and initialize the application:</p>
-
-<ol>
-<li>Manage the Elementary GLView:
-<ol type="a">
-
-<li>Create a single GLView component covering the whole window using the <span style="font-family: Courier New,Courier,monospace;">app_create()</span> function:
-<pre class="prettyprint">
-typedef struct
-{
- Evas_Object *glview;
-
- Eina_Lock lck;
-
- // RT to main loop
- Ecore_Pipe *pipe;
-
- // Main loop to RT: direct pipe file descriptors
- int rt_rpipefd, rt_wpipefd;
-
- // General OpenGL ES data: program to draw a texture fullscreen
- GLuint vtx_shader[1], fgmt_shader[1], program[1], vbo[2];
- Evas_GL_Context *main_ctx;
-
- // Render thread data
- struct
- {
- Ecore_Thread *thread;
-
- Evas_GL_Context *ctx;
- Evas_GL_Surface *sfc;
-
- GLfloat c1, c2, c3, c4;
-
- Eina_Bool cancelled;
- Eina_Bool finished;
- Eina_Bool ready;
- } th;
-
- // Pool of Target_Buffer: empty, ready (locked access)
- Eina_Inlist *buffers_empty;
- Eina_Inlist *buffers_ready;
- Target_Buffer *last_buffer;
-} App_Data;
-
-static bool
-app_create(void *data)
-{
- Evas_Object *win, *glview;
- App_Data *ad = data;
-
- // Request OpenGL hardware acceleration
-
- elm_config_accel_preference_set("gl");
- elm_config_accel_preference_override_set(EINA_TRUE);
- // Create a basic window
- win = elm_win_util_standard_add("win", "Multi-thread OpenGL ES demo");
- evas_object_show(win);
- // On window deletion, exit the render thread
- evas_object_smart_callback_add(win, "delete,request", delete_cb, &ad);
- // Create a basic OpenGL ES surface with GLView
- glview = elm_glview_version_add(win, EVAS_GL_GLES_2_X);
- evas_object_size_hint_min_set(glview, 240, 240);
- elm_win_resize_object_add(win, glview);
- ELEMENTARY_GLVIEW_GLOBAL_USE(glview);
- evas_object_size_hint_weight_set(glview, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
- evas_object_size_hint_align_set(glview, EVAS_HINT_FILL, EVAS_HINT_FILL);
- evas_object_show(glview);
-
- elm_glview_mode_set(glview, ELM_GLVIEW_ALPHA);
- elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
- elm_glview_resize_policy_set(glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
- elm_glview_init_func_set(glview, init);
- elm_glview_render_func_set(glview, render);
-
- evas_object_data_set(glview, "ad", &ad);
- ad->glview = glview;
-}
-</pre>
-</li>
-
-<li>Initialize the gl status. The main thread render function acts as a compositor thread.
-<pre class="prettyprint">
-static void
-init(Evas_Object *obj)
-{
- App_Data *ad = evas_object_data_get(obj, "ad");
- const char *p;
- static const char vertex_texture[] =
- "attribute vec4 vPosition;\n"
- "attribute vec2 vTexCoord;\n"
- "varying vec2 texcoord;\n"
- "void main()\n"
- "{\n"
- " gl_Position = vPosition;\n"
- " texcoord = vTexCoord;\n"
- "}\n";
- static const char fragment_texture[] =
- "#ifdef GL_ES\n"
- "precision mediump float;\n"
- "#endif\n"
- "uniform sampler2D tex;\n"
- "varying vec2 texcoord;\n"
- "void main()\n"
- "{\n"
- " gl_FragColor = texture2D(tex, texcoord);\n"
- "}\n";
- const float rectangle_fullscreen_vertices[] =
- {
- 1.0, 1.0, 0.0,
- -1.0, -1.0, 0.0,
- 1.0, -1.0, 0.0,
- 1.0, 1.0, 0.0,
- -1.0, 1.0, 0.0,
- -1.0, -1.0, 0.0
- };
- const float texture_vertices[] =
- {
- 1.0, 1.0,
- 0.0, 0.0,
- 1.0, 0.0,
- 1.0, 1.0,
- 0.0, 1.0,
- 0.0, 0.0,
- };
- // Init main data
- ad->main_ctx = evas_gl_current_context_get(elm_glview_evas_gl_get(obj));
- // Create vertex data
- glGenBuffers(2, ad->vbo);
- glBindBuffer(GL_ARRAY_BUFFER, ad->vbo[0]);
- glBufferData(GL_ARRAY_BUFFER, 3 * 6 * 4, rectangle_fullscreen_vertices, GL_STATIC_DRAW);
- glBindBuffer(GL_ARRAY_BUFFER, ad->vbo[1]);
- glBufferData(GL_ARRAY_BUFFER, 2 * 6 * 4, texture_vertices, GL_STATIC_DRAW);
- // Texture draw
- p = vertex_texture;
- ad->vtx_shader[0] = glCreateShader(GL_VERTEX_SHADER);
- glShaderSource(ad->vtx_shader[0], 1, &p, NULL);
- glCompileShader(ad->vtx_shader[0]);
- p = fragment_texture;
- ad->fgmt_shader[0] = glCreateShader(GL_FRAGMENT_SHADER);
- glShaderSource(ad->fgmt_shader[0], 1, &p, NULL);
- glCompileShader(ad->fgmt_shader[0]);
- ad->program[0] = glCreateProgram();
- glAttachShader(ad->program[0], ad->vtx_shader[0]);
- glAttachShader(ad->program[0], ad->fgmt_shader[0]);
-</pre>
-</li>
-</ol>
-</li>
-
-<li>Create Ecore threads.
-<p>To easily create threads with EFL, use the <span style="font-family: Courier New,Courier,monospace;">ecore_thread()</span> infrastructure, which provides a high level abstraction over system threads, along with callbacks in the main loop to signal that a thread has finished running or has been canceled.</p>
-<p>When the main OpenGL ES context is properly set up, spawn the render thread and start setting up its OpenGL ES context:</p>
-<pre class="prettyprint">
- glBindAttribLocation(ad->program[0], 0, "vPosition");
- glBindAttribLocation(ad->program[0], 1, "vTexCoord");
- glLinkProgram(ad->program[0]);
-
- ad->th.thread = ecore_thread_run(thread_run, thread_end, thread_cancel, ad);
-}
-</pre>
-
-<p>The <span style="font-family: Courier New,Courier,monospace;">thread_run()</span>, <span style="font-family: Courier New,Courier,monospace;">thread_end()</span>, and <span style="font-family: Courier New,Courier,monospace;">thread_cancel()</span> callback functions are called when the thread runs, returns successfully, or is canceled prematurely. In this application, the thread always returns and must never be forcefully canceled because it never returns from the <span style="font-family: Courier New,Courier,monospace;">thread_run()</span> function. To run again, trigger a cancel callback if the thread is calling the <span style="font-family: Courier New,Courier,monospace;">ecore_thread_reschedule()</span> function.</p>
-</li>
-</ol>
-
- <h3>Managing Inter-thread Communication Channels</h3>
-
-<p>To establish safe communication channels between threads:</p>
-<ol>
-<li>Since most of EFL is not thread-safe, certain operations cannot be executed from another thread and you must use the main loop instead.
-<p>Establish a communication channel from the render thread to the main loop.</p>
-<ol type="a">
-<li>Create an <span style="font-family: Courier New,Courier,monospace;">ecore_pipe</span> channel.
-<p>EFL provides a simple tool to send messages to the main thread using pipes. Ecore Pipe is the abstraction layer around pipe objects, and is the easiest way to send a message from any thread back to the main thread.</p>
-<pre class="prettyprint">
-// In the app_create() function, create pipe for messaging
-ad.pipe = ecore_pipe_add(pipe_handler, &ad);
-eina_lock_new(&ad.lck);
-</pre>
-
-<p><span style="font-family: Courier New,Courier,monospace;">eina_lock_new()</span> creates a new <span style="font-family: Courier New,Courier,monospace;">Eina_Lock</span>. It protects access to shared variables.</p>
-</li>
-<li>Send messages with <span style="font-family: Courier New,Courier,monospace;">ecore_pipe</span>.
-<p>The following code passes <span style="font-family: Courier New,Courier,monospace;">Message_Data</span> structures, which are copied by <span style="font-family: Courier New,Courier,monospace;">ecore_pipe</span> and sent over to the <span style="font-family: Courier New,Courier,monospace;">pipe_handler</span> callback. <span style="font-family: Courier New,Courier,monospace;">Message_Data</span> structures have to be defined by the application.</p>
-<pre class="prettyprint">
-// Render thread to main loop
-static void
-message_send(App_Data *ad, Message_Type type, ...)
-{
- Message_Data msg = {0};
- msg.type = type;
- if (type == MSG_NEWFRAME)
- {
- va_list args;
- va_start(args, type);
- msg.newframe.target = va_arg(args, Target_Buffer *);
- va_end(args);
- }
- // The pipe copies the passed data
- ecore_pipe_write(ad->pipe, &msg, sizeof(msg));
-}
-</pre>
-</li>
-
-<li>Receive messages through the <span style="font-family: Courier New,Courier,monospace;">ecore_pipe</span>.
-<p>The <span style="font-family: Courier New,Courier,monospace;">ecore_pipe</span> has a callback running in the main thread, and receives data sent over by any thread.</p>
-<pre class="prettyprint">
-static void
-pipe_handler(void *data, void *buf, unsigned int len EINA_UNUSED)
-{
- Message_Data *msg = buf;
- App_Data *ad = data;
- switch (msg->type)
- {
- case MSG_HELLO:
- // Render thread has started
- printf("The render thread is saying hello.\n");
- break;
- case MSG_GOODBYE:
- // It is now safe to request exit from the main loop
- printf("Thread has cleanly terminated.\n");
- elm_exit();
- break;
- }
-}
-</pre>
-<p>You do not need to use the <span style="font-family: Courier New,Courier,monospace;">free()</span> function to free data since the data belongs to the <span style="font-family: Courier New,Courier,monospace;">ecore_pipe</span>.</p>
-</li>
-</ol>
-</li>
-
-<li><p>Sending messages to the render thread from the main thread covers input event passing handling. The following example passes input event messages and regular ticks to the render thread.</p>
-
-<p>Establish a communication channel from the main thread to the render thread:</p>
-
-<ol type="a">
-<li>Create a pipe.
-<p>The easiest way to send a simple message in EFL in Tizen is to rely on a POSIX pipe file handle.</p>
-<pre class="prettyprint">
-// Create a pipe for messaging
-int fds[2];
-pipe(fds);
-ad.rt_rpipefd = fds[0];
-ad.rt_wpipefd = fds[1];
-</pre>
-</li>
-
-<li>Send messages to a thread. Write data to the pipe created above, from the main loop.
-<pre class="prettyprint">
-// Main loop to render thread
-static void
-event_send(App_Data *ad, Event_Type type, ...)
-{
- // Event Data is defined by application
- Event_Data *ed = calloc(1, sizeof(Event_Data));
- ed->type = type;
- if (type == EVENT_MOUSE)
- {
- va_list args;
- va_start(args, type);
- ed->mouse.down = (va_arg(args, int) != 0);
- va_end(args);
- }
- // Manually send this over the pipe fd (only the pointer)
- write(ad->rt_wpipefd, &ed, sizeof(ed));
-}
-</pre>
-</li>
-
-<li>Receive messages in a thread.
-<p>In the render thread, use the event handling code.</p>
-<pre class="prettyprint">
-while (!ecore_thread_check(ad->th.thread))
-{
- Event_Data *ev = NULL;
- int r;
-
- // Render
-
- r = read(ad->rt_rpipefd, &ev, sizeof(ev));
- if ((r == sizeof(ev)) && ev)
- {
- // Handle message
- }
-}
-</pre></li>
-
-<li>Use a simple pipe file descriptor to use the <span style="font-family: Courier New,Courier,monospace;">poll()</span> or <span style="font-family: Courier New,Courier,monospace;">select()</span> function to wait for events for a pre-determined period of time, or to wait for events on more than a single file descriptor. In this example, the main loop is responsible for the render thread life-cycle.
-<pre class="prettyprint">
-thread_run(void *data, Ecore_Thread *th EINA_UNUSED)
-{
- evas_gl_make_current(evgl, ad->th.sfc, ad->th.ctx);
- while (!ecore_thread_check(ad->th.thread))
- {
- // Prepare new frame
- glViewport(0, 0, BUFFER_WIDTH, BUFFER_HEIGHT);
- glBindFramebuffer(GL_FRAMEBUFFER, target->fbo);
-
- if (((r = read(ad->rt_rpipefd, &ev, sizeof(ev))) == sizeof(ev)) && ev)
- {
- if (ev->type == EVENT_QUIT)
- {
- free(ev);
- break;
- }
- }
- }
-}
-</pre>
-
-<p>The <span style="font-family: Courier New,Courier,monospace;">ecore_thread_check()</span> function returns true when the thread is canceled using the <span style="font-family: Courier New,Courier,monospace;">ecore_thread_cancel()</span> function.</p>
-</li>
-</ol>
-</li>
-
-<li>Handle input events:
-<p>With the above setup environment, pass input events from the main thread to any thread.</p>
-<ol type="a">
-<li>Add the following code to the <span style="font-family: Courier New,Courier,monospace;">app_create()</span> function to catch mouse up or down events on the GLView object:
-<pre class="prettyprint">
-evas_object_event_callback_add(glview, EVAS_CALLBACK_MOUSE_DOWN, mouse_down_cb, &ad);
-evas_object_event_callback_add(glview, EVAS_CALLBACK_MOUSE_UP, mouse_up_cb, &ad);
-</pre>
-</li>
-
-<li>
-<p>Add a handle to the callbacks.</p>
-<p>The mouse down callback sends a mouse down event to render thread.</p>
-<pre class="prettyprint">
-static void
-mouse_down_cb(void *data, Evas *e EINA_UNUSED,
- Evas_Object *obj EINA_UNUSED, void *event_info)
-{
- Evas_Event_Mouse_Down *event = event_info;
- App_Data *ad = data;
- if (event->button != 1)
- return;
-
- event_send(ad, EVENT_MOUSE, EINA_TRUE);
-}
-</pre>
-</li>
-<li>
-<p>The mouse up callback sends a mouse up event to render thread:</p>
-<pre class="prettyprint">
-static void
-mouse_up_cb(void *data, Evas *e EINA_UNUSED,
- Evas_Object *obj EINA_UNUSED, void *event_info)
-{
- Evas_Event_Mouse_Up *event = event_info;
- App_Data *ad = data;
-
- if (event->button != 1)
- return;
-
- event_send(ad, EVENT_MOUSE, EINA_FALSE);
-}
-</pre>
-
-<p>The render thread receives these events calling the <span style="font-family: Courier New,Courier,monospace;">read()</span> function:</p>
-<pre class="prettyprint">
-thread_run(void *data, Ecore_Thread *th EINA_UNUSED)
-{
- // Prepare new frame
- glViewport(0, 0, BUFFER_WIDTH, BUFFER_HEIGHT);
- glBindFramebuffer(GL_FRAMEBUFFER, target->fbo);
- evas_gl_make_current(evgl, ad->th.sfc, ad->th.ctx);
- while (!ecore_thread_check(ad->th.thread))
- {
- // Check for events from the main thread (one event at a time)
- if (((r = read(ad->rt_rpipefd, &ev, sizeof(ev))) == sizeof(ev)) && ev)
- {
- if (ev->type == EVENT_MOUSE)
- {
- if (ev->mouse.down)
- {
- // Do something
- }
- }
- }
- }
-}
-</pre>
-</li>
-</ol>
-</li>
-</ol>
-
-<h3>Managing Multi-thread OpenGL ES</h3>
-
-<p>To deliver the result of OpenGL ES rendering to the main thread for compositing, render the thread:</p>
-<ol>
-<li>
-<p>The easiest way to share data between threads in OpenGL ES is to use shared contexts. However, all objects ID's, such as texture IDs and FBOs, are shared between contexts. In addition, it is not always allowed to bind the same object from different contexts at the same time.</p>
-
-<p>The example shows that the render thread uses EvasGL directly to create a dummy PBuffer surface and its render context. The PBuffer surface is necessary for the <span style="font-family: Courier New,Courier,monospace;">evas_gl_make_current()</span> function:</p>
-<pre class="prettyprint">
-Evas_GL *evgl = elm_glview_evas_gl_get(ad->glview);
-
-cfg = evas_gl_config_new();
-cfg->color_format = EVAS_GL_NO_FBO;
-cfg->depth_bits = EVAS_GL_DEPTH_NONE;
-cfg->stencil_bits = EVAS_GL_STENCIL_NONE;
-cfg->options_bits = EVAS_GL_OPTIONS_NONE;
-ad->th.sfc = evas_gl_pbuffer_surface_create(evgl, cfg, 1, 1, NULL);
-evas_gl_config_free(cfg);
-ad->th.ctx = evas_gl_context_create(evgl, ad->main_ctx);
-evas_gl_make_current(evgl, ad->th.sfc, ad->th.ctx);
-</pre>
-</li>
-
-<li>
-<p>Deliver images from one context to another using a shared FBO. The following example uses a pool of at least 2 buffers: texture and FBO. This works as double or triple buffering. At all times, one buffer is used for drawing (rendering in the render thread) and the other for compositing (reading in the main thread).</p>
-<pre class="prettyprint">
-// Create targets (needs at least 2)
-eina_lock_take(&ad->lck);
-for (i = 0; i < BUFFER_COUNT; i++)
-{
- target = target_create(ad);
- if (!target) break;
- target->id = i;
- ad->buffers_empty = eina_inlist_append(ad->buffers_empty,
- EINA_INLIST_GET(target));
-}
-eina_lock_release(&ad->lck);
-message_send(ad, MSG_READY);
-</pre>
-</li>
-<li>
-<p>Use the <span style="font-family: Courier New,Courier,monospace;">target_create()</span> function to create a texture and an attached FBO, and package them together:</p>
-<pre class="prettyprint">
-typedef struct
-{
- EINA_INLIST;
- GLuint fbo, tex;
- EvasGLSync sync;
- int id;
-}
-Target_Buffer;
-
-static Target_Buffer *
-target_create(App_Data *ad EINA_UNUSED)
-{
- Target_Buffer *target = calloc(1, sizeof(Target_Buffer));
- GLenum err;
- if (!target)
- return NULL;
- glGenFramebuffers(1, &target->fbo);
- glBindFramebuffer(GL_FRAMEBUFFER, target->fbo);
- glGenTextures(1, &target->tex);
- glBindTexture(GL_TEXTURE_2D, target->tex);
- glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
- glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
- glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
- glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
- glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, BUFFER_WIDTH, BUFFER_HEIGHT, 0, GL_RGBA, GL_UNSIGNED_BYTE, NULL);
- glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, target->tex, 0);
- err = glCheckFramebufferStatus(GL_FRAMEBUFFER);
- if (err != GL_FRAMEBUFFER_COMPLETE)
- {
- printf("FBO could not be set: 0x%x\n", (int) err);
- glDeleteTextures(1, &target->tex);
- glDeleteFramebuffers(1, &target->fbo);
- free(target);
-
- return NULL;
- }
- return target;
-}
-</pre>
-</li>
-
-<li>
-<p>Use the shared buffers in the render thread as target surfaces:</p>
-<pre class="prettyprint">
-thread_run(void *data, Ecore_Thread *th EINA_UNUSED)
-{
- evas_gl_make_current(evgl, ad->th.sfc, ad->th.ctx);
- while (!ecore_thread_check(ad->th.thread))
- {
- // Get an empty buffer
- eina_lock_take(&ad->lck);
- if (!ad->buffers_empty)
- {
- // Wait
- eina_lock_release(&ad->lck);
- usleep(1000);
- continue;
- }
- target = EINA_INLIST_CONTAINER_GET(ad->buffers_empty, Target_Buffer);
- ad->buffers_empty = eina_inlist_remove(ad->buffers_empty, ad->buffers_empty);
- eina_lock_release(&ad->lck);
- // Prepare new frame
- glViewport(0, 0, BUFFER_WIDTH, BUFFER_HEIGHT);
- glBindFramebuffer(GL_FRAMEBUFFER, target->fbo);
- // Draw a new frame
- thread_draw(ad);
- // Release FBO; some drivers complain if it is bound by a different thread
- glBindFramebuffer(GL_FRAMEBUFFER, 0);
- }
-}
-</pre>
-</li>
-<li>
-<p>To render in a thread, use the <span style="font-family: Courier New,Courier,monospace;">thread_draw()</span> function. The following example draws with a color.</p>
-<pre class="prettyprint">
-static void
-thread_draw(App_Data *ad, Evas_GL_API *gl)
-{
- // Draw function
- glClearColor(ad->th.c1, ad->th.c2, ad->th.c3, ad->th.c4);
- glClear(GL_COLOR_BUFFER_BIT);
-}
-</pre>
-</li>
-
-<li>Render the FBO to the screen. The following example uses the <span style="font-family: Courier New,Courier,monospace;">ecore_pipe</span>.
-<pre class="prettyprint">
-// Signal the main thread that a new frame is now available
-message_send(ad, MSG_NEWFRAME, target);
-</pre>
-</li>
-<li>
-<p>The pipe handler receives this message in <span style="font-family: Courier New,Courier,monospace;">pipe_handler</span>. The following example adds the target buffer to a queue.</p>
-<pre class="prettyprint">
-case MSG_NEWFRAME:
- // Queue a new frame description
- printf("Got a new frame with buffer %d\n", msg->newframe.target->id);
- eina_lock_take(&ad->lck);
- ad->buffers_ready = eina_inlist_append(ad->buffers_ready, EINA_INLIST_GET(msg->newframe.target));
- eina_lock_release(&ad->lck);
- elm_glview_changed_set(ad->glview);
- break;
-</pre>
-</li>
-<li>
-<p>The GLView <span style="font-family: Courier New,Courier,monospace;">render()</span> function is called from the main loop, and draws the texture to the screen:</p>
-<pre class="prettyprint">
-// Draw the texture on the screen
-evas_object_geometry_get(ad->glview, 0, 0, &w, &h);
-draw_rectangle(ad, w, h, target->tex);
-</pre>
-
-<p>Draw the texture:</p>
-<pre class="prettyprint">
-void
-draw_rectangle(App_Data *ad, int w, int h, int tex)
-{
- GLuint u;
- glViewport(0, 0, w, h);
- glClearColor(0.2, 0.2, 0.2, 1.0);
- glClear(GL_COLOR_BUFFER_BIT);
- glEnable(GL_BLEND);
- glBlendFunc(GL_ONE, GL_ONE_MINUS_SRC_ALPHA);
- glUseProgram(ad->program[0]);
- glBindBuffer(GL_ARRAY_BUFFER, ad->vbo[0]);
- glVertexAttribPointer(0, 3, GL_FLOAT, GL_FALSE, 0, 0);
- glEnableVertexAttribArray(0);
- glBindBuffer(GL_ARRAY_BUFFER, ad->vbo[1]);
- glVertexAttribPointer(1, 2, GL_FLOAT, GL_FALSE, 0, 0);
- glEnableVertexAttribArray(1);
- u = glGetUniformLocation(ad->program[0], "tex");
- glUniform1i(u, 0);
- glActiveTexture(GL_TEXTURE0);
- glBindTexture(GL_TEXTURE_2D, tex);
- glDrawArrays(GL_TRIANGLES, 0, 6);
-}
-</pre>
-</li>
-
-<li>
-<p>The above code works in some cases but depending on the GPU and driver, there can be synchronization issues between the 2 threads, as one is drawing and the other is reading from the same object. Remember that most GL commands are asynchronous.</p>
-
-<p>You can synchronize data between threads:</p>
-<ul>
-<li>Using fence sync objects
-<p>Use the <span style="font-family: Courier New,Courier,monospace;">fence_sync</span> extension:</p>
-<pre class="prettyprint">
-// Create fence sync
-if (evasglCreateSync)
- target->sync = evasglCreateSync(evgl, EVAS_GL_SYNC_FENCE, NULL);
-else
-{
- target->sync = EVAS_GL_NO_SYNC;
- glFinish();
-}
-</pre>
-<p>The <span style="font-family: Courier New,Courier,monospace;">evasglCreateSync</span> function pointer is <span style="font-family: Courier New,Courier,monospace;">NULL</span> if the extension is not supported. In that case, call the <span style="font-family: Courier New,Courier,monospace;">glFinish()</span> function, because the lock is not used.</p>
-</li>
-
-<li>Waiting on a fence
-<p>The main thread now waits on this sync before drawing the texture on the screen. This yields a better performance than the <span style="font-family: Courier New,Courier,monospace;">glFinish()</span> function:</p>
-<pre class="prettyprint">
-// Wait for the render thread to complete rendering, if fence_sync is available
-if (target->sync)
-{
- evasglClientWaitSync(evgl, target->sync,
- EVAS_GL_SYNC_FLUSH_COMMANDS_BIT,
- EVAS_GL_FOREVER);
- evasglDestroySync(evgl, target->sync);
- target->sync = EVAS_GL_NO_SYNC;
-}
-
-// Draw the texture on the screen
-</pre>
-
-
-<p>Instead of passing <span style="font-family: Courier New,Courier,monospace;">EVAS_GL_FOREVER</span>, it is also possible to pass a timeout, so that the wait function never dead locks.</p>
-</li>
-</ul>
-</li>
-</ol>
-
-<h3>Using EvasGL Images</h3>
-
-<p>You can deliver the result of rendering from one OpenGL ES thread to another to use EvasGLImage objects. This requires an underlying EGL image extension (or equivalent if the backend is not EGL), and might not be fully supported on all platforms.</p>
-<ol>
-<li>
-<p>To check for the presence of this extension, check the function pointers in Evas_GL_API:</p>
-<pre class="prettyprint">
-if (evasglCreateImageForContext)
-{
- // Create an image
-}
-</pre>
-</li>
-<li>
-<p>Create the image with a texture ID or a renderbuffer ID. Since EFL abstracts the underlying display system, such as X or Wayland, a portable application limits itself to the most portable options, such as pure OpenGL ES objects:</p>
-<pre class="prettyprint">
-if (evasglCreateImageForContext)
-{
- // Create an image
- evasglCreateImageForContext(evgl, ctx, EVAS_GL_TEXTURE_2D,
- (void*)(intptr_t)texid, NULL);
+ return ret;
}
</pre>
-<p>Tizen also provides specific buffers created with TBM that can be passed to this function. Unfortunately the image extension is more device-dependent, and may not even work in the Tizen emulator.</p>
-</li>
-</ol>
-
<h2 id="ext" name="ext">Using OpenGL ES Extensions</h2>
<p>Image and sync support are the most commonly used EvasGL extensions. Both can be used for multi-thread rendering, but EvasGL images can also be used to share images between contexts.</p>
-<ul>
-<li>To use the image extension:
+<h3>EvasGLImage</h3>
-<p>There are 2 versions of the <span style="font-family: Courier New,Courier,monospace;">evasglCreateImage()</span> function, out of which extra <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Context</span> is taken as a parameter. It is recommended to call the <span style="font-family: Courier New,Courier,monospace;">evasglCreateImageForContext()</span> function if you are dealing with multiple contexts, otherwise calling the <span style="font-family: Courier New,Courier,monospace;">evasglCreateImage()</span> function is sufficient.</p>
+<p>There are 2 versions of the <span style="font-family: Courier New,Courier,monospace;">evasglCreateImage</span> function, out of which extra <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Context</span> is taken as an argument. It is recommended to call <span style="font-family: Courier New,Courier,monospace;">evasglCreateImageForContext</span> if you are dealing with multiple contexts, otherwise calling the <span style="font-family: Courier New,Courier,monospace;">evasglCreateImage</span> function is sufficient.</p>
+
+<p>The code below is just an example.</p>
<ol>
<li>Check for support.
- <p>Before using this extension, check whether it is supported.</p>
+ <p>Before using this extension, check whether it is supported:</p>
<pre class="prettyprint">
if (gl->evasglCreateImageForContext && gl->evasglDestroyImage)
</pre>
</li>
<li>Create an image.
- <p>Create a render buffer and bind it to an EvasGL image.</p>
+ <p>Create a render buffer and bind it to an EvasGL image:</p>
<pre class="prettyprint">
const int width = 64, height = 64;
<p>The EvasGL image is now created and available for use from another context.</p>
</li>
<li>Use an image.
- <p>To draw something in the texture and render that texture to the screen. The following example shows how to skip the draw function.</p>
+ <p>To draw something in the texture and render that texture to the screen. To skip the draw function:</p>
<pre class="prettyprint">
gl->glBindFramebuffer(GL_FRAMEBUFFER_EXT, fbo);
gl->glGenTextures(1, &tex);
gl->glBindTexture(GL_TEXTURE_2D, tex);
gl->glEGLImageTargetTexture2DOES(GL_TEXTURE_2D, image);
-// Draw the contents of the texture on the screen
+//And do the actual draw operation (draw the contents of the texture on screen):
static const GLint verts[12] = { -5, -6, -10, 5, -6, -10, -5, 4, 10, 5, 4, 10 };
static const GLint tex_coords[8] = { 0, 0, 1, 0, 0, 1, 1, 1 };
<p>The image content can be shared between different contexts.</p>
</li>
<li>Destroy an image.
- <p>After releasing all the associated resources, such as FBO and textures, release the image object itself.</p>
+ <p>After releasing all the associated resources, such as FBO and textures, release the image object itself:</p>
<pre class="prettyprint">
gl->evasglDestroyImage(image);</pre>
</li>
</ol>
-</li>
-<li>To use the sync extension:
+
+<h3>Sync</h3>
<p>Another commonly used extension is the fence sync extension along with the reusable sync and wait sync. This allows creating a semaphore-style object that is released as soon as all the previous render operations have been completed.</p>
-<p>This guide does not explain the details of these extensions, as they must behave in a similar way to their EGL implementations.</p>
+<p>This guide does not explain the details of these extensions, as they should behave in a similar way to their EGL implementations.</p>
<p>As usual with extensions, check the support:</p>
<pre class="prettyprint">
if (gl->evasglCreateSync)
- // fence_sync must be supported
+ // fence_sync must be supported
</pre>
-</li>
-</ul>
<h2 id="direct" name="direct">Using Direct Rendering</h2>
<p>To enhance rendering performance, the Direct Rendering option is supported.</p>
-<ul>
-<li>
-<p>To use direct rendering in GLView:</p>
-<p>In GLView, the <span style="font-family: Courier New,Courier,monospace;">ELM_GLVIEW_DIRECT</span> option is one of GLView mode's enums and the option can be enabled using the <span style="font-family: Courier New,Courier,monospace;">elm_glview_mode_set()</span> function.</p>
+<h3>GLView</h3>
+
<pre class="prettyprint">
// Tizen 2.3
// elm_config_accel_preference_set("opengl");
elm_glview_mode_set(glview, ELM_GLVIEW_DEPTH_24 | ELM_GLVIEW_STENCIL_8 | ELM_GLVIEW_MULTISAMPLE_HIGH);
</pre>
+<p>In GLView, the <span style="font-family: Courier New,Courier,monospace;">ELM_GLVIEW_DIRECT</span> option is one of GLView mode's enums and the option can be enabled using the <span style="font-family: Courier New,Courier,monospace;">elm_glview_mode_set()</span> function.</p>
+
<p>To use the Direct Rendering mode since Tizen 2.3.1, 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>
-</li>
-<li>
-<p>To use direct rendering in EvasGL:</p>
-<p>In EvasGL, the <span style="font-family: Courier New,Courier,monospace;">EVAS_GL_OPTIONS_DIRECT</span> is one of EvasGL's config options and the option can be enabled by setting the <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Config</span> option.</p>
+<h3>EvasGL</h3>
+
<pre class="prettyprint">
// Tizen 2.3
// elm_config_accel_preference_set("opengl");
cfg->multisample_bits = EVAS_GL_MULTISAMPLE_HIGH;
</pre>
-<p>To use the Direct Rendering mode since Tizen 2.3.1, set the same option values (depth, stencil, and MSAA) to a rendering engine and an <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Config</span> 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. If the <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Config</span> object option values are bigger or higher than the rendering engine's, the Direct Rendering mode is disabled.</p>
+<p>In EvasGL, the <span style="font-family: Courier New,Courier,monospace;">EVAS_GL_OPTIONS_DIRECT</span> is one of EvasGL's config options and the option can be enabled by setting the <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Config</span> option. To use the Direct Rendering mode since Tizen 2.3.1, set the same option values (depth, stencil, and MSAA) to a rendering engine and an <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Config</span> 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. If the <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Config</span> object option values are bigger or higher than the rendering engine's, the Direct Rendering mode is disabled.</p>
<table class="note">
<tbody>
<th class="note">Note</th>
</tr>
<tr>
- <td class="note">If direct rendering is enabled, EvasGL rendersdirectly to the back buffer of the window. Otherwise, EvasGL renders to the off screen buffer, then composited to the back buffer of the window.
+ <td class="note">If direct rendering is enabled, EvasGL will render directly to the back buffer of the window. Otherwise, EvasGL will render to the off screen buffer, then composited to the back buffer of the window.
-<p>Although direct rendering is enabled, EvasGL not always renders directly to the back buffer. The following conditions disable direct rendering and force a fallback to indirect rendering in a frame buffer:</p>
+<p>Although direct rendering is enabled, EvasGL will not always render directly to the back buffer. Here are some conditions that will disable direct rendering and force a fallback to indirect rendering in a frame buffer.</p>
-<ul>
+<ol>
<li>If the object's color is not 255,255,255,255.</li>
<li>If the object has an Evas map.</li>
<li>If the object size is different from the viewport, (<span style="font-family: Courier New,Courier,monospace;">RESIZE_POLICY_SCALE</span>).</li>
<li>If the window is rotated and <span style="font-family: Courier New,Courier,monospace;">CLIENT_SIDE_ROTATION</span> is not set.</li>
<li>If the GLView policy is set to <span style="font-family: Courier New,Courier,monospace;">ALWAYS</span> render or the EvasGL does not use pixel getter callback.</li>
-</ul></td>
+</ol></td>
</tr>
</tbody>
</table>
<td class="note">In the render callback function, call only GL functions.
<p>In case the GL functions are called outside the render callback function, you must call the <span style="font-family: Courier New,Courier,monospace;">evas_gl_make_current()</span> function before the GL function calls. However, this results in a performance degradation due to context switching, and only works if the target surface is not an <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Surface</span> with Direct Rendering enabled.</p>
-<p>If the target buffer is an <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Surface</span> with Direct Rendering enabled, all GL functions must be called from the render callback function only. All other operations can break the rendering order and the unexpected rendering occurs.</p></td>
+<p>If the target buffer is an <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Surface</span> with Direct Rendering enabled, all GL functions must be called from the render callback function only. All other operations can break the rendering order and the unexpected rendering will occur.</p></td>
</tr>
</tbody>
</table>
- </li>
- </ul>
<h2 id="client" name="client">Using Client-side Rotation</h2>
-<p>The Client Side Rotation is a special value that indicates to EFL that the application handles the view rotation when the device is rotated. This is needed only when the application requests Direct Rendering.</p>
+
+<p>The Client Side Rotation is a special value that indicates to EFL that the application will handle the view rotation when the device is rotated. This is needed only when the application requests Direct Rendering.</p>
<p>If the window is rotated and the Direct Rendering flag is set, Client Side Rotation can be used to avoid falling back to a frame buffer.</p>
-<ul>
-<li>To use GLView rotation:
+<h3>GLView</h3>
-<p>In GLView, the <span style="font-family: Courier New,Courier,monospace;">ELM_GLVIEW_CLIENT_SIDE_ROTATION</span> option is one of GLView mode's enums and the option can be enabled by using the <span style="font-family: Courier New,Courier,monospace;">elm_glview_mode_set()</span> function. This option is needed only when Direct Rendering is enabled.</p>
<pre class="prettyprint">
Evas_Object *gl;
gl = elm_glview_add(win);
elm_glview_mode_set(gl, ELM_GLVIEW_DEPTH | ELM_GLVIEW_DIRECT | ELM_GLVIEW_CLIENT_SIDE_ROTATION);</pre>
-</li>
-<li>To use EvasGL rotation:
+<p>In GLView, the <span style="font-family: Courier New,Courier,monospace;">ELM_GLVIEW_CLIENT_SIDE_ROTATION</span> option is one of GLView mode's enums and the option can be enabled by using the <span style="font-family: Courier New,Courier,monospace;">elm_glview_mode_set()</span> function. This option is needed only when Direct Rendering is enabled.</p>
+
+<h3>EvasGL</h3>
-<p>In EvasGL, the <span style="font-family: Courier New,Courier,monospace;">EVAS_GL_OPTIONS_CLIENT_SIDE_ROTATION</span> is one of EvasGL's config options and this option can be enabled by setting the <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Config</span> option.</p>
<pre class="prettyprint">
Evas_GL_Config *cfg;
cfg = evas_gl_config_new();
cfg->options_bits = EVAS_GL_OPTIONS_DIRECT | EVAS_GL_OPTIONS_CLIENT_SIDE_ROTATION;</pre>
+<p>In EvasGL, the <span style="font-family: Courier New,Courier,monospace;">EVAS_GL_OPTIONS_CLIENT_SIDE_ROTATION</span> is one of EvasGL's config options and this option can be enabled by setting the <span style="font-family: Courier New,Courier,monospace;">Evas_GL_Config</span> option.</p>
+
<p>Get the current rotation value:</p>
+
<pre class="prettyprint">
static void _draw_gl(Evas_Object *obj)
{
}
}</pre>
-<p>To get the current rotation of the view, in degrees, call the <span style="font-family: Courier New,Courier,monospace;">evas_gl_rotation_get()</span> function to properly handle the current rotation of the view. It always returns 0 unless the option <span style="font-family: Courier New,Courier,monospace;">EVAS_GL_OPTIONS_CLIENT_SIDE_ROTATION</span> has been set. Indeed, in case of Direct Rendering to the back buffer, the client application is responsible for properly rotating its view. This can generally be done by applying a rotation to a view matrix.</p>
-</li>
-</ul>
+<p>To get the current rotation of the view, in degrees, call the <span style="font-family: Courier New,Courier,monospace;">evas_gl_rotation_get()</span> in order to properly handle the current rotation of the view. It will always return 0 unless the option <span style="font-family: Courier New,Courier,monospace;">EVAS_GL_OPTIONS_CLIENT_SIDE_ROTATION</span> has been set. Indeed, in case of Direct Rendering to the back buffer, the client application is responsible for properly rotating its view. This can generally be done by applying a rotation to a view matrix.</p>
<script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>
projects / sdk / online-doc.git / commitdiff