src/lib/elm_glview.h

   1 /**
   2  * @defgroup GLView GLView
   3  *
   4  * A GLView widget allows for simple GL rendering in elementary environment.
   5  * GLView hides all the complicated evas_gl details so that the user only
   6  * has to deal with registering a few callback functions for rendering
   7  * to a surface using OpenGL APIs.
   8  *
   9  * Below is an illustrative example of how to use GLView and and OpenGL
  10  * to render in elementary environment.
  11  * @code
  12 // Simple GLView example
  13 #include <Elementary.h>
  14 #include <Evas_GL.h>
  15 #include <stdio.h>
  16
  17 typedef struct _GLData GLData;
  18
  19 // GL related data here..
  20 struct _GLData
  21 {
  22    Evas_GL_API *glapi;
  23    GLuint       program;
  24    GLuint       vtx_shader;
  25    GLuint       fgmt_shader;
  26    GLuint       vbo;
  27    int          initialized : 1;
  28 };
  29
  30
  31 static float red = 1.0;
  32
  33 //--------------------------------//
  34 // a helper function to load shaders from a shader source
  35 static GLuint
  36 load_shader( GLData *gld, GLenum type, const char *shader_src )
  37 {
  38    Evas_GL_API *gl = gld->glapi;
  39    GLuint shader;
  40    GLint compiled;
  41
  42    // Create the shader object
  43    shader = gl->glCreateShader(type);
  44    if (shader==0)
  45       return 0;
  46
  47    // Load/Compile shader source
  48    gl->glShaderSource(shader, 1, &shader_src, NULL);
  49    gl->glCompileShader(shader);
  50    gl->glGetShaderiv(shader, GL_COMPILE_STATUS, &compiled);
  51
  52    if (!compiled)
  53      {
  54         GLint info_len = 0;
  55         gl->glGetShaderiv(shader, GL_INFO_LOG_LENGTH, &info_len);
  56         if (info_len > 1)
  57           {
  58              char* info_log = malloc(sizeof(char) * info_len);
  59
  60              gl->glGetShaderInfoLog(shader, info_len, NULL, info_log);
  61              printf("Error compiling shader:\n%s\n======\n%s\n======\n", info_log, shader_src );
  62              free(info_log);
  63           }
  64         gl->glDeleteShader(shader);
  65         return 0;
  66      }
  67
  68    return shader;
  69 }
  70
  71 // Initialize the shader and program object
  72 static int
  73 init_shaders(GLData *gld)
  74 {
  75    Evas_GL_API *gl = gld->glapi;
  76    GLbyte vShaderStr[] =
  77       "attribute vec4 vPosition;    \n"
  78       "void main()                  \n"
  79       "{                            \n"
  80       "   gl_Position = vPosition;  \n"
  81       "}                            \n";
  82
  83    GLbyte fShaderStr[] =
  84       "#ifdef GL_ES                                 \n"
  85       "precision mediump float;                     \n"
  86       "#endif                                       \n"
  87       "void main()                                  \n"
  88       "{                                            \n"
  89       "  gl_FragColor = vec4 ( 1.0, 0.0, 0.0, 1.0 );\n"
  90       "}                                            \n";
  91
  92    GLint linked;
  93
  94    // Load the vertex/fragment shaders
  95    gld->vtx_shader  = load_shader(gld, GL_VERTEX_SHADER, (const char*)vShaderStr);
  96    gld->fgmt_shader = load_shader(gld, GL_FRAGMENT_SHADER, (const char*)fShaderStr);
  97
  98    // Create the program object
  99    gld->program = gl->glCreateProgram( );
 100    if (gld->program==0)
 101       return 0;
 102
 103    gl->glAttachShader(gld->program, gld->vtx_shader);
 104    gl->glAttachShader(gld->program, gld->fgmt_shader);
 105
 106    gl->glBindAttribLocation(gld->program, 0, "vPosition");
 107    gl->glLinkProgram(gld->program);
 108    gl->glGetProgramiv(gld->program, GL_LINK_STATUS, &linked);
 109
 110    if (!linked)
 111      {
 112         GLint info_len = 0;
 113         gl->glGetProgramiv(gld->program, GL_INFO_LOG_LENGTH, &info_len);
 114         if (info_len > 1)
 115           {
 116              char* info_log = malloc(sizeof(char) * info_len);
 117
 118              gl->glGetProgramInfoLog(gld->program, info_len, NULL, info_log);
 119              printf("Error linking program:\n%s\n", info_log);
 120              free(info_log);
 121           }
 122         gl->glDeleteProgram(gld->program);
 123         return 0;
 124      }
 125    return 1;
 126 }
 127
 128
 129
 130 // Callbacks
 131 // intialize callback that gets called once for intialization
 132 static void
 133 _init_gl(Evas_Object *obj)
 134 {
 135    GLData *gld = evas_object_data_get(obj, "gld");
 136    Evas_GL_API *gl = gld->glapi;
 137    GLfloat vVertices[] = {  0.0f,  0.5f, 0.0f,
 138                            -0.5f, -0.5f, 0.0f,
 139                             0.5f, -0.5f, 0.0f };
 140
 141    if (!init_shaders(gld))
 142      {
 143         printf("Error Initializing Shaders\n");
 144         return;
 145      }
 146
 147    gl->glGenBuffers(1, &gld->vbo);
 148    gl->glBindBuffer(GL_ARRAY_BUFFER, gld->vbo);
 149    gl->glBufferData(GL_ARRAY_BUFFER, 3 * 3 * 4, vVertices, GL_STATIC_DRAW);
 150 }
 151
 152 // delete callback gets called when glview is deleted
 153 static void
 154 _del_gl(Evas_Object *obj)
 155 {
 156    GLData *gld = evas_object_data_get(obj, "gld");
 157    if (!gld)
 158      {
 159         printf("Unable to get GLData. \n");
 160         return;
 161      }
 162    Evas_GL_API *gl = gld->glapi;
 163
 164    gl->glDeleteShader(gld->vtx_shader);
 165    gl->glDeleteShader(gld->fgmt_shader);
 166    gl->glDeleteProgram(gld->program);
 167    gl->glDeleteBuffers(1, &gld->vbo);
 168
 169    evas_object_data_del((Evas_Object*)obj, "..gld");
 170    free(gld);
 171 }
 172
 173 // resize callback gets called every time object is resized
 174 static void
 175 _resize_gl(Evas_Object *obj)
 176 {
 177    int w, h;
 178    GLData *gld = evas_object_data_get(obj, "gld");
 179    Evas_GL_API *gl = gld->glapi;
 180
 181    elm_glview_size_get(obj, &w, &h);
 182
 183    // GL Viewport stuff. you can avoid doing this if viewport is all the
 184    // same as last frame if you want
 185    gl->glViewport(0, 0, w, h);
 186 }
 187
 188
 189 // draw callback is where all the main GL rendering happens
 190 static void
 191 _draw_gl(Evas_Object *obj)
 192 {
 193    Evas_GL_API *gl = elm_glview_gl_api_get(obj);
 194    GLData *gld = evas_object_data_get(obj, "gld");
 195    if (!gld) return;
 196    int w, h;
 197
 198    elm_glview_size_get(obj, &w, &h);
 199
 200    gl->glViewport(0, 0, w, h);
 201    gl->glClearColor(red,0.8,0.3,1);
 202    gl->glClear(GL_COLOR_BUFFER_BIT);
 203
 204    // Draw a Triangle
 205    gl->glEnable(GL_BLEND);
 206
 207    gl->glUseProgram(gld->program);
 208
 209    gl->glBindBuffer(GL_ARRAY_BUFFER, gld->vbo);
 210    gl->glVertexAttribPointer(0, 3, GL_FLOAT, GL_FALSE,
 211                              0, 0);
 212    gl->glEnableVertexAttribArray(0);
 213
 214    gl->glDrawArrays(GL_TRIANGLES, 0, 3);
 215
 216    // Optional - Flush the GL pipeline
 217    gl->glFinish();
 218
 219    red -= 0.1;
 220    if (red < 0.0) red = 1.0;
 221 }
 222
 223 // just need to notify that glview has changed so it can render
 224 static Eina_Bool
 225 _anim(void *data)
 226 {
 227    elm_glview_changed_set(data);
 228    return EINA_TRUE;
 229 }
 230
 231 static void
 232 _on_done(void *data, Evas_Object *obj, void *event_info)
 233 {
 234    evas_object_del((Evas_Object*)data);
 235    elm_exit();
 236 }
 237
 238 static void
 239 _del(void *data, Evas *evas, Evas_Object *obj, void *event_info)
 240 {
 241    Ecore_Animator *ani = evas_object_data_get(obj, "ani");
 242    ecore_animator_del(ani);
 243 }
 244
 245
 246 EAPI int
 247 elm_main(int argc, char **argv)
 248 {
 249    Evas_Object *win, *bg, *bx, *bt, *gl;
 250    Ecore_Animator *ani;
 251    GLData *gld = NULL;
 252
 253    if (!(gld = calloc(1, sizeof(GLData)))) return 1;
 254
 255    // set the engine to opengl_x11
 256    // if commented out, ELM will choose one
 257    elm_engine_set("opengl_x11");
 258
 259    win = elm_win_add(NULL, "glview simple", ELM_WIN_BASIC);
 260    elm_win_title_set(win, "GLView Simple");
 261    elm_win_autodel_set(win, EINA_TRUE);
 262
 263    bg = elm_bg_add(win);
 264    elm_win_resize_object_add(win, bg);
 265    evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
 266    evas_object_show(bg);
 267
 268    bx = elm_box_add(win);
 269    evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
 270    elm_win_resize_object_add(win, bx);
 271    evas_object_show(bx);
 272
 273    //-//-//-// THIS IS WHERE GL INIT STUFF HAPPENS (ALA EGL)
 274    //-//
 275    // create a new glview object
 276    gl = elm_glview_add(win);
 277    gld->glapi = elm_glview_gl_api_get(gl);
 278    evas_object_size_hint_align_set(gl, EVAS_HINT_FILL, EVAS_HINT_FILL);
 279    evas_object_size_hint_weight_set(gl, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
 280    // mode is simply for supporting alpha, depth buffering, and stencil
 281    // buffering.
 282    elm_glview_mode_set(gl, ELM_GLVIEW_ALPHA | ELM_GLVIEW_DEPTH);
 283    // resize policy tells glview what to do with the surface when it
 284    // resizes.  ELM_GLVIEW_RESIZE_POLICY_RECREATE will tell it to
 285    // destroy the current surface and recreate it to the new size
 286    elm_glview_resize_policy_set(gl, ELM_GLVIEW_RESIZE_POLICY_RECREATE);
 287    // render policy tells glview how it would like glview to render
 288    // gl code. ELM_GLVIEW_RENDER_POLICY_ON_DEMAND will have the gl
 289    // calls called in the pixel_get callback, which only gets called
 290    // if the object is visible, hence ON_DEMAND.  ALWAYS mode renders
 291    // it despite the visibility of the object.
 292    elm_glview_render_policy_set(gl, ELM_GLVIEW_RENDER_POLICY_ON_DEMAND);
 293    // initialize callback function gets registered here
 294    elm_glview_init_func_set(gl, _init_gl);
 295    // delete callback function gets registered here
 296    elm_glview_del_func_set(gl, _del_gl);
 297    elm_glview_resize_func_set(gl, _resize_gggl);
 298    elm_glview_render_func_set(gl, _draw_gl);
 299    //-//
 300    //-//-//-// END GL INIT BLOB
 301
 302    elm_box_pack_end(bx, gl);
 303    evas_object_show(gl);
 304
 305    elm_object_focus_set(gl, EINA_TRUE);
 306
 307    // animating - just a demo. as long as you trigger an update on the image
 308    // object via elm_glview_changed_set() it will be updated.
 309    //
 310    // NOTE: if you delete gl, this animator will keep running trying to access
 311    // gl so you'd better delete this animator with ecore_animator_del().
 312    ani = ecore_animator_add(_anim, gl);
 313
 314    evas_object_data_set(gl, "ani", ani);
 315    evas_object_data_set(gl, "gld", gld);
 316    evas_object_event_callback_add(gl, EVAS_CALLBACK_DEL, _del, gl);
 317
 318    // add an 'OK' button to end the program
 319    bt = elm_button_add(win);
 320    elm_object_text_set(bt, "OK");
 321    evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
 322    evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, 0.0);
 323    elm_box_pack_end(bx, bt);
 324    evas_object_show(bt);
 325    evas_object_smart_callback_add(bt, "clicked", _on_done, win);
 326
 327    evas_object_resize(win, 320, 480);
 328    evas_object_show(win);
 329
 330    // run the mainloop and process events and callbacks
 331    elm_run();
 332    return 0;
 333 }
 334 ELM_MAIN()
 335  * @endcode
 336  */
 337
 338
 339
 340 /**
 341  * @addtogroup GLView
 342  * @{
 343  */
 344
 345 typedef void (*Elm_GLView_Func_Cb)(Evas_Object *obj);
 346
 347 typedef enum _Elm_GLView_Mode
 348 {
 349    ELM_GLVIEW_NONE    = 0,
 350    ELM_GLVIEW_ALPHA   = (1<<1), /**< Alpha channel enabled rendering mode */
 351    ELM_GLVIEW_DEPTH   = (1<<2), /**< Depth buffer enabled rendering mode */
 352    ELM_GLVIEW_STENCIL = (1<<3), /**< Stencil buffer enabled rendering mode */
 353    ELM_GLVIEW_DIRECT  = (1<<4)  /**< Direct rendering optimization hint */
 354 } Elm_GLView_Mode;
 355
 356 /**
 357  * Defines a policy for the glview resizing.
 358  *
 359  * The resizing policy tells glview what to do with the underlying
 360  * surface when resize happens. ELM_GLVIEW_RESIZE_POLICY_RECREATE
 361  * will destroy the current surface and recreate the surface to the
 362  * new size.  ELM_GLVIEW_RESIZE_POLICY_SCALE will instead keep the
 363  * current surface but only display the result at the desired size
 364  * scaled.
 365  *
 366  * @note Default is ELM_GLVIEW_RESIZE_POLICY_RECREATE
 367  */
 368 typedef enum
 369 {
 370    ELM_GLVIEW_RESIZE_POLICY_RECREATE = 1, /**< Resize the internal surface along with the image */
 371    ELM_GLVIEW_RESIZE_POLICY_SCALE    = 2  /**< Only resize the internal image and not the surface */
 372 } Elm_GLView_Resize_Policy;
 373
 374 /**
 375  * Defines a policy for gl rendering.
 376  *
 377  * The rendering policy tells glview where to run the gl rendering code.
 378  * ELM_GLVIEW_RENDER_POLICY_ON_DEMAND tells glview to call the rendering
 379  * calls on demand, which means that the rendering code gets called
 380  * only when it is visible.
 381  *
 382  * @note Default is ELM_GLVIEW_RENDER_POLICY_ON_DEMAND
 383  */
 384 typedef enum
 385 {
 386    ELM_GLVIEW_RENDER_POLICY_ON_DEMAND = 1, /**< Render only when there is a need for redrawing */
 387    ELM_GLVIEW_RENDER_POLICY_ALWAYS    = 2  /**< Render always even when it is not visible */
 388 } Elm_GLView_Render_Policy;
 389
 390 /**
 391  * Add a new glview to the parent
 392  *
 393  * @param parent The parent object
 394  * @return The new object or NULL if it cannot be created
 395  *
 396  * @ingroup GLView
 397  */
 398 EAPI Evas_Object *elm_glview_add(Evas_Object *parent);
 399
 400 /**
 401  * Sets the size of the glview
 402  *
 403  * @param obj The glview object
 404  * @param w width of the glview object
 405  * @param h height of the glview object
 406  *
 407  * @ingroup GLView
 408  */
 409 EAPI void         elm_glview_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
 410
 411 /**
 412  * Gets the size of the glview.
 413  *
 414  * @param obj The glview object
 415  * @param w width of the glview object
 416  * @param h height of the glview object
 417  *
 418  * Note that this function returns the actual image size of the
 419  * glview.  This means that when the scale policy is set to
 420  * ELM_GLVIEW_RESIZE_POLICY_SCALE, it'll return the non-scaled
 421  * size.
 422  *
 423  * @ingroup GLView
 424  */
 425 EAPI void         elm_glview_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
 426
 427 /**
 428  * Gets the gl api struct for gl rendering
 429  *
 430  * @param obj The glview object
 431  * @return The api object or NULL if it cannot be created
 432  *
 433  * @ingroup GLView
 434  */
 435 EAPI Evas_GL_API *elm_glview_gl_api_get(const Evas_Object *obj);
 436
 437 /**
 438  * Set the mode of the GLView. Supports alpha, depth, stencil.
 439  *
 440  * @param obj The glview object
 441  * @param mode The mode Options OR'ed enabling Alpha, Depth, Stencil, Direct.
 442  * @return True if set properly.
 443  *
 444  * Direct is a hint for the elm_glview to render directly to the window
 445  * given that the right conditions are met. Otherwise it falls back
 446  * to rendering to an offscreen buffer before it gets composited to the
 447  * window.
 448  *
 449  * @ingroup GLView
 450  */
 451 EAPI Eina_Bool    elm_glview_mode_set(Evas_Object *obj, Elm_GLView_Mode mode);
 452
 453 /**
 454  * Set the resize policy for the glview object.
 455  *
 456  * @param obj The glview object.
 457  * @param policy The scaling policy.
 458  *
 459  * By default, the resize policy is set to ELM_GLVIEW_RESIZE_POLICY_RECREATE.
 460  * When resize is called it destroys the previous surface and recreates the
 461  * newly specified size. If the policy is set to
 462  * ELM_GLVIEW_RESIZE_POLICY_SCALE, however, glview only scales the image
 463  * object and not the underlying GL Surface.
 464  *
 465  * @ingroup GLView
 466  */
 467 EAPI Eina_Bool    elm_glview_resize_policy_set(Evas_Object *obj, Elm_GLView_Resize_Policy policy);
 468
 469 /**
 470  * Set the render policy for the glview object.
 471  *
 472  * @param obj The glview object.
 473  * @param policy The render policy.
 474  *
 475  * By default, the render policy is set to ELM_GLVIEW_RENDER_POLICY_ON_DEMAND.
 476  * This policy is set such that during the render loop, glview is only
 477  * redrawn if it needs to be redrawn. (i.e. when it is visible) If the policy
 478  * is set to ELM_GLVIEWW_RENDER_POLICY_ALWAYS, it redraws regardless of
 479  * whether it is visible or needs redrawing.
 480  *
 481  * @ingroup GLView
 482  */
 483 EAPI Eina_Bool    elm_glview_render_policy_set(Evas_Object *obj, Elm_GLView_Render_Policy policy);
 484
 485 /**
 486  * Set the init function that runs once in the main loop.
 487  *
 488  * @param obj The glview object.
 489  * @param func The init function to be registered.
 490  *
 491  * The registered init function gets called once during the render loop.
 492  * This function allows glview to hide all the rendering context/surface
 493  * details and have the user just call GL calls that they desire
 494  * for initialization GL calls.
 495  *
 496  * @ingroup GLView
 497  */
 498 EAPI void         elm_glview_init_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
 499
 500 /**
 501  * Set the render function that runs in the main loop.
 502  *
 503  * @param obj The glview object.
 504  * @param func The delete function to be registered.
 505  *
 506  * The registered del function gets called when GLView object is deleted.
 507  * This function allows glview to hide all the rendering context/surface
 508  * details and have the user just call GL calls that they desire
 509  * when delete happens.
 510  *
 511  * @ingroup GLView
 512  */
 513 EAPI void         elm_glview_del_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
 514
 515 /**
 516  * Set the resize function that gets called when resize happens.
 517  *
 518  * @param obj The glview object.
 519  * @param func The resize function to be registered.
 520  *
 521  * The resize function gets called during the render loop.
 522  * This function allows glview to hide all the rendering context/surface
 523  * details and have the user just call GL calls that they desire
 524  * when resize happens.
 525  *
 526  * @ingroup GLView
 527  */
 528 EAPI void         elm_glview_resize_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
 529
 530 /**
 531  * Set the render function that runs in the main loop.
 532  *
 533  * The render function gets called in the main loop but whether it runs
 534  * depends on the rendering policy and whether elm_glview_changed_set()
 535  * gets called.
 536  *
 537  * @param obj The glview object.
 538  * @param func The render function to be registered.
 539  *
 540  * @ingroup GLView
 541  */
 542 EAPI void         elm_glview_render_func_set(Evas_Object *obj, Elm_GLView_Func_Cb func);
 543
 544 /**
 545  * Notifies that there has been changes in the GLView.
 546  *
 547  * @param obj The glview object.
 548  *
 549  * @ingroup GLView
 550  */
 551 EAPI void         elm_glview_changed_set(Evas_Object *obj);
 552
 553 /**
 554  * @}
 555  */