summaryrefslogtreecommitdiff
path: root/src/lib/evas/Evas_GL.h
diff options
context:
space:
mode:
authorJean-Philippe Andre <jp.andre@samsung.com>2014-09-19 15:45:28 +0900
committerJean-Philippe Andre <jp.andre@samsung.com>2014-10-20 12:16:08 +0900
commit6cd0aa17dae73dd242ce95bc23dbb13657875baa (patch)
tree0167ec2546c6a86d9b96753427b06c08470b0242 /src/lib/evas/Evas_GL.h
parent29e7f54ea0458e4634fd0d9d3f1290063a1bdbf3 (diff)
Evas GL: Some documentation fixups
Diffstat (limited to 'src/lib/evas/Evas_GL.h')
-rw-r--r--src/lib/evas/Evas_GL.h283
1 files changed, 164 insertions, 119 deletions
diff --git a/src/lib/evas/Evas_GL.h b/src/lib/evas/Evas_GL.h
index f6b595a90e..c061770406 100644
--- a/src/lib/evas/Evas_GL.h
+++ b/src/lib/evas/Evas_GL.h
@@ -10,10 +10,14 @@ extern "C" {
10 10
11/** 11/**
12 * @defgroup Evas_GL Rendering GL on Evas 12 * @defgroup Evas_GL Rendering GL on Evas
13 * @ingroup Evas_Canvas
14 *
15 * @brief This group discusses the functions that are used to do OpenGL rendering on Evas. Evas allows you
16 * to use OpenGL to render to specially set up image objects (which act as
17 * render target surfaces).
18 *
13 * 19 *
14 * Functions that are used to do OpenGL rendering on Evas. Evas allows you 20 * <h2> Evas GL usage example </h2>
15 * to use OpenGL to render to specially set up image objects (which act as
16 * render target surfaces).
17 * 21 *
18 * Below is an illustrative example of how to use OpenGL to render to an 22 * Below is an illustrative example of how to use OpenGL to render to an
19 * object in Evas. 23 * object in Evas.
@@ -39,10 +43,10 @@ typedef struct _GLData
39 Eina_Bool initialized : 1; 43 Eina_Bool initialized : 1;
40} GLData; 44} GLData;
41 45
42// callbacks we want to handle deletion on the object and updates/draws 46// Callbacks we need to handle deletion on the object and updates/draws
43static void on_del (void *data, Evas *e, Evas_Object *obj, void *event_info); 47static void on_del (void *data, Evas *e, Evas_Object *obj, void *event_info);
44static void on_pixels (void *data, Evas_Object *obj); 48static void on_pixels (void *data, Evas_Object *obj);
45// demo - animator just to keep ticking over saying to draw the image 49// Demo - animator just to keep ticking over asking to draw the image
46static Eina_Bool on_animate (void *data); 50static Eina_Bool on_animate (void *data);
47// gl stuff 51// gl stuff
48static int init_shaders (GLData *gld); 52static int init_shaders (GLData *gld);
@@ -51,23 +55,23 @@ static GLuint load_shader (GLData *gld, GLenum type, const char *shader_src)
51int 55int
52main(int argc, char **argv) 56main(int argc, char **argv)
53{ 57{
54 // a size by default 58 // A size by default
55 int w = 256, h = 256; 59 int w = 256, h = 256;
56 // some variables we will use 60 // Some variables we will use
57 Ecore_Evas *ee; 61 Ecore_Evas *ee;
58 Evas *canvas; 62 Evas *canvas;
59 Evas_Object *r1; 63 Evas_Object *r1;
60 Evas_Native_Surface ns; 64 Evas_Native_Surface ns;
61 GLData *gld = NULL; 65 GLData *gld = NULL;
62 66
63 // regular low-leve EFL (ecore+ecore-evas) init. elm is simpler 67 // Regular low-level EFL (ecore+ecore-evas) init. elm is simpler
64 ecore_init(); 68 ecore_init();
65 ecore_evas_init(); 69 ecore_evas_init();
66 ee = ecore_evas_gl_x11_new(NULL, 0, 0, 0, 512, 512); 70 ee = ecore_evas_gl_x11_new(NULL, 0, 0, 0, 512, 512);
67 ecore_evas_title_set(ee, "Ecore_Evas Template"); 71 ecore_evas_title_set(ee, "Ecore_Evas Template");
68 canvas = ecore_evas_get(ee); 72 canvas = ecore_evas_get(ee);
69 73
70 // alloc a data struct to hold our relevant gl info in 74 // Alloc a data struct to hold our relevant gl info in it
71 if (!(gld = calloc(1, sizeof(GLData)))) return 0; 75 if (!(gld = calloc(1, sizeof(GLData)))) return 0;
72 76
73 //-//-//-// THIS IS WHERE GL INIT STUFF HAPPENS (ALA EGL) 77 //-//-//-// THIS IS WHERE GL INIT STUFF HAPPENS (ALA EGL)
@@ -83,26 +87,26 @@ main(int argc, char **argv)
83 //gld->cfg->stencil_bits = EVAS_GL_STENCIL_NONE; 87 //gld->cfg->stencil_bits = EVAS_GL_STENCIL_NONE;
84 //gld->cfg->options_bits = EVAS_GL_OPTIONS_NONE; 88 //gld->cfg->options_bits = EVAS_GL_OPTIONS_NONE;
85 89
86 // create a surface and context 90 // Create a surface and context
87 gld->sfc = evas_gl_surface_create(gld->evasgl, gld->cfg, w, h); 91 gld->sfc = evas_gl_surface_create(gld->evasgl, gld->cfg, w, h);
88 gld->ctx = evas_gl_context_create(gld->evasgl, NULL); 92 gld->ctx = evas_gl_context_create(gld->evasgl, NULL);
89 //-// 93 //-//
90 //-//-//-// END GL INIT BLOB 94 //-//-//-// END GL INIT BLOB
91 95
92 // set up the image object. a filled one by default 96 // Set up the image object. A filled one by default
93 r1 = evas_object_image_filled_add(canvas); 97 r1 = evas_object_image_filled_add(canvas);
94 // attach important data we need to the object using key names. This just 98 // Attach important data we need to the object using key names. This just
95 // avoids some global variables and means we can do nice cleanup. You can 99 // avoids some global variables which means we can do a good cleanup. You can
96 // avoid this if you are lazy 100 // avoid this if you are lazy
97 evas_object_data_set(r1, "..gld", gld); 101 evas_object_data_set(r1, "..gld", gld);
98 // when the object is deleted - call the on_del callback. like the above, 102 // When the object is deleted - call the on_del callback. Like the above,
99 // this is just being clean 103 // this is just being clean
100 evas_object_event_callback_add(r1, EVAS_CALLBACK_DEL, on_del, NULL); 104 evas_object_event_callback_add(r1, EVAS_CALLBACK_DEL, on_del, NULL);
101 // set up an actual pixel size fot the buffer data. It may be different 105 // Set up an actual pixel size for the buffer data. It may be different
102 // to the output size. any windowing system has something like this, just 106 // from the output size. Any windowing system has something like this, only
103 // evas has 2 sizes, a pixel size and the output object size 107 // evas has 2 sizes, a pixel size and the output object size
104 evas_object_image_size_set(r1, w, h); 108 evas_object_image_size_set(r1, w, h);
105 // set up the native surface info to use the context and surface created 109 // Set up the native surface info to use the context and surface created
106 // above 110 // above
107 111
108 //-//-//-// THIS IS WHERE GL INIT STUFF HAPPENS (ALA EGL) 112 //-//-//-// THIS IS WHERE GL INIT STUFF HAPPENS (ALA EGL)
@@ -113,32 +117,32 @@ main(int argc, char **argv)
113 //-// 117 //-//
114 //-//-//-// END GL INIT BLOB 118 //-//-//-// END GL INIT BLOB
115 119
116 // move the image object somewhere, resize it and show it. any windowing 120 // Move the image object somewhere, resize it, and show it. Any windowing
117 // system would need this kind of thing - place a child "window" 121 // system would need this kind of thing - place a child "window"
118 evas_object_move(r1, 128, 128); 122 evas_object_move(r1, 128, 128);
119 evas_object_resize(r1, w, h); 123 evas_object_resize(r1, w, h);
120 evas_object_show(r1); 124 evas_object_show(r1);
121 125
122 // animating - just a demo. as long as you trigger an update on the image 126 // Animating - just a demo. As long as you trigger an update on the image
123 // object via evas_object_image_pixels_dirty_set(). any display system, 127 // object via evas_object_image_pixels_dirty_set(), any display system,
124 // mainloop siztem etc. will have something of this kind unless it's making 128 // mainloop system etc., will have something of this kind unless it's making
125 // you spin infinitely yourself and invent your own animation mechanism 129 // you spin infinitely by yourself and invent your own animation mechanism
126 // 130 //
127 // NOTE: if you delete r1, this animator will keep running trying to access 131 // NOTE: If you delete r1, this animator will keep running and trying to access
128 // r1 so you'd better delete this animator with ecore_animator_del() or 132 // r1 so you'd better delete this animator with ecore_animator_del() or
129 // structure how you do animation differently. you can also attach it like 133 // structure how you do animation differently. You can also attach it like
130 // evasgl, sfc, etc. etc. if this animator is specific to this object 134 // evasgl, sfc, etc., if this animator is specific to this object
131 // only and delete it in the del handler for the obj. 135 // then delete it in the del handler for the obj.
132 ecore_animator_add(on_animate, r1); 136 ecore_animator_add(on_animate, r1);
133 137
134 // finally show the window for the world to see. windowing system generic 138 // Finally show the window for the world to see. Windowing system generic
135 ecore_evas_show(ee); 139 ecore_evas_show(ee);
136 140
137 // begin the mainloop and tick over the animator, handle events etc. 141 // Begin the mainloop and tick over the animator, handle events, etc.
138 // also windowing system generic 142 // Also windowing system generic
139 ecore_main_loop_begin(); 143 ecore_main_loop_begin();
140 144
141 // standard EFL shutdown stuff - generic for most systems, EFL or not 145 // Standard EFL shutdown stuff - generic for most systems, EFL or not
142 ecore_evas_shutdown(); 146 ecore_evas_shutdown();
143 ecore_shutdown(); 147 ecore_shutdown();
144 return 0; 148 return 0;
@@ -147,11 +151,11 @@ main(int argc, char **argv)
147static void 151static void
148on_del(void *data, Evas *e, Evas_Object *obj, void *event_info) 152on_del(void *data, Evas *e, Evas_Object *obj, void *event_info)
149{ 153{
150 // on delete of our object clean up some things that don't get auto 154 // On delete of our object clean up some things that don't get auto
151 // celeted for us as they are not intrinsically bound to the image 155 // deleted for us as they are not intrinsically bound to the image
152 // object as such (you could use the same context and surface across 156 // object as such (you could use the same context and surface across
153 // multiple image objects and re-use the evasgl handle too multiple times. 157 // multiple image objects and re-use the evasgl handle multiple times.
154 // here we bind them to 1 object only though by doing this. 158 // Here we bind them to only 1 object though by doing this.
155 GLData *gld = evas_object_data_get(obj, "..gld"); 159 GLData *gld = evas_object_data_get(obj, "..gld");
156 if (!gld) return; 160 if (!gld) return;
157 Evas_GL_API *gl = gld->glapi; 161 Evas_GL_API *gl = gld->glapi;
@@ -174,7 +178,7 @@ on_del(void *data, Evas *e, Evas_Object *obj, void *event_info)
174static void 178static void
175on_pixels(void *data, Evas_Object *obj) 179on_pixels(void *data, Evas_Object *obj)
176{ 180{
177 // get some variable we need from the object data keys 181 // Get some variable we need from the object data keys
178 GLData *gld = evas_object_data_get(obj, "..gld"); 182 GLData *gld = evas_object_data_get(obj, "..gld");
179 if (!gld) return; 183 if (!gld) return;
180 Evas_GL_API *gl = gld->glapi; 184 Evas_GL_API *gl = gld->glapi;
@@ -186,9 +190,9 @@ on_pixels(void *data, Evas_Object *obj)
186 }; 190 };
187 int w, h; 191 int w, h;
188 192
189 // get the image size in case it changed with evas_object_image_size_set() 193 // Get the image size, in case it changed, with evas_object_image_size_set()
190 evas_object_image_size_get(obj, &w, &h); 194 evas_object_image_size_get(obj, &w, &h);
191 // set up the context and surface as the current one 195 // Set up the context and surface as the current one
192 evas_gl_make_current(gld->evasgl, gld->sfc, gld->ctx); 196 evas_gl_make_current(gld->evasgl, gld->sfc, gld->ctx);
193 197
194 if (!gld->initialized) 198 if (!gld->initialized)
@@ -197,12 +201,12 @@ on_pixels(void *data, Evas_Object *obj)
197 gld->initialized = EINA_TRUE; 201 gld->initialized = EINA_TRUE;
198 } 202 }
199 203
200 // GL Viewport stuff. you can avoid doing this if viewport is all the 204 // GL Viewport stuff. You can avoid doing this if viewport is all the
201 // same as last frame if you want 205 // same as the last frame, if you want
202 gl->glViewport(0, 0, w, h); 206 gl->glViewport(0, 0, w, h);
203 207
204 // Clear the buffer 208 // Clear the buffer
205 gl->glClearColor(0.0, 0.0, 1.0, 1); 209 gl->glClearColor(1.0, 0.0, 0.0, 1);
206 gl->glClear(GL_COLOR_BUFFER_BIT); 210 gl->glClear(GL_COLOR_BUFFER_BIT);
207 211
208 // Draw a Triangle 212 // Draw a Triangle
@@ -222,11 +226,11 @@ on_pixels(void *data, Evas_Object *obj)
222static Eina_Bool 226static Eina_Bool
223on_animate(void *data) 227on_animate(void *data)
224{ 228{
225 // just a demo - animate here whenever an animation tick happens and then 229 // Just a demo - Animate here whenever an animation tick happens and then
226 // mark the image as "dirty" meaning it needs an update next time evas 230 // mark the image as "dirty" meaning it needs an update the next time evas
227 // renders. it will call the pixel get callback then. 231 // renders. It will then call the pixel get callback.
228 evas_object_image_pixels_dirty_set(data, EINA_TRUE); 232 evas_object_image_pixels_dirty_set(data, EINA_TRUE);
229 return EINA_TRUE; // keep looping 233 return EINA_TRUE; // Keep looping
230} 234}
231 235
232static GLuint 236static GLuint
@@ -336,54 +340,54 @@ init_shaders(GLData *gld)
336/** 340/**
337 * @typedef Evas_GL 341 * @typedef Evas_GL
338 * 342 *
339 * Evas GL Object for rendering gl in Evas. 343 * @brief The structure type of the Evas GL object used to render GL in Evas.
340 */ 344 */
341typedef struct _Evas_GL Evas_GL; 345typedef struct _Evas_GL Evas_GL;
342 346
343/** 347/**
344 * @typedef Evas_GL_Surface 348 * @typedef Evas_GL_Surface
345 * 349 *
346 * Evas GL Surface object, a GL rendering target in Evas GL. 350 * @brief The structure type of the Evas GL Surface object, a GL rendering target in Evas GL.
347 */ 351 */
348typedef struct _Evas_GL_Surface Evas_GL_Surface; 352typedef struct _Evas_GL_Surface Evas_GL_Surface;
349 353
350/** 354/**
351 * @typedef Evas_GL_Context 355 * @typedef Evas_GL_Context
352 * 356 *
353 * Evas GL Context object, a GL rendering context in Evas GL. 357 * @brief The structure type of the Evas GL Context object, a GL rendering context in Evas GL.
354 */ 358 */
355typedef struct _Evas_GL_Context Evas_GL_Context; 359typedef struct _Evas_GL_Context Evas_GL_Context;
356 360
357/** 361/**
358 * @typedef Evas_GL_Config 362 * @typedef Evas_GL_Config
359 * 363 *
360 * Evas GL Surface configuration object for surface creation. 364 * @brief The structure type of the Evas GL Surface configuration object for surface creation.
361 */ 365 */
362typedef struct _Evas_GL_Config Evas_GL_Config; 366typedef struct _Evas_GL_Config Evas_GL_Config;
363 367
364/** 368/**
365 * @typedef Evas_GL_API 369 * @typedef Evas_GL_API
366 * 370 *
367 * Evas GL API object that contains the GL APIs to be used in Evas GL. 371 * @brief The structure type of the Evas GL API object that contains the GL APIs to be used in Evas GL.
368 */ 372 */
369typedef struct _Evas_GL_API Evas_GL_API; 373typedef struct _Evas_GL_API Evas_GL_API;
370 374
371/** 375/**
372 * @typedef Evas_GL_Func 376 * @typedef Evas_GL_Func
373 * 377 *
374 * Evas GL Function Object used as a function pointer. 378 * @brief Represents a function pointer, that can be used for Evas GL extensions.
375 */ 379 */
376typedef void *Evas_GL_Func; 380typedef void *Evas_GL_Func;
377 381
378/** 382/**
379 * @typedef EvasGLImage 383 * @typedef EvasGLImage
380 * 384 *
381 * Evas GL Image Object used in Evas GL Image extension. 385 * @brief Represents an Evas GL Image object used with Evas GL Image extensions.
382 */ 386 */
383typedef void *EvasGLImage; 387typedef void *EvasGLImage;
384 388
385/** 389/**
386 * Surface Color Format 390 * @brief Enumeration that defines the available surface color formats.
387 */ 391 */
388typedef enum _Evas_GL_Color_Format 392typedef enum _Evas_GL_Color_Format
389{ 393{
@@ -392,7 +396,7 @@ typedef enum _Evas_GL_Color_Format
392} Evas_GL_Color_Format; 396} Evas_GL_Color_Format;
393 397
394/** 398/**
395 * Surface Depth Format 399 * @brief Enumeration that defines the Surface Depth Format.
396 */ 400 */
397typedef enum _Evas_GL_Depth_Bits 401typedef enum _Evas_GL_Depth_Bits
398{ 402{
@@ -404,7 +408,7 @@ typedef enum _Evas_GL_Depth_Bits
404} Evas_GL_Depth_Bits; 408} Evas_GL_Depth_Bits;
405 409
406/** 410/**
407 * Surface Stencil Format 411 * @brief Enumeration that defines the Surface Stencil Format.
408 */ 412 */
409typedef enum _Evas_GL_Stencil_Bits 413typedef enum _Evas_GL_Stencil_Bits
410{ 414{
@@ -417,7 +421,7 @@ typedef enum _Evas_GL_Stencil_Bits
417} Evas_GL_Stencil_Bits; 421} Evas_GL_Stencil_Bits;
418 422
419/** 423/**
420 * Configuration Options. 424 * @brief Enumeration that defines the Configuration Options.
421 * 425 *
422 * @since 1.1 426 * @since 1.1
423 */ 427 */
@@ -431,10 +435,11 @@ typedef enum _Evas_GL_Options_Bits
431} Evas_GL_Options_Bits; 435} Evas_GL_Options_Bits;
432 436
433/** 437/**
434 * Configuration Option for Multisample Anti-aliased (MSAA) rendering surface. 438 * @brief Enumeration that defines the configuration options for a Multisample Anti-Aliased (MSAA) rendering surface.
435 * Only works in supported device.
436 * 439 *
437 * @since 1.2 440 * @since 1.2
441 *
442 * @remarks This only works on devices that support the required extensions.
438 */ 443 */
439typedef enum _Evas_GL_Multisample_Bits 444typedef enum _Evas_GL_Multisample_Bits
440{ 445{
@@ -445,10 +450,16 @@ typedef enum _Evas_GL_Multisample_Bits
445} Evas_GL_Multisample_Bits; 450} Evas_GL_Multisample_Bits;
446 451
447/** 452/**
448 * @struct _Evas_GL_Config 453 * @struct _Evas_GL_Config
449 * 454 *
450 * Evas GL Surface configuration 455 * @brief A structure used to specify the configuration of an @ref Evas_GL_Surface.
451 */ 456 *
457 * This structure should be allocated with @ref evas_gl_config_new() and released
458 * with @ref evas_gl_config_free().
459 *
460 * @see evas_gl_surface_create
461 * @see evas_gl_pbuffer_surface_create
462 */
452struct _Evas_GL_Config 463struct _Evas_GL_Config
453{ 464{
454 Evas_GL_Color_Format color_format; /**< Surface Color Format */ 465 Evas_GL_Color_Format color_format; /**< Surface Color Format */
@@ -463,104 +474,134 @@ struct _Evas_GL_Config
463 474
464 475
465/** 476/**
466 * Creates a new Evas_GL object and returns a handle for gl rendering on efl. 477 * @brief Creates a new Evas_GL object and returns a handle for GL rendering with the EFL.
478 *
479 * @param[in] e The given Evas canvas to use
467 * 480 *
468 * @param e The given evas canvas OpenGL is to be used on. 481 * @return The created Evas_GL object, or @c NULL in case of failure
469 * @return The created evas_gl object, or NULL on failure.
470 */ 482 */
471EAPI Evas_GL *evas_gl_new (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 483EAPI Evas_GL *evas_gl_new (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
472 484
473/** 485/**
474 * Frees the created Evas_GL object. 486 * @brief Frees an Evas_GL object.
475 * 487 *
476 * @param evas_gl The given Evas_GL object. 488 * @param[in] evas_gl The given Evas_GL object to destroy
489 *
490 * @see evas_gl_new
477 */ 491 */
478EAPI void evas_gl_free (Evas_GL *evas_gl) EINA_ARG_NONNULL(1); 492EAPI void evas_gl_free (Evas_GL *evas_gl) EINA_ARG_NONNULL(1);
479 493
480/** 494/**
481 * Allocates a new config object for the user to fill out. 495 * @brief Allocates a new config object for the user to fill out.
496 *
497 * @remarks As long as Evas creates a config object for the user, it takes care
498 * of the backward compatibility issue.
482 * 499 *
483 * As long as the Evas creates a config object for the user, it takes care 500 * @see evas_gl_config_free
484 * of the backward compatibility issue.
485 */ 501 */
486EAPI Evas_GL_Config *evas_gl_config_new (void); 502EAPI Evas_GL_Config *evas_gl_config_new (void);
487 503
488/** 504/**
489 * Frees a config object created from evas_gl_config_new. 505 * @brief Frees a config object created from evas_gl_config_new.
506 *
507 * @param[in] cfg The configuration structure to free, it can not be accessed afterwards.
490 * 508 *
491 * As long as the Evas creates a config object for the user, it takes care 509 * @remarks As long as Evas creates a config object for the user, it takes care
492 * of the backward compatibility issue. 510 * of the backward compatibility issue.
511 *
512 * @see evas_gl_config_new
493 */ 513 */
494EAPI void evas_gl_config_free (Evas_GL_Config *cfg) EINA_ARG_NONNULL(1); 514EAPI void evas_gl_config_free (Evas_GL_Config *cfg) EINA_ARG_NONNULL(1);
495 515
496/** 516/**
497 * Creates and returns new Evas_GL_Surface object for GL Rendering. 517 * @brief Creates and returns a new @ref Evas_GL_Surface object for GL Rendering.
498 * 518 *
499 * @param evas_gl The given Evas_GL object. 519 * @param[in] evas_gl The given Evas_GL object
500 * @param cfg The pixel format and configuration of the rendering surface. 520 * @param[in] cfg The pixel format and configuration of the rendering surface
501 * @param w The width of the surface. 521 * @param[in] w The width of the surface
502 * @param h The height of the surface. 522 * @param[in] h The height of the surface
503 * @return The created GL surface object, or NULL on failure. 523 *
524 * @return The created GL surface object,
525 * otherwise @c NULL on failure
526 *
527 * @see evas_gl_surface_destroy
504 */ 528 */
505EAPI Evas_GL_Surface *evas_gl_surface_create (Evas_GL *evas_gl, Evas_GL_Config *cfg, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2); 529EAPI Evas_GL_Surface *evas_gl_surface_create (Evas_GL *evas_gl, Evas_GL_Config *cfg, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2);
506 530
507/** 531/**
508 * Destroys the created Evas GL Surface. 532 * @brief Destroys an Evas GL Surface.
509 * 533 *
510 * @param evas_gl The given Evas_GL object. 534 * @param[in] evas_gl The given Evas_GL object
511 * @param surf The given GL surface object. 535 * @param[in] surf The given GL surface object
512 */ 536 */
513EAPI void evas_gl_surface_destroy (Evas_GL *evas_gl, Evas_GL_Surface *surf) EINA_ARG_NONNULL(1,2); 537EAPI void evas_gl_surface_destroy (Evas_GL *evas_gl, Evas_GL_Surface *surf) EINA_ARG_NONNULL(1,2);
514 538
515/** 539/**
516 * Creates and returns a new Evas GL context object 540 * @brief Creates and returns a new Evas GL context object.
517 * 541 *
518 * @param evas_gl The given Evas_GL object. 542 * @param[in] evas_gl The given Evas_GL object
519 * @return The created context, or NULL on failure. 543 * @param[in] share_ctx An Evas_GL context to share with the new context
544 *
545 * @return The created context,
546 * otherwise @c NULL on failure
520 */ 547 */
521EAPI Evas_GL_Context *evas_gl_context_create (Evas_GL *evas_gl, Evas_GL_Context *share_ctx) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 548EAPI Evas_GL_Context *evas_gl_context_create (Evas_GL *evas_gl, Evas_GL_Context *share_ctx) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
522 549
523/** 550/**
524 * Destroys the given Evas GL context object 551 * @brief Destroys the given Evas GL context object.
525 * 552 *
526 * @param evas_gl The given Evas_GL object. 553 * @param[in] evas_gl The given Evas_GL object
527 * @param ctx The given Evas GL context. 554 * @param[in] ctx The given Evas GL context
555 *
556 * @see evas_gl_context_create
557 * @see evas_gl_context_version_create
528 */ 558 */
529EAPI void evas_gl_context_destroy (Evas_GL *evas_gl, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2); 559EAPI void evas_gl_context_destroy (Evas_GL *evas_gl, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2);
530 560
531/** 561/**
532 * Sets the given context as a current context for the given surface 562 * @brief Sets the given context as the current context for the given surface.
533 * 563 *
534 * @param evas_gl The given Evas_GL object. 564 * @param[in] evas_gl The given Evas_GL object
535 * @param surf The given Evas GL surface. 565 * @param[in] surf The given Evas GL surface
536 * @param ctx The given Evas GL context. 566 * @param[in] ctx The given Evas GL context
537 * @return @c EINA_TRUE if successful, @c EINA_FALSE if not. 567 * @return @c EINA_TRUE if successful,
568 * otherwise @c EINA_FALSE if not
538 */ 569 */
539EAPI Eina_Bool evas_gl_make_current (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2); 570EAPI Eina_Bool evas_gl_make_current (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2);
540 571
541/** 572/**
542 * Returns a pointer to a static, zero-terminated string describing some aspect of evas_gl. 573 * @brief Returns a pointer to a static, null-terminated string describing some aspect of Evas GL.
543 * 574 *
544 * @param evas_gl The given Evas_GL object. 575 * @param[in] evas_gl The given Evas_GL object
545 * @param name Specifies a symbolic constant, one of EVAS_GL_EXTENSIONS... 576 * @param[in] name A symbolic constant, only @ref EVAS_GL_EXTENSIONS is supported for now
546 */ 577 */
547EAPI const char *evas_gl_string_query (Evas_GL *evas_gl, int name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; 578EAPI const char *evas_gl_string_query (Evas_GL *evas_gl, int name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
548 579
549/** 580/**
550 * Returns a GL or the Glue Layer's extension function. 581 * @brief Returns a extension function from OpenGL or the Evas_GL glue layer.
582 *
583 * @param[in] evas_gl The given Evas_GL object
584 * @param[in] name The name of the function to return
551 * 585 *
552 * @param evas_gl The given Evas_GL object. 586 * The available extension functions may depend on the backend engine Evas GL is
553 * @param name The name of the function to return. 587 * running on.
588 *
589 * @return A function pointer to the Evas_GL extension.
554 */ 590 */
555EAPI Evas_GL_Func evas_gl_proc_address_get (Evas_GL *evas_gl, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2) EINA_PURE; 591EAPI Evas_GL_Func evas_gl_proc_address_get (Evas_GL *evas_gl, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2) EINA_PURE;
556 592
557/** 593/**
558 * Fills in the Native Surface information from the given Evas GL surface. 594 * @brief Fills in the Native Surface information from a given Evas GL surface.
595 *
596 * @param[in] evas_gl The given Evas_GL object
597 * @param[in] surf The given Evas GL surface to retrieve the Native Surface information from
598 * @param[out] ns The native surface structure that the function fills in
599 * @return @c EINA_TRUE if successful,
600 * otherwise @c EINA_FALSE if not
559 * 601 *
560 * @param evas_gl The given Evas_GL object. 602 * @details This function can be called to later set this native surface as
561 * @param surf The given Evas GL surface to retrieve the Native Surface info from. 603 * source of an Evas Object Image. Please refer to
562 * @param ns The native surface structure that the function fills in. 604 * @ref evas_object_image_native_surface_set.
563 * @return @c EINA_TRUE if successful, @c EINA_FALSE if not.
564 */ 605 */
565EAPI Eina_Bool evas_gl_native_surface_get (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_Native_Surface *ns) EINA_ARG_NONNULL(1,2,3); 606EAPI Eina_Bool evas_gl_native_surface_get (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_Native_Surface *ns) EINA_ARG_NONNULL(1,2,3);
566 607
@@ -634,11 +675,15 @@ EAPI Eina_Bool evas_gl_surface_query (Evas_GL *evas_gl, Evas
634 * @return @ref EVAS_GL_SUCCESS in case of no error, or any other @c EVAS_GL error code. 675 * @return @ref EVAS_GL_SUCCESS in case of no error, or any other @c EVAS_GL error code.
635 * 676 *
636 * Since Evas GL is a glue layer for GL imitating EGL, the error codes returned 677 * Since Evas GL is a glue layer for GL imitating EGL, the error codes returned
637 * have the same meaning as those defined in EGL. 678 * have a similar meaning as those defined in EGL, so please refer to the EGL
679 * documentation for more information about the various error codes.
638 * 680 *
639 * @note At the moment of writing, this API is only partially implemented 681 * @note Evas GL does not specify exactly which error codes will be returned in
640 * and might return @c EVAS_GL_SUCCESS even when the last call(s) to 682 * which circumstances. This is because different backends may behave
641 * Evas_GL failed. 683 * differently and Evas GL will try to give the most meaningful error code
684 * based on the backend's error. Evas GL only tries to provide some
685 * information, so an application can not expect the exact same error
686 * codes as EGL would return.
642 * 687 *
643 * @since 1.12 688 * @since 1.12
644 */ 689 */
@@ -1547,10 +1592,10 @@ typedef unsigned long long EvasGLTime;
1547 * The attributes can be queried using @ref evas_gl_surface_query 1592 * The attributes can be queried using @ref evas_gl_surface_query
1548 * @{ 1593 * @{
1549 */ 1594 */
1550#define EVAS_GL_HEIGHT 0x3056 /**< Attribute for @ref evas_gl_surface_query, returns the surface width in pixels (@c value should be an @c int) */ 1595#define EVAS_GL_HEIGHT 0x3056 /**< @brief Attribute for @ref evas_gl_surface_query, returns the surface width in pixels (@c value should be an @c int) */
1551#define EVAS_GL_WIDTH 0x3057 /**< Attribute for @ref evas_gl_surface_query, returns the surface width in pixels (@c value should be an @c int) */ 1596#define EVAS_GL_WIDTH 0x3057 /**< @brief Attribute for @ref evas_gl_surface_query, returns the surface width in pixels (@c value should be an @c int) */
1552#define EVAS_GL_TEXTURE_FORMAT 0x3080 /**< Attribute for @ref evas_gl_surface_query, returns an @ref Evas_GL_Color_Format */ 1597#define EVAS_GL_TEXTURE_FORMAT 0x3080 /**< @brief Attribute for @ref evas_gl_surface_query, returns an @ref Evas_GL_Color_Format */
1553#define EVAS_GL_TEXTURE_TARGET 0x3081 /**< Attribute for @ref evas_gl_surface_query, returns @ref EVAS_GL_TEXTURE_2D (if format is @c EVAS_GL_RGB_888 or @c EVAS_GL_RGBA_8888) or 0 (meaning @c NO_TEXTURE, from @c EVAS_GL_NO_FBO) (@c value should be an @c int) */ 1598#define EVAS_GL_TEXTURE_TARGET 0x3081 /**< @brief Attribute for @ref evas_gl_surface_query, returns @ref EVAS_GL_TEXTURE_2D (if format is @c EVAS_GL_RGB_888 or @c EVAS_GL_RGBA_8888) or 0 (meaning @c NO_TEXTURE, from @c EVAS_GL_NO_FBO) (@c value should be an @c int) */
1554/** @} */ 1599/** @} */
1555 1600
1556#define EVAS_GL_API_VERSION 1 1601#define EVAS_GL_API_VERSION 1
@@ -1867,7 +1912,7 @@ EvasGLImage *img = glapi->evasglCreateImageForContext
1867 * @since 1.12 1912 * @since 1.12
1868 */ 1913 */
1869 EvasGLImage (*evasglCreateImageForContext) (Evas_GL *evas_gl, Evas_GL_Context *ctx, int target, void* buffer, const int* attrib_list) EINA_WARN_UNUSED_RESULT; 1914 EvasGLImage (*evasglCreateImageForContext) (Evas_GL *evas_gl, Evas_GL_Context *ctx, int target, void* buffer, const int* attrib_list) EINA_WARN_UNUSED_RESULT;
1870 1915 /** @} */
1871 1916
1872 1917
1873 /*------- EvasGL / EGL-related functions -------*/ 1918 /*------- EvasGL / EGL-related functions -------*/