Porting a native EGL+OpenGL-ES2 application to EFL

Contents of this section:

• Foreword
• Why all the trouble?
• Evas GL initialization with GLView
• Direct rendering with Evas GL
• OpenGL-ES 1.1 support in EFL
• Other uses of EGL and their Evas GL equivalents

Foreword

While Evas and Ecore provide all the required functions to build a whole application based on EFL and using OpenGL, it is recommended to use Elm_GLView instead. Elementary Elm_GLView will create a drawable GL surface for the application, and set up all the required callbacks so that the complexity of Evas GL is hidden.

Convenience functions for OpenGL with EFL

The file Elementary_GL_Helpers.h provides some convenience functions that ease the use of OpenGL within an Elementary application.

Why all the trouble?

Evas GL is an abstraction layer on top of EGL, GLX or WGL that should provide the necessary features for most applications, in a platform-independent way. Since the goal of Evas GL is to abstract the underlying platform, only a subset of the features can be used by applications.

On top of this, an Evas GL surface can be stacked within a GUI layout just like any other widget, and will support transparency, direct rendering, and various other features. For these reasons, it is not possible to directly expose lower level APIs like OpenGL or EGL and interact with Evas as the same time.

The following sections should provide developers guides on how to use OpenGL-ES in an EFL application.

Evas GL initialization with GLView

When using Elm_GLView, EFL will take care of the tedious creation of all the surfaces and contexts. Also, EFL hides the underlying display system so there is no way to get a direct handle to

Here is a demo using EFL with OpenGL:

// gcc `pkg-config --cflags --libs elementary` glview.c -o glview
#include <Elementary_GL_Helpers.h>

static void _draw_gl(Evas_Object *obj)
{
   ELEMENTARY_GLVIEW_USE(obj);

   glClearColor(0.2, 0.2, 0.2, 1.0);
   glClear(GL_COLOR_BUFFER_BIT);
}

static void _resize_gl(Evas_Object *obj)
{
   ELEMENTARY_GLVIEW_USE(obj);
   int w, h;

   elm_glview_size_get(obj, &w, &h);
   glViewport(0, 0, w, h);
}

// This is the GL initialization function
Evas_Object* glview_create(Evas_Object *win)
{
   Evas_Object *glview;

   glview = elm_glview_add(win);
   elm_win_resize_object_add(win, glview);
   elm_glview_mode_set(glview, ELM_GLVIEW_ALPHA | ELM_GLVIEW_DEPTH | ELM_GLVIEW_STENCIL);
   elm_glview_resize_policy_set(glview, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
   elm_glview_render_policy_set(glview, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
   //elm_glview_init_func_set(glview, _init_gl);
   //elm_glview_del_func_set(glview, _del_gl);
   elm_glview_render_func_set(glview, _draw_gl);
   elm_glview_resize_func_set(glview, _resize_gl);
   evas_object_size_hint_min_set(glview, 250, 250);
   evas_object_show(glview);

   return glview;
}

EAPI int elm_main(int argc EINA_UNUSED, char **argv EINA_UNUSED)
{
   Evas_Object *win;

   // Set the acceleration preference to 3d
   elm_config_accel_preference_set("3d");

   // Create a window
   win = elm_win_util_standard_add("glview", "GLView");
   evas_object_show(win);

   // Setup our GLView
   glview_create(win);

   elm_run();
   elm_shutdown();
   return 0;
}
ELM_MAIN()

Direct rendering with Evas GL

Evas GL can be used to render directly to the back buffer of the Evas window. It is important to note that this is an optimization path and this will present a few limitations. Normally, Evas GL will create an FBO and use it as target surface for all the GL draw operations, and finally blend this FBO's contents to the Evas canvas.

Evas GL will automatically fallback to indirect rendering unless the conditions are right. The flag EVAS_GL_OPTIONS_DIRECT must be set on the target surface in order to enable direct rendering. When using the Elementary GLView widget, the flag ELM_GLVIEW_DIRECT should be set.

Some limitations of direct rendering include the following:

• If glClear() is called after glClearColor(0,0,0,0), then clear will be skipped for the color buffer. Otherwise this would erase the back buffer in evas, instead of preparing a transparent surface for GL rendering. Opaque colors will be cleared as expected (eg. (0,0,0,1)).
• Evas GL will fallback to indirect rendering if an Evas Map is applied, or if other conditions force Evas to fallback.
• The user application is responsible for handling screen rotation when using direct rendering, which is why applications should set the flag EVAS_GL_OPTIONS_CLIENT_SIDE_ROTATION on the GL surface (or ELM_GLVIEW_CLIENT_SIDE_ROTATION for Elm_GLView). Please also see evas_gl_rotation_get.

Note:

Direct rendering is an option that can drastically improve the performance of OpenGL applications, but it can exhibit some side effects.

OpenGL-ES 1.1 support in EFL

Since Tizen 2.3, Evas GL supports the OpenGL-ES 1.1 set of rendering APIs on top of the normal OpenGL-ES 2.0 APIs, if the drivers supports it.

With Elm_GLView, it is easy to create a 1.1 capable surface:

Evas_Object *glview;
glview = elm_glview_version_add(win, EVAS_GL_GLES_1_X);

OpenGL-ES 3.0 support in EFL

Since Tizen 2.4, Evas GL supports the OpenGL-ES 3.0 set of rendering APIs on top of the normal OpenGL-ES 2.0 APIs, if the drivers supports it.

With Elm_GLView, it is easy to create a 3.0 capable surface:

Evas_Object *glview;
glview = elm_glview_version_add(win, EVAS_GL_GLES_3_X);

As usual, the GL API is available using elm_glview_gl_api_get, which can be abstracted with ELEMENTARY_GLVIEW_USE.

When using Evas GL directly, developers must be careful to use evas_gl_context_api_get with the current context in order to get the proper API (1.1 or 2.0 or 3.0). Indeed, evas_gl_api_get will always return a GLES 2.0 API, and the 1.1 and 2.0 APIs are not compatible. Also, the application will then be responsible for calling evas_gl_make_current.

Remarks:

Always use Elm_GLView unless there is a very good reason not to.

Other uses of EGL and their Evas GL equivalents

Of course, Evas GL is not limited to creating fullscreen OpenGL target surfaces, and some developers might want to exploit some of the more advanced features of Evas GL.

• Evas GL vs. EGL
• Query surfaces for their properties
• PBuffer surfaces for multithread rendering

These features usually require to use Rendering GL on Evas directly rather than just Elm_GLView.

Evas GL vs. EGL

As explained above, Evas GL is an abstraction layer on top of EGL, but not limited to EGL. While trying to look similar to EGL, Evas GL should also support GLX and other backends (WGL, ...).

As a consequence, only a subset of the EGL features are supported by Evas GL.

Manual work is required in order to transform all calls to EGL into Evas GL calls, but the final code should be much lighter when using EFL. Here is a simple table comparison between EGL and Evas GL calls:

The extensions above may or may not be available depending on the OpenGL driver and the backend used.

Some EGL definitions have also been imported and transformed for Evas GL. In particular, the EVAS_GL error codes returned by evas_gl_error_get don't start from 0x3000 like EGL but from 0. Also, attribute lists can be terminated by 0 instead of EGL_NONE.

Query surfaces for their properties

When using EGL, it is common to query a surface for its properties. Evas GL supports only a subset of the surface properties:

• EVAS_GL_WIDTH,
• EVAS_GL_HEIGHT,
• EVAS_GL_TEXTURE_FORMAT,
• EVAS_GL_TEXTURE_TARGET

Refer to evas_gl_surface_query for more information.

PBuffer surfaces for multithread rendering

If an application wants to render offscreen using OpenGL, it can use FBOs. But if the application wants to render in a separate render thread, a surface must be created for that thread in order to call evas_gl_make_current.

In the EGL world, it is common to create a PBuffer surface with eglCreatePBufferSurface() and set its size to 1x1. With Rendering GL on Evas this is possible using evas_gl_pbuffer_surface_create.

Here is how an application could setup a render context in a separate thread:

// In the init function:
Evas_GL_Surface *sfc;
Evas_GL_Config *cfg;
Evas_GL_Context *ctx;
Evas_GL *evasgl;

evasgl = elm_glview_evas_gl_get(glview);

cfg = evas_gl_config_new();
cfg->color_format = EVAS_GL_RGBA_8888;
cfg->depth_bits = EVAS_GL_DEPTH_NONE;
cfg->stencil_bits = EVAS_GL_STENCIL_NONE;
cfg->options_bits = EVAS_GL_OPTIONS_NONE;

sfc = evas_gl_pbuffer_surface_create(evasgl, cfg, WIDTH, HEIGHT, NULL);
ctx = evas_gl_context_create(elm_glview_evas_gl_get(glview), NULL);
evas_gl_config_free(cfg);
// ...

// In the render function:
evas_gl_make_current(evasgl, sfc, ctx);

// Render to a FBO, bind it to a native image and pass it to the main thread
// using an EvasGLImage.

Multithread OpenGL rendering with Evas GL is the topic of another guide.