src/lib/canvas/evas_main.c

   1 #include "evas_common.h"
   2 #include "evas_private.h"
   3 #include "evas_cs.h"
   4
   5 static int _evas_init_count = 0;
   6 int _evas_log_dom_global = -1;
   7 /**
   8  * Initialize Evas
   9  *
  10  * @return The init counter value.
  11  *
  12  * This function initialize evas, increments a counter of the number
  13  * of calls to this function and returns this value.
  14  *
  15  * @see evas_shutdown().
  16  *
  17  * @ingroup Evas_Group
  18  */
  19 EAPI int
  20 evas_init(void)
  21 {
  22    if (++_evas_init_count != 1)
  23      return _evas_init_count;
  24
  25 #ifdef HAVE_EVIL
  26    if (!evil_init())
  27      return --_evas_init_count;
  28 #endif
  29
  30    if (!eina_init())
  31      goto shutdown_evil;
  32
  33    _evas_log_dom_global = eina_log_domain_register("evas_main",EVAS_DEFAULT_LOG_COLOR);
  34    if (_evas_log_dom_global < 0)
  35      {
  36         EINA_LOG_ERR("Evas could not create a default log domain\n");
  37         goto shutdown_eina;
  38      }
  39
  40    evas_module_init();
  41 #ifdef BUILD_ASYNC_EVENTS
  42    if (!evas_async_events_init())
  43      goto shutdown_module;
  44 #endif
  45 #ifdef EVAS_CSERVE
  46    if (getenv("EVAS_CSERVE")) evas_cserve_init();
  47 #endif
  48 #ifdef BUILD_ASYNC_PRELOAD
  49    _evas_preload_thread_init();
  50 #endif
  51 #ifdef EVAS_FRAME_QUEUING
  52    evas_common_frameq_init();
  53 #endif
  54
  55    return _evas_init_count;
  56
  57 #ifdef BUILD_ASYNC_EVENTS
  58  shutdown_module:
  59    evas_module_shutdown();
  60    eina_log_domain_unregister(_evas_log_dom_global);
  61 #endif
  62  shutdown_eina:
  63    eina_shutdown();
  64  shutdown_evil:
  65 #ifdef HAVE_EVIL
  66    evil_shutdown();
  67 #endif
  68
  69    return --_evas_init_count;
  70 }
  71
  72 /**
  73  * Shutdown Evas
  74  *
  75  * @return The init counter value.
  76  *
  77  * This function finalize evas, decrements the counter of the number
  78  * of calls to the function evas_init() and returns this value.
  79  *
  80  * @see evas_init().
  81  *
  82  * @ingroup Evas_Group
  83  */
  84 EAPI int
  85 evas_shutdown(void)
  86 {
  87    if (--_evas_init_count != 0)
  88      return _evas_init_count;
  89
  90 #ifdef EVAS_FRAME_QUEUING
  91    if (evas_common_frameq_enabled())
  92      {
  93         evas_common_frameq_finish();
  94         evas_common_frameq_destroy();
  95      }
  96 #endif
  97 #ifdef BUILD_ASYNC_EVENTS
  98    _evas_preload_thread_shutdown();
  99 #endif
 100 #ifdef EVAS_CSERVE
 101    if (getenv("EVAS_CSERVE")) evas_cserve_shutdown();
 102 #endif
 103 #ifdef BUILD_ASYNC_EVENTS
 104    evas_async_events_shutdown();
 105 #endif
 106    evas_font_dir_cache_free();
 107    evas_common_shutdown();
 108    evas_module_shutdown();
 109    eina_log_domain_unregister(_evas_log_dom_global);
 110    eina_shutdown();
 111 #ifdef HAVE_EVIL
 112    evil_shutdown();
 113 #endif
 114
 115    return _evas_init_count;
 116 }
 117
 118
 119 /**
 120  * Creates a new empty evas.
 121  *
 122  * Note that before you can use the evas, you will to at a minimum:
 123  * @li Set its render method with @ref evas_output_method_set .
 124  * @li Set its viewport size with @ref evas_output_viewport_set .
 125  * @li Set its size of the canvas with @ref evas_output_size_set .
 126  * @li Ensure that the render engine is given the correct settings
 127  *     with @ref evas_engine_info_set .
 128  *
 129  * This function should only fail if the memory allocation fails
 130  *
 131  * @note this function is very low level. Instead of using it
 132  *       directly, consider using the high level functions in
 133  *       Ecore_Evas such as @c ecore_evas_new(). See
 134  *       http://docs.enlightenment.org/auto/ecore/.
 135  *
 136  * @attention it is recommended that one calls evas_init() before
 137  *       creating new canvas.
 138  *
 139  * @return A new uninitialised Evas canvas on success.  Otherwise, @c
 140  * NULL.
 141  * @ingroup Evas_Canvas
 142  */
 143 EAPI Evas *
 144 evas_new(void)
 145 {
 146    Evas *e;
 147
 148    e = calloc(1, sizeof(Evas));
 149    if (!e) return NULL;
 150
 151    e->magic = MAGIC_EVAS;
 152    e->output.render_method = RENDER_METHOD_INVALID;
 153    e->viewport.w = 1;
 154    e->viewport.h = 1;
 155    e->hinting = EVAS_FONT_HINTING_BYTECODE;
 156    e->name_hash = eina_hash_string_superfast_new(NULL);
 157
 158    eina_array_step_set(&e->delete_objects, 256);
 159    eina_array_step_set(&e->active_objects, 256);
 160    eina_array_step_set(&e->restack_objects, 256);
 161    eina_array_step_set(&e->render_objects, 256);
 162    eina_array_step_set(&e->pending_objects, 256);
 163    eina_array_step_set(&e->obscuring_objects, 256);
 164    eina_array_step_set(&e->temporary_objects, 256);
 165    eina_array_step_set(&e->calculate_objects, 256);
 166    eina_array_step_set(&e->clip_changes, 256);
 167
 168    return e;
 169 }
 170
 171 /**
 172  * Frees the given evas and any objects created on it.
 173  *
 174  * Any objects with 'free' callbacks will have those callbacks called
 175  * in this function.
 176  *
 177  * @param   e The given evas.
 178  *
 179  * @ingroup Evas_Canvas
 180  */
 181 EAPI void
 182 evas_free(Evas *e)
 183 {
 184    Eina_Rectangle *r;
 185    Evas_Layer *lay;
 186    int i;
 187    int del;
 188
 189    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 190    return;
 191    MAGIC_CHECK_END();
 192
 193 #ifdef EVAS_FRAME_QUEUING
 194    evas_common_frameq_flush();
 195 #endif
 196
 197    if (e->walking_list == 0) evas_render_idle_flush(e);
 198
 199    if (e->walking_list > 0) return;
 200    if (!e->callbacks) return;
 201    if (e->callbacks->deletions_waiting) return;
 202
 203    e->callbacks->deletions_waiting = 0;
 204    evas_event_callback_list_post_free(&e->callbacks->callbacks);
 205    if (!e->callbacks->callbacks)
 206      {
 207         free(e->callbacks);
 208         e->callbacks = NULL;
 209      }
 210
 211    _evas_post_event_callback_free(e);
 212
 213    del = 1;
 214    e->walking_list++;
 215    e->cleanup = 1;
 216    while (del)
 217      {
 218         del = 0;
 219         EINA_INLIST_FOREACH(e->layers, lay)
 220           {
 221              Evas_Object *o;
 222
 223              evas_layer_pre_free(lay);
 224
 225              EINA_INLIST_FOREACH(lay->objects, o)
 226                {
 227                   if ((o->callbacks) && (o->callbacks->walking_list))
 228                     {
 229                        /* Defer free */
 230                        e->delete_me = 1;
 231                        e->walking_list--;
 232                        return;
 233                     }
 234                   if (!o->delete_me)
 235                     del = 1;
 236                }
 237           }
 238      }
 239    EINA_INLIST_FOREACH(e->layers, lay)
 240      evas_layer_free_objects(lay);
 241    evas_layer_clean(e);
 242
 243    e->walking_list--;
 244
 245    evas_font_path_clear(e);
 246    e->pointer.object.in = eina_list_free(e->pointer.object.in);
 247
 248    if (e->name_hash) eina_hash_free(e->name_hash);
 249    e->name_hash = NULL;
 250
 251    EINA_LIST_FREE(e->damages, r)
 252      eina_rectangle_free(r);
 253    EINA_LIST_FREE(e->obscures, r)
 254      eina_rectangle_free(r);
 255
 256    evas_fonts_zero_free(e);
 257
 258    evas_event_callback_all_del(e);
 259    evas_event_callback_cleanup(e);
 260
 261    if (e->engine.func)
 262      {
 263         e->engine.func->context_free(e->engine.data.output, e->engine.data.context);
 264         e->engine.func->output_free(e->engine.data.output);
 265         e->engine.func->info_free(e, e->engine.info);
 266      }
 267
 268    for (i = 0; i < e->modifiers.mod.count; i++)
 269      free(e->modifiers.mod.list[i]);
 270    if (e->modifiers.mod.list) free(e->modifiers.mod.list);
 271
 272    for (i = 0; i < e->locks.lock.count; i++)
 273      free(e->locks.lock.list[i]);
 274    if (e->locks.lock.list) free(e->locks.lock.list);
 275
 276    if (e->engine.module) evas_module_unref(e->engine.module);
 277
 278    eina_array_flush(&e->delete_objects);
 279    eina_array_flush(&e->active_objects);
 280    eina_array_flush(&e->restack_objects);
 281    eina_array_flush(&e->render_objects);
 282    eina_array_flush(&e->pending_objects);
 283    eina_array_flush(&e->obscuring_objects);
 284    eina_array_flush(&e->temporary_objects);
 285    eina_array_flush(&e->calculate_objects);
 286    eina_array_flush(&e->clip_changes);
 287
 288    e->magic = 0;
 289    free(e);
 290 }
 291
 292 /**
 293  * Sets the output engine for the given evas.
 294  *
 295  * Once the output engine for an evas is set, any attempt to change it
 296  * will be ignored.  The value for @p render_method can be found using
 297  * @ref evas_render_method_lookup .
 298  *
 299  * @attention it is mandatory that one calls evas_init() before
 300  *       setting the output method.
 301  *
 302  * @param   e             The given evas.
 303  * @param   render_method The numeric engine value to use.
 304  * @ingroup Evas_Output_Method
 305  */
 306 EAPI void
 307 evas_output_method_set(Evas *e, int render_method)
 308 {
 309    Evas_Module *em;
 310
 311    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 312    return;
 313    MAGIC_CHECK_END();
 314
 315    /* if our engine to set it to is invalid - abort */
 316    if (render_method == RENDER_METHOD_INVALID) return;
 317    /* if the engine is already set up - abort */
 318    if (e->output.render_method != RENDER_METHOD_INVALID) return;
 319    /* Request the right engine. */
 320    em = evas_module_engine_get(render_method);
 321    if (!em) return ;
 322    if (em->id_engine != render_method) return;
 323    if (!evas_module_load(em)) return;
 324
 325    /* set the correct render */
 326    e->output.render_method = render_method;
 327    e->engine.func = (em->functions);
 328    evas_module_use(em);
 329    if (e->engine.module) evas_module_unref(e->engine.module);
 330    e->engine.module = em;
 331    evas_module_ref(em);
 332    /* get the engine info struct */
 333    if (e->engine.func->info) e->engine.info = e->engine.func->info(e);
 334    return;
 335 }
 336
 337 /**
 338  * Retrieves the number of the output engine used for the given evas.
 339  * @param   e The given evas.
 340  * @return  The ID number of the output engine being used.  @c 0 is
 341  *          returned if there is an error.
 342  * @ingroup Evas_Output_Method
 343  */
 344 EAPI int
 345 evas_output_method_get(const Evas *e)
 346 {
 347    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 348    return RENDER_METHOD_INVALID;
 349    MAGIC_CHECK_END();
 350
 351    return e->output.render_method;
 352 }
 353
 354 /**
 355  * Retrieves the current render engine info struct from the given evas.
 356  *
 357  * The returned structure is publicly modifiable.  The contents are
 358  * valid until either @ref evas_engine_info_set or @ref evas_render
 359  * are called.
 360  *
 361  * This structure does not need to be freed by the caller.
 362  *
 363  * @param   e The given evas.
 364  * @return  A pointer to the Engine Info structure.  @c NULL is returned if
 365  *          an engine has not yet been assigned.
 366  * @ingroup Evas_Output_Method
 367  */
 368 EAPI Evas_Engine_Info *
 369 evas_engine_info_get(const Evas *e)
 370 {
 371    Evas_Engine_Info *info;
 372
 373    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 374    return NULL;
 375    MAGIC_CHECK_END();
 376
 377    if (!e->engine.info) return NULL;
 378
 379    info = e->engine.info;
 380    ((Evas *)e)->engine.info_magic = info->magic;
 381
 382    return info;
 383 }
 384
 385 /**
 386  * Applies the engine settings for the given evas from the given @c
 387  * Evas_Engine_Info structure.
 388  *
 389  * To get the Evas_Engine_Info structure to use, call @ref
 390  * evas_engine_info_get .  Do not try to obtain a pointer to an
 391  * @c Evas_Engine_Info structure in any other way.
 392  *
 393  * You will need to call this function at least once before you can
 394  * create objects on an evas or render that evas.  Some engines allow
 395  * their settings to be changed more than once.
 396  *
 397  * Once called, the @p info pointer should be considered invalid.
 398  *
 399  * @param   e    The pointer to the Evas Canvas
 400  * @param   info The pointer to the Engine Info to use
 401  * @return  1 if no error occured, 0 otherwise
 402  * @ingroup Evas_Output_Method
 403  */
 404 EAPI int
 405 evas_engine_info_set(Evas *e, Evas_Engine_Info *info)
 406 {
 407    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 408    return 0;
 409    MAGIC_CHECK_END();
 410    if (!info) return 0;
 411    if (info != e->engine.info) return 0;
 412    if (info->magic != e->engine.info_magic) return 0;
 413    return e->engine.func->setup(e, info);
 414 }
 415
 416 /**
 417  * Sets the output size of the render engine of the given evas.
 418  *
 419  * The evas will render to a rectangle of the given size once this
 420  * function is called.  The output size is independent of the viewport
 421  * size.  The viewport will be stretched to fill the given rectangle.
 422  *
 423  * The units used for @p w and @p h depend on the engine used by the
 424  * evas.
 425  *
 426  * @param   e The given evas.
 427  * @param   w The width in output units, usually pixels.
 428  * @param   h The height in output units, usually pixels.
 429  * @ingroup Evas_Output_Size
 430  */
 431 EAPI void
 432 evas_output_size_set(Evas *e, int w, int h)
 433 {
 434    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 435    return;
 436    MAGIC_CHECK_END();
 437
 438    if ((w == e->output.w) && (h == e->output.h)) return;
 439    if (w < 1) w = 1;
 440    if (h < 1) h = 1;
 441
 442 #ifdef EVAS_FRAME_QUEUING
 443    evas_common_frameq_flush();
 444 #endif
 445
 446    e->output.w = w;
 447    e->output.h = h;
 448    e->output.changed = 1;
 449    e->output_validity++;
 450    e->changed = 1;
 451    evas_render_invalidate(e);
 452 }
 453
 454 /**
 455  * Retrieve the output size of the render engine of the given evas.
 456  *
 457  * The output size is given in whatever the output units are for the
 458  * engine.
 459  *
 460  * If either @p w or @p h is @c NULL, then it is ignored.  If @p e is
 461  * invalid, the returned results are undefined.
 462  *
 463  * @param   e The given evas.
 464  * @param   w The pointer to an integer to store the width in.
 465  * @param   h The pointer to an integer to store the height in.
 466  * @ingroup Evas_Output_Size
 467  */
 468 EAPI void
 469 evas_output_size_get(const Evas *e, int *w, int *h)
 470 {
 471    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 472    if (w) *w = 0;
 473    if (h) *h = 0;
 474    return;
 475    MAGIC_CHECK_END();
 476
 477    if (w) *w = e->output.w;
 478    if (h) *h = e->output.h;
 479 }
 480
 481 /**
 482  * Sets the output viewport of the given evas in evas units.
 483  *
 484  * The output viewport is the area of the evas that will be visible to
 485  * the viewer.  The viewport will be stretched to fit the output
 486  * target of the evas when rendering is performed.
 487  *
 488  * @note The coordinate values do not have to map 1-to-1 with the output
 489  *       target.  However, it is generally advised that it is done for ease
 490  *       of use.
 491  *
 492  * @param   e The given evas.
 493  * @param   x The top-left corner x value of the viewport.
 494  * @param   y The top-left corner y value of the viewport.
 495  * @param   w The width of the viewport.  Must be greater than 0.
 496  * @param   h The height of the viewport.  Must be greater than 0.
 497  * @ingroup Evas_Output_Size
 498  */
 499 EAPI void
 500 evas_output_viewport_set(Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h)
 501 {
 502    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 503    return;
 504    MAGIC_CHECK_END();
 505
 506    if ((x == e->viewport.x) && (y == e->viewport.y) &&
 507        (w == e->viewport.w) && (h == e->viewport.h)) return;
 508    if (w <= 0) return;
 509    if (h <= 0) return;
 510    if ((x != 0) || (y != 0))
 511      {
 512         ERR("Compat error. viewport x,y != 0,0 not supported");
 513         x = 0;
 514         y = 0;
 515      }
 516    e->viewport.x = x;
 517    e->viewport.y = y;
 518    e->viewport.w = w;
 519    e->viewport.h = h;
 520    e->viewport.changed = 1;
 521    e->output_validity++;
 522    e->changed = 1;
 523 }
 524
 525 /**
 526  * Get the render engine's output viewport co-ordinates in canvas units.
 527  * @param e The pointer to the Evas Canvas
 528  * @param x The pointer to a x variable to be filled in
 529  * @param y The pointer to a y variable to be filled in
 530  * @param w The pointer to a width variable to be filled in
 531  * @param h The pointer to a height variable to be filled in
 532  * @ingroup Evas_Output_Size
 533  *
 534  * Calling this function writes the current canvas output viewport
 535  * size and location values into the variables pointed to by @p x, @p
 536  * y, @p w and @p h.  On success the variables have the output
 537  * location and size values written to them in canvas units. Any of @p
 538  * x, @p y, @p w or @p h that are NULL will not be written to. If @p e
 539  * is invalid, the results are undefined.
 540  *
 541  * Example:
 542  * @code
 543  * extern Evas *evas;
 544  * Evas_Coord x, y, width, height;
 545  *
 546  * evas_output_viewport_get(evas, &x, &y, &w, &h);
 547  * @endcode
 548  */
 549 EAPI void
 550 evas_output_viewport_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h)
 551 {
 552    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 553    if (x) *x = 0;
 554    if (y) *y = 0;
 555    if (w) *w = 0;
 556    if (h) *h = 0;
 557    return;
 558    MAGIC_CHECK_END();
 559
 560    if (x) *x = e->viewport.x;
 561    if (y) *y = e->viewport.y;
 562    if (w) *w = e->viewport.w;
 563    if (h) *h = e->viewport.h;
 564 }
 565
 566 /**
 567  * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
 568  *
 569  * @param e The pointer to the Evas Canvas
 570  * @param x The screen/output x co-ordinate
 571  * @return The screen co-ordinate translated to canvas unit co-ordinates
 572  * @ingroup Evas_Coord_Mapping_Group
 573  *
 574  * This function takes in a horizontal co-ordinate as the @p x
 575  * parameter and converts it into canvas units, accounting for output
 576  * size, viewport size and location, returning it as the function
 577  * return value. If @p e is invalid, the results are undefined.
 578  *
 579  * Example:
 580  * @code
 581  * extern Evas *evas;
 582  * extern int screen_x;
 583  * Evas_Coord canvas_x;
 584  *
 585  * canvas_x = evas_coord_screen_x_to_world(evas, screen_x);
 586  * @endcode
 587  */
 588 EAPI Evas_Coord
 589 evas_coord_screen_x_to_world(const Evas *e, int x)
 590 {
 591    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 592    return 0;
 593    MAGIC_CHECK_END();
 594    if (e->output.w == e->viewport.w) return e->viewport.x + x;
 595    return (long long)e->viewport.x + (((long long)x * (long long)e->viewport.w) / (long long)e->output.w);
 596 }
 597
 598 /**
 599  * Convert/scale an ouput screen co-ordinate into canvas co-ordinates
 600  *
 601  * @param e The pointer to the Evas Canvas
 602  * @param y The screen/output y co-ordinate
 603  * @return The screen co-ordinate translated to canvas unit co-ordinates
 604  * @ingroup Evas_Coord_Mapping_Group
 605  *
 606  * This function takes in a vertical co-ordinate as the @p y parameter
 607  * and converts it into canvas units, accounting for output size,
 608  * viewport size and location, returning it as the function return
 609  * value. If @p e is invalid, the results are undefined.
 610  *
 611  * Example:
 612  * @code
 613  * extern Evas *evas;
 614  * extern int screen_y;
 615  * Evas_Coord canvas_y;
 616  *
 617  * canvas_y = evas_coord_screen_y_to_world(evas, screen_y);
 618  * @endcode
 619  */
 620 EAPI Evas_Coord
 621 evas_coord_screen_y_to_world(const Evas *e, int y)
 622 {
 623    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 624    return 0;
 625    MAGIC_CHECK_END();
 626    if (e->output.h == e->viewport.h) return e->viewport.y + y;
 627    return (long long)e->viewport.y + (((long long)y * (long long)e->viewport.h) / (long long)e->output.h);
 628 }
 629
 630 /**
 631  * Convert/scale a canvas co-ordinate into output screen co-ordinates
 632  *
 633  * @param e The pointer to the Evas Canvas
 634  * @param x The canvas x co-ordinate
 635  * @return The output/screen co-ordinate translated to output co-ordinates
 636  * @ingroup Evas_Coord_Mapping_Group
 637  *
 638  * This function takes in a horizontal co-ordinate as the @p x
 639  * parameter and converts it into output units, accounting for output
 640  * size, viewport size and location, returning it as the function
 641  * return value. If @p e is invalid, the results are undefined.
 642  *
 643  * Example:
 644  * @code
 645  * extern Evas *evas;
 646  * int screen_x;
 647  * extern Evas_Coord canvas_x;
 648  *
 649  * screen_x = evas_coord_world_x_to_screen(evas, canvas_x);
 650  * @endcode
 651  */
 652 EAPI int
 653 evas_coord_world_x_to_screen(const Evas *e, Evas_Coord x)
 654 {
 655    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 656    return 0;
 657    MAGIC_CHECK_END();
 658    if (e->output.w == e->viewport.w) return x - e->viewport.x;
 659    return (int)((((long long)x - (long long)e->viewport.x) * (long long)e->output.w) /  (long long)e->viewport.w);
 660 }
 661
 662 /**
 663  * Convert/scale a canvas co-ordinate into output screen co-ordinates
 664  *
 665  * @param e The pointer to the Evas Canvas
 666  * @param y The canvas y co-ordinate
 667  * @return The output/screen co-ordinate translated to output co-ordinates
 668  * @ingroup Evas_Coord_Mapping_Group
 669  *
 670  * This function takes in a vertical co-ordinate as the @p x parameter
 671  * and converts it into output units, accounting for output size,
 672  * viewport size and location, returning it as the function return
 673  * value. If @p e is invalid, the results are undefined.
 674  *
 675  * Example:
 676  * @code
 677  * extern Evas *evas;
 678  * int screen_y;
 679  * extern Evas_Coord canvas_y;
 680  *
 681  * screen_y = evas_coord_world_y_to_screen(evas, canvas_y);
 682  * @endcode
 683  */
 684 EAPI int
 685 evas_coord_world_y_to_screen(const Evas *e, Evas_Coord y)
 686 {
 687    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 688    return 0;
 689    MAGIC_CHECK_END();
 690    if (e->output.h == e->viewport.h) return y - e->viewport.y;
 691    return (int)((((long long)y - (long long)e->viewport.y) * (long long)e->output.h) /  (long long)e->viewport.h);
 692 }
 693
 694 /**
 695  * Look up a numeric ID from a string name of a rendering engine.
 696  *
 697  * @param name The string name of an engine
 698  * @return A numeric (opaque) ID for the rendering engine
 699  * @ingroup Evas_Output_Method
 700  *
 701  * This function looks up a numeric return value for the named engine
 702  * in the string @p name. This is a normal C string, NUL byte
 703  * terminated. The name is case sensitive. If the rendering engine is
 704  * available, a numeric ID for that engine is returned that is not
 705  * 0. If the engine is not available, 0 is returned, indicating an
 706  * invalid engine.
 707  *
 708  * The programmer should NEVER rely on the numeric ID of an engine
 709  * unless it is returned by this function. Programs should NOT be
 710  * written accessing render method ID's directly, without first
 711  * obtaining it from this function.
 712  *
 713  * @attention it is mandatory that one calls evas_init() before
 714  *       looking up the render method.
 715  *
 716  * Example:
 717  * @code
 718  * int engine_id;
 719  * Evas *evas;
 720  *
 721  * evas_init();
 722  *
 723  * evas = evas_new();
 724  * if (!evas)
 725  *   {
 726  *     fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n");
 727  *     exit(-1);
 728  *   }
 729  * engine_id = evas_render_method_lookup("software_x11");
 730  * if (!engine_id)
 731  *   {
 732  *     fprintf(stderr, "ERROR: Requested rendering engine is absent.\n");
 733  *     exit(-1);
 734  *   }
 735  * evas_output_method_set(evas, engine_id);
 736  * @endcode
 737  */
 738 EAPI int
 739 evas_render_method_lookup(const char *name)
 740 {
 741    Evas_Module *em;
 742
 743    if (!name) return RENDER_METHOD_INVALID;
 744    /* search on the engines list for the name */
 745    em = evas_module_find_type(EVAS_MODULE_TYPE_ENGINE, name);
 746    if (!em) return RENDER_METHOD_INVALID;
 747
 748    return em->id_engine;
 749 }
 750
 751 /**
 752  * List all the rendering engines compiled into the copy of the Evas library
 753  *
 754  * @return A linked list whose data members are C strings of engine names
 755  * @ingroup Evas_Output_Method
 756  *
 757  * Calling this will return a handle (pointer) to an Evas linked
 758  * list. Each node in the linked list will have the data pointer be a
 759  * (char *) pointer to the string name of the rendering engine
 760  * available. The strings should never be modified, neither should the
 761  * list be modified. This list should be cleaned up as soon as the
 762  * program no longer needs it using evas_render_method_list_free(). If
 763  * no engines are available from Evas, NULL will be returned.
 764  *
 765  * Example:
 766  * @code
 767  * Eina_List *engine_list, *l;
 768  * char *engine_name;
 769  *
 770  * engine_list = evas_render_method_list();
 771  * if (!engine_list)
 772  *   {
 773  *     fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
 774  *     exit(-1);
 775  *   }
 776  * printf("Availible Evas Engines:\n");
 777  * EINA_LIST_FOREACH(engine_list, l, engine_name)
 778  *     printf("%s\n", engine_name);
 779  * evas_render_method_list_free(engine_list);
 780  * @endcode
 781  */
 782 EAPI Eina_List *
 783 evas_render_method_list(void)
 784 {
 785    Eina_List *methods = NULL;
 786
 787    /* FIXME: get from modules - this is currently coded-in */
 788 #ifdef BUILD_ENGINE_SOFTWARE_GDI
 789    methods = eina_list_append(methods, "software_gdi");
 790 #endif
 791 #ifdef BUILD_ENGINE_SOFTWARE_DDRAW
 792    methods = eina_list_append(methods, "software_ddraw");
 793 #endif
 794 #ifdef BUILD_ENGINE_SOFTWARE_16_DDRAW
 795    methods = eina_list_append(methods, "software_16_ddraw");
 796 #endif
 797 #ifdef BUILD_ENGINE_DIRECT3D
 798    methods = eina_list_append(methods, "direct3d");
 799 #endif
 800 #ifdef BUILD_ENGINE_SOFTWARE_16_WINCE
 801    methods = eina_list_append(methods, "software_16_wince");
 802 #endif
 803 #ifdef BUILD_ENGINE_SOFTWARE_X11
 804    methods = eina_list_append(methods, "software_x11");
 805 #endif
 806 #ifdef BUILD_ENGINE_XRENDER_X11
 807    methods = eina_list_append(methods, "xrender_x11");
 808 #endif
 809 #ifdef BUILD_ENGINE_XRENDER_XCB
 810    methods = eina_list_append(methods, "xrender_xcb");
 811 #endif
 812 #ifdef BUILD_ENGINE_SOFTWARE_16_X11
 813    methods = eina_list_append(methods, "software_16_x11");
 814 #endif
 815 #ifdef BUILD_ENGINE_GL_X11
 816    methods = eina_list_append(methods, "gl_x11");
 817 #endif
 818 #ifdef BUILD_ENGINE_GL_GLEW
 819    methods = eina_list_append(methods, "gl_glew");
 820 #endif
 821 #ifdef BUILD_ENGINE_CAIRO_X11
 822    methods = eina_list_append(methods, "cairo_x11");
 823 #endif
 824 #ifdef BUILD_ENGINE_DIRECTFB
 825    methods = eina_list_append(methods, "directfb");
 826 #endif
 827 #ifdef BUILD_ENGINE_FB
 828    methods = eina_list_append(methods, "fb");
 829 #endif
 830 #ifdef BUILD_ENGINE_BUFFER
 831    methods = eina_list_append(methods, "buffer");
 832 #endif
 833 #ifdef BUILD_ENGINE_SOFTWARE_WIN32_GDI
 834    methods = eina_list_append(methods, "software_win32_gdi");
 835 #endif
 836 #ifdef BUILD_ENGINE_SOFTWARE_QTOPIA
 837    methods = eina_list_append(methods, "software_qtopia");
 838 #endif
 839 #ifdef BUILD_ENGINE_SOFTWARE_SDL
 840    methods = eina_list_append(methods, "software_sdl");
 841 #endif
 842
 843    return methods;
 844 }
 845
 846 /**
 847  * This function should be called to free a list of engine names
 848  *
 849  * @param list The Eina_List base pointer for the engine list to be freed
 850  * @ingroup Evas_Output_Method
 851  *
 852  * When this function is called it will free the engine list passed in
 853  * as @p list. The list should only be a list of engines generated by
 854  * calling evas_render_method_list(). If @p list is NULL, nothing will
 855  * happen.
 856  *
 857  * Example:
 858  * @code
 859  * Eina_List *engine_list, *l;
 860  * char *engine_name;
 861  *
 862  * engine_list = evas_render_method_list();
 863  * if (!engine_list)
 864  *   {
 865  *     fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n");
 866  *     exit(-1);
 867  *   }
 868  * printf("Availible Evas Engines:\n");
 869  * EINA_LIST_FOREACH(engine_list, l, engine_name)
 870  *     printf("%s\n", engine_name);
 871  * evas_render_method_list_free(engine_list);
 872  * @endcode
 873  */
 874 EAPI void
 875 evas_render_method_list_free(Eina_List *list)
 876 {
 877    eina_list_free(list);
 878 }
 879
 880 /**
 881  * This function returns the current known pointer co-ordinates
 882  *
 883  * @param e The pointer to the Evas Canvas
 884  * @param x The pointer to an integer to be filled in
 885  * @param y The pointer to an integer to be filled in
 886  * @ingroup Evas_Pointer_Group
 887  *
 888  * This function returns the current known screen/output co-ordinates
 889  * of the mouse pointer and sets the contents of the integers pointed
 890  * to by @p x and @p y to contain these co-ordinates. If @p e is not a
 891  * valid canvas the results of this function are undefined.
 892  *
 893  * Example:
 894  * @code
 895  * extern Evas *evas;
 896  * int mouse_x, mouse_y;
 897  *
 898  * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
 899  * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y);
 900  * @endcode
 901  */
 902 EAPI void
 903 evas_pointer_output_xy_get(const Evas *e, int *x, int *y)
 904 {
 905    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 906    if (x) *x = 0;
 907    if (y) *y = 0;
 908    return;
 909    MAGIC_CHECK_END();
 910    if (x) *x = e->pointer.x;
 911    if (y) *y = e->pointer.y;
 912 }
 913
 914 /**
 915  * This function returns the current known pointer co-ordinates
 916  *
 917  * @param e The pointer to the Evas Canvas
 918  * @param x The pointer to a Evas_Coord to be filled in
 919  * @param y The pointer to a Evas_Coord to be filled in
 920  * @ingroup Evas_Pointer_Group
 921  *
 922  * This function returns the current known canvas unit co-ordinates of
 923  * the mouse pointer and sets the contents of the Evas_Coords pointed
 924  * to by @p x and @p y to contain these co-ordinates. If @p e is not a
 925  * valid canvas the results of this function are undefined.
 926  *
 927  * Example:
 928  * @code
 929  * extern Evas *evas;
 930  * Evas_Coord mouse_x, mouse_y;
 931  *
 932  * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y);
 933  * printf("Mouse is at canvas position %f, %f\n", mouse_x, mouse_y);
 934  * @endcode
 935  */
 936 EAPI void
 937 evas_pointer_canvas_xy_get(const Evas *e, Evas_Coord *x, Evas_Coord *y)
 938 {
 939    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 940    if (x) *x = 0;
 941    if (y) *y = 0;
 942    return;
 943    MAGIC_CHECK_END();
 944    if (x) *x = e->pointer.x;
 945    if (y) *y = e->pointer.y;
 946 }
 947
 948 /**
 949  * Returns a bitmask with the mouse buttons currently pressed, set to 1
 950  *
 951  * @param e The pointer to the Evas Canvas
 952  * @return A bitmask of the currently depressed buttons on the cavas
 953  * @ingroup Evas_Pointer_Group
 954  *
 955  * Calling this function will return a 32-bit integer with the
 956  * appropriate bits set to 1 that correspond to a mouse button being
 957  * depressed. This limits Evas to a mouse devices with a maximum of 32
 958  * buttons, but that is generally in excess of any host system's
 959  * pointing device abilities.
 960  *
 961  * A canvas by default begins with no mouse buttons being pressed and
 962  * only calls to evas_event_feed_mouse_down(),
 963  * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and
 964  * evas_event_feed_mouse_up_data() will alter that.
 965  *
 966  * The least significant bit corresponds to the first mouse button
 967  * (button 1) and the most significant bit corresponds to the last
 968  * mouse button (button 32).
 969  *
 970  * If @p e is not a valid canvas, the return value is undefined.
 971  *
 972  * Example:
 973  * @code
 974  * extern Evas *evas;
 975  * int button_mask, i;
 976  *
 977  * button_mask = evas_pointer_button_down_mask_get(evas);
 978  * printf("Buttons currently pressed:\n");
 979  * for (i = 0; i < 32; i++)
 980  *   {
 981  *     if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1);
 982  *   }
 983  * @endcode
 984  */
 985 EAPI int
 986 evas_pointer_button_down_mask_get(const Evas *e)
 987 {
 988    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
 989    return 0;
 990    MAGIC_CHECK_END();
 991    return (int)e->pointer.button;
 992 }
 993
 994 /**
 995  * Returns whether the mouse pointer is logically inside the canvas
 996  *
 997  * @param e The pointer to the Evas Canvas
 998  * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise
 999  * @ingroup Evas_Pointer_Group
1000  *
1001  * When this function is called it will return a value of either 0 or
1002  * 1, depending on if evas_event_feed_mouse_in(),
1003  * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(),
1004  * evas_event_feed_mouse_out_data() have been called to feed in a
1005  * mouse enter event into the canvas.
1006  *
1007  * A return value of 1 indicates the mouse is logically inside the
1008  * canvas, and 0 implies it is logically outside the canvas.
1009  *
1010  * A canvas begins with the mouse being assumed outside (0).
1011  *
1012  * If @p e is not a valid canvas, the return value is undefined.
1013  *
1014  * Example:
1015  * @code
1016  * extern Evas *evas;
1017  *
1018  * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n");
1019  * else printf("Mouse is out!\n");
1020  * @endcode
1021  */
1022 EAPI Eina_Bool
1023 evas_pointer_inside_get(const Evas *e)
1024 {
1025    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
1026    return 0;
1027    MAGIC_CHECK_END();
1028    return (int)e->pointer.inside;
1029 }
1030
1031 /**
1032  * Attaches a specific pointer to the evas for fetching later
1033  *
1034  * @param e The canvas to attach the pointer to
1035  * @param data The pointer to attach
1036  * @ingroup Evas_Canvas
1037  */
1038 EAPI void
1039 evas_data_attach_set(Evas *e, void *data)
1040 {
1041    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
1042    return;
1043    MAGIC_CHECK_END();
1044    e->attach_data = data;
1045 }
1046
1047 /**
1048  * Returns the pointer attached by evas_data_attach_set()
1049  *
1050  * @param e The canvas to attach the pointer to
1051  * @return The pointer attached
1052  * @ingroup Evas_Canvas
1053  */
1054 EAPI void *
1055 evas_data_attach_get(const Evas *e)
1056 {
1057    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
1058    return NULL;
1059    MAGIC_CHECK_END();
1060    return e->attach_data;
1061 }
1062
1063 /**
1064  * Inform to the evas that it got the focus.
1065  *
1066  * @param e The evas to change information.
1067  * @ingroup Evas_Canvas
1068  */
1069 EAPI void
1070 evas_focus_in(Evas *e)
1071 {
1072    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
1073    return;
1074    MAGIC_CHECK_END();
1075    if (e->focus) return;
1076    e->focus = 1;
1077    evas_event_callback_call(e, EVAS_CALLBACK_CANVAS_FOCUS_IN, NULL);
1078 }
1079
1080 /**
1081  * Inform to the evas that it lost the focus.
1082  *
1083  * @param e The evas to change information.
1084  * @ingroup Evas_Canvas
1085  */
1086 EAPI void
1087 evas_focus_out(Evas *e)
1088 {
1089    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
1090    return;
1091    MAGIC_CHECK_END();
1092    if (!e->focus) return;
1093    e->focus = 0;
1094    evas_event_callback_call(e, EVAS_CALLBACK_CANVAS_FOCUS_OUT, NULL);
1095 }
1096
1097 /**
1098  * Get the focus state known by the given evas
1099  *
1100  * @param e The evas to query information.
1101  * @ingroup Evas_Canvas
1102  */
1103 EAPI Eina_Bool
1104 evas_focus_state_get(const Evas *e)
1105 {
1106    MAGIC_CHECK(e, Evas, MAGIC_EVAS);
1107    return 0;
1108    MAGIC_CHECK_END();
1109    return e->focus;
1110 }
1111
1112 void
1113 _evas_walk(Evas *e)
1114 {
1115    e->walking_list++;
1116 }
1117
1118 void
1119 _evas_unwalk(Evas *e)
1120 {
1121    e->walking_list--;
1122    if ((e->walking_list == 0) && (e->delete_me)) evas_free(e);
1123 }
1124
1125 /**
1126  * Converts the given error code into a string describing it in english.
1127  * @param error the error code.
1128  * @return Always return a valid string. If given @p error is not
1129  *         supported "Unknown error" is returned.
1130  * @ingroup Evas_Utils
1131  */
1132 EAPI const char *
1133 evas_load_error_str(int error)
1134 {
1135    switch (error)
1136      {
1137       case EVAS_LOAD_ERROR_NONE:
1138          return "No error on load";
1139       case EVAS_LOAD_ERROR_GENERIC:
1140          return "A non-specific error occured";
1141       case EVAS_LOAD_ERROR_DOES_NOT_EXIST:
1142          return "File (or file path) does not exist";
1143       case EVAS_LOAD_ERROR_PERMISSION_DENIED:
1144          return "Permission deinied to an existing file (or path)";
1145       case EVAS_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED:
1146          return "Allocation of resources failure prevented load";
1147       case EVAS_LOAD_ERROR_CORRUPT_FILE:
1148          return "File corrupt (but was detected as a known format)";
1149       case EVAS_LOAD_ERROR_UNKNOWN_FORMAT:
1150          return "File is not a known format";
1151       default:
1152          return "Unknown error";
1153      }
1154 }