efl/src/lib/efl/interfaces/efl_gfx_image.eo

import efl_gfx_types;
import eina_types;

enum @beta Efl.Gfx.Image_Content_Hint
{
   [[How an image's data is to be treated by EFL, for optimization.]]
   none = 0,    [[No hint on the content (default).]]
   dynamic = 1, [[The content will change over time.]]
   static = 2   [[The content won't change over time.]]
}

enum @beta Efl.Gfx.Image_Scale_Hint
{
  /* FIXME: Legacy is in Emile, where it does not belong. */
  [[How an image's data is to be treated by EFL, with regard to scaling cache.]]
  none = 0,    [[No hint on the scaling (default).]]
  dynamic = 1, [[Image will be re-scaled over time, thus turning scaling cache OFF for its data.]]
  static = 2   [[Image will not be re-scaled over time, thus turning scaling cache ON for its data.]]
}

enum @beta Efl.Gfx.Image_Scale_Type
{
   [[Enumeration that defines scale types of an image.]]
   none,        [[Use the image's natural size.]]
   fill,        [[Scale the image so that it matches
                  the object's area exactly.
                  The image's aspect ratio might be changed.]]
   fit,         [[Scale the image
                  so that it fits completely inside the object's area
                  while maintaining the aspect ratio.
                  At least one of the dimensions of the image
                  will be equal to the corresponding dimension
                  of the object.]]
   fit_width,   [[Scale the image
                  so that it covers the entire object area horizontally
                  while maintaining the aspect ratio.
                  The image may become taller than the object.]]
   fit_height,  [[Scale the image
                  so that it covers the entire object area vertically
                  while maintaining the aspect ratio.
                  The image may become wider than the object.]]
   expand,      [[Scale the image
                  so that it covers the entire object area on one axis
                  while maintaining the aspect ratio, preferring whichever
                  axis is largest.
                  The image may become larger than the object.]]
   tile,        [[Tile image at its original size.]]
}

struct Efl.Gfx.Image_Stretch_Region
{
   [[This struct holds the description of a stretchable region in one dimension (vertical or horizontal).
   Used when scaling an image.

     $offset + $length should be smaller than image size in that dimension.
   ]]
   offset: uint; [[First pixel of the stretchable region, starting at 0.]]
   length: uint; [[Length of the stretchable region in pixels.]]
}

interface @beta Efl.Gfx.Image
{
   [[Common APIs for all 2D images that can be rendered on the canvas.]]

   methods {
      @property smooth_scale {
         [[Whether to use high-quality image scaling algorithm for this image.

           When enabled, a higher quality image scaling algorithm is used
           when scaling images to sizes other than the source image's
           original one. This gives better results but is more
           computationally expensive.

           $true by default
         ]]
         set {}
         get {}
         values {
            smooth_scale: bool; [[Whether to use smooth scale or not.]]
         }
      }
      @property scale_type {
         [[Control how the image is scaled.]]
         values {
            scale_type: Efl.Gfx.Image_Scale_Type; [[Image scale type]]
         }
      }
      @property can_upscale {
         [[If $true, the image may be scaled to a larger size. If $false,
           the image will never be resized larger than its native size.
           This is set to $true by default.
         ]]
         values {
            upscale: bool; [[Allow image upscaling]]
         }
      }
      @property can_downscale {
         [[If $true, the image may be scaled to a smaller size. If $false,
           the image will never be resized smaller than its native size.
           This is set to $true by default.
         ]]
         values {
            downscale: bool; [[Allow image downscaling]]
         }
      }
      @property ratio {
         [[The native width/height ratio of the image.]]
         get {
            [[Returns 1.0 if not applicable (eg. height = 0).]]
         }
         values {
            ratio: double; [[The image's ratio.]]
         }
      }
      @property content_region {
         [[Return the relative area enclosed inside the image where content is expected.

           We do expect content to be inside the limit defined by the border or inside the
           stretch region. If a stretch region is provided, the content region will encompass the
           non strechable area that are surrounded by stretchable area. If no border and no
           stretch region is set, they are assumed to be zero and the full object geometry is
           where content can be layout on top. The area size change with the object size.

           The geometry of the area is expressed relative to the geometry of the object.
         ]]
         get { }
         values {
            region: Eina.Rect; [[A rectangle inside the object boundary that where content is expected.]]
         }
      }
      @property border {
         [[Dimensions of this image's border, a region that does not scale
           with the center area.

           When EFL renders an image, its source may be scaled to fit
           the size of the object. This function sets an area from
           the borders of the image inwards which is not to be scaled.
           This function is useful for making frames and for widget
           theming, where, for example, buttons may be of varying
           sizes, but their border size must remain constant.

           The units used for $l, $r, $t and $b are canvas units (pixels).

           Note: The border region itself may be scaled by the
           @.border_scale.set function.

           Note: By default, image objects have no borders set, i.e.
           $l, $r, $t and $b start as 0.

           Note: Similar to the concepts of 9-patch images or cap insets.
         ]]
         set {}
         get {}
         values {
            l: int; [[The border's left width.]]
            r: int; [[The border's right width.]]
            t: int; [[The border's top height.]]
            b: int; [[The border's bottom height.]]
         }
      }
      @property border_scale {
         [[Scaling factor applied to the image borders.

           This value multiplies the size of the @.border when scaling an
           object.

           Default value is 1.0 (no scaling).
         ]]
         set {}
         get {}
         values {
            scale: double; [[The scale factor.]]
         }
      }
      @property border_center_fill {
         [[Specifies how the center part of the object (not the borders)
           should be drawn when EFL is rendering it.

           This function sets how the center part of the image object's
           source image is to be drawn, which must be one of the values
           in @Efl.Gfx.Border_Fill_Mode. By center we mean the complementary
           part of that defined by @.border.set. This is very useful for
           making frames and decorations. You would most probably also be
           using a filled image (as in @Efl.Gfx.Fill.fill_auto) to use as a frame.

           The default value is @Efl.Gfx.Border_Fill_Mode.default, i.e. render
           and scale the center area, respecting its transparency.
         ]]
         set {}
         get {}
         values {
            fill: Efl.Gfx.Border_Fill_Mode; [[Fill mode of the center region.]]
         }
      }
      @property stretch_region {
         [[This property defines the stretchable pixels region of an image.

           When the regions are set by the user, the method will walk the iterators
           once and then destroy them. When the regions are retrieved by the user,
           it is his responsibility to destroy the iterators.. It will remember the
           information for the lifetime of the object. It will ignore all value
           of @.border, @.border_scale and @.border_center_fill . To reset the object
           you can just pass $null to both horizontal and vertical at the same
           time.
         ]]
         set {
           return: Eina.Error; [[return an error code if the stretch_region provided are incorrect.]]
         }
         get {}
         values {
            horizontal: iterator<ptr(Efl.Gfx.Image_Stretch_Region)>; [[Representation of areas that are stretchable in
                                                                       the image horizontal space.]]
            vertical: iterator<ptr(Efl.Gfx.Image_Stretch_Region)>; [[Representation of areas that are stretchable in
                                                                     the image vertical space.]]
         }
      }
      @property image_size {
         [[This represents the size of the original image in pixels.

           This may be different from the actual geometry on screen or even
           the size of the loaded pixel buffer. This is the size of the image
           as stored in the original file.

           This is a read-only property, and may return 0x0.
         ]]
         get {}
         values {
            size: Eina.Size2D; [[The size in pixels.]]
         }
      }

      /* Note: those are obscure features of evas image. Expose in Efl.Gfx.Image? */
      @property content_hint {
         [[Content hint setting for the image. These hints might be used by EFL
           to enable optimizations.

           For example, if you're on the GL engine and your driver implementation
           supports it, setting this hint to @Efl.Gfx.Image_Content_Hint.dynamic
           will make it need zero copies at texture upload time, which is an
           "expensive" operation.
         ]]
         set {
         }
         get {
         }
         values {
            hint: Efl.Gfx.Image_Content_Hint; [[Dynamic or static content hint.]]
         }
      }
      @property scale_hint {
         [[The scale hint of a given image of the canvas.

           The scale hint affects how Evas is to cache
           scaled versions of its original source image.
         ]]
         set {
         }
         get {
         }
         values {
            hint: Efl.Gfx.Image_Scale_Hint; [[Scalable or static size hint,
                                          see @Efl.Gfx.Image_Scale_Hint]]
         }
      }
      @property image_load_error {
         [[The (last) file loading error for a given object.]]
         get {
         }
         values {
            error: Eina.Error; [[The load error code.]]
         }
      }
   }
   events {
      image,preload: void; [[Image data has been preloaded.]]
      image,resize: void;  [[Image was resized (its pixel data).]]
      image,unload: void;  [[Image data has been unloaded (by some mechanism in
                       EFL that threw out the original image data).]]
   }
}