src/lib/elm_image.h

   1 /**
   2  * @defgroup Elm_Image Image
   3  * @ingroup elm_widget_group
   4  *
   5  * @image html image_inheritance_tree.png
   6  * @image latex image_inheritance_tree.eps
   7  *
   8  * It allows one to load and display an @b image
   9  * file on it, be it from a disk file or from a memory
  10  * region. Exceptionally, one may also load an Edje group as the
  11  * contents of the image. In this case, though, most of the functions
  12  * of the image API will act as a no-op.
  13  *
  14  * One can tune various properties of the image, like:
  15  * - pre-scaling,
  16  * - smooth scaling,
  17  * - orientation,
  18  * - aspect ratio during resizes, etc.
  19  *
  20  * An image object may also be made valid source and destination for
  21  * drag and drop actions, through the elm_image_editable_set() call.
  22  *
  23  * If the image source size is bigger than maximum texture size of the GPU (or also of
  24  * the software rendering code too), evas can't render it because of such a limitation.
  25  * If evas just magically always downscales on load if it's too big, then the user has a new bug:
  26  * "the image is blurry". Potentially any image can cause issue.
  27  * What if the image is too big to allocate memory for it?
  28  * A 30000x30000 image will need just a bit under 4GB of RAM to store it.
  29  * Texture size limitations are something every game developer has to deal with game engines,
  30  * OpenGL, D3D etc. You can get the maximum image size evas can possibly handle by
  31  * the calling evas_image_max_size_get() function. If the image size is bigger than this,
  32  * you can try using load options to pre-scale down on load to lower quality.
  33  * So use the elm_image_prescale_set() function to scale the image down.
  34  * Another option is to use the Photocam widget. Photocam solves this issue
  35  * by loading the prices as needed asynchronously in tiles and automatically using pre-scaling as well
  36  * So use Photocam if you expect to load very large images.
  37  *
  38  * Signals that you can add callbacks for are:
  39  *
  40  * @li @c "drop" - This is called when a user has dropped an image
  41  *                 typed object onto the object in question -- the
  42  *                 event info argument is the path to that image file
  43  * @li @c "clicked" - This is called when a user has clicked the image
  44  * @li @c "download,start" - This is called when the remote image file download
  45  *                           has started.
  46  * @li @c "download,progress" - This is continuously called before the remote
  47  *                              image file download has done. The event info
  48  *                              data is of type Elm_Image_Progress.
  49  * @li @c "download,done" - This is called when the download has completed.
  50  * @li @c "download,error"- This is called when the download has failed.
  51  * @li @c "load,open" - Triggered when the file has been opened, if async
  52  *                      open is enabled (image size is known). (since 1.19)
  53  * @li @c "load,ready" - Triggered when the image file is ready for display,
  54  *                       if preload is enabled. (since 1.19)
  55  * @li @c "load,error" - Triggered if an async I/O or decoding error occurred,
  56  *                       if async open or preload is enabled (since 1.19)
  57  * @li @c "load,cancel" - Triggered whenener async I/O was cancelled. (since 1.19)
  58  *
  59  * An example of usage for this API follows:
  60  * @li @ref tutorial_image
  61  */
  62
  63
  64 /**
  65  * @addtogroup Elm_Image
  66  * @{
  67  */
  68
  69 #include <elm_image_common.h>
  70 #ifdef EFL_EO_API_SUPPORT
  71 #include <elm_image_eo.h>
  72 #endif
  73 #ifndef EFL_NOLEGACY_API_SUPPORT
  74 #include <elm_image_legacy.h>
  75 #endif
  76
  77 /**
  78  * @}
  79  */