efl/src/lib/efl/interfaces/efl_gfx_buffer.eo

import efl_gfx_types;

/* FIXME: this is very very low level. expose to apps? */
enum Efl.Gfx.Buffer.Access_Mode {
   none      = 0x0,
   read      = 0x1,
   write     = 0x2,
   cow       = 0x4,  [[Forces copy-on-write if already mapped as read-only. Requires write.]]
}

interface Efl.Gfx.Buffer ()
{
   [[Common APIs for all objects representing images and 2D pixel buffers.]]
   legacy_prefix: null;

   methods {
      @property buffer_size {
         [[Rectangular size of the pixel buffer as allocated in memory.]]
         set {
            [[Potentially not implemented, @.buffer_size may be read-only.]]
         }
         get {}
         values {
            w: int; [[Width in pixels.]]
            h: int; [[Height in pixels.]]
         }
      }
      @property colorspace {
         [[The colorspace defines how pixels are encoded in the image in memory.

           By default, images are encoded in 32-bit BGRA, ie. each pixel takes
           4 bytes in memory, with each channel B,G,R,A encoding the color with
           values from 0 to 255.

           All images used in EFL use alpha-premultipied BGRA values, which
           means that for each pixel, B <= A, G <= A and R <= A.
         ]]
         get {
            [[Returns the current encoding of this buffer's pixels.

              See @Efl.Gfx.Colorspace for more information on the supported
              formats.
            ]]
         }
         values {
            cspace: Efl.Gfx.Colorspace;
         }
      }
      @property alpha {
         [[Indicates whether the alpha channel should be used.

           This does not indicate whether the image source file contains
           an alpha channel, only whether to respect it or discard it.
         ]]
         set {
            [[Change alpha channel usage for this object.

              This function sets a flag on an image object indicating
              whether or not to use alpha channel data. A value of $true
              makes it use alpha channel data, and $false makes it ignore
              that data. Note that this has nothing to do with an object's
              color as manipulated by @Efl.Gfx.Base.color.set.
            ]]
         }
         get {
            [[Retrieve whether alpha channel data is used on this object.]]
         }
         values {
            alpha: bool; [[Whether to use alpha channel ($true) data
                           or not ($false).]]
         }
      }

      @property stride {
         [[Length in bytes of one row of pixels in memory.

           Usually this will be equal to width * 4, with a plain BGRA image.
           This may return 0 if the stride is not applicable.

           When applicable, this will include the @.buffer_borders as well
           as potential extra padding.
         ]]
         get {}
         values {
            stride: int;
         }
      }

      buffer_update_add {
         [[Mark a sub-region of the given image object to be redrawn.

           This function schedules a particular rectangular region of an
           image object to be updated (redrawn) at the next rendering cycle.
         ]]
         params {
            @in x: int; [[X-offset of the region to be updated.]]
            @in y: int; [[Y-offset of the region to be updated.]]
            @in w: int; [[Width of the region to be updated.]]
            @in h: int; [[Height of the region to be updated.]]
         }
      }

      /* FIXME: too low-level? */
      @property buffer_borders {
         [[Duplicated pixel borders inside this buffer.

           Internally, EFL may require an image to have its border pixels
           duplicated, in particular for GL textures. This property exposes
           the internal duplicated borders to allow calling @.buffer_map
           with the entire pixel data, including those edge pixels.
         ]]
         get {}
         values {
            l: uint(0); [[Left border pixels, usually 0 or 1]]
            r: uint(0); [[Right border pixels, usually 0 or 1]]
            t: uint(0); [[Top border pixels, usually 0 or 1]]
            b: uint(0); [[Bottom border pixels, usually 0 or 1]]
         }
      }

      /* Note: Not for bindings, only C/C++ */
      buffer_map {
         [[Map a region of this buffer for read or write access by the CPU.

           Fetches data from the GPU if needed. This operation may be slow if
           cpu_readable_fast or cpu_writeable_fast are not true, or if the
           required colorspace is different from the internal one.

           Note that if the buffer has @.buffer_borders, then $x and $y may
           be negative.
         ]]
         params {
            @out length: int @nonull; [[Accessible buffer size in bytes, should not be $null.]]
            @in mode: Efl.Gfx.Buffer.Access_Mode; [[Specifies whether to map for read-only,
                                                    write-only or read-write access (OR combinaison of flags).]]
            @in x: int @optional;  [[X position of the top-left pixel to map, defaults to 0.]]
            @in y: int @optional;  [[Y position of the top-left pixel to map, defaults to 0.]]
            @in w: int @optional; [[If 0, defaults to the buffer width.]]
            @in h: int @optional; [[If 0, defaults to the buffer height.]]
            @in cspace: Efl.Gfx.Colorspace @optional; [[Requested colorspace. If differen from the internal cspace,
                                                        map should try to convert the data into a new buffer.
                                                        argb8888 by default.]]
            @out stride: int @optional; [[Returns the length in bytes of a mapped line]]
         }
         return: void* @warn_unused; [[Pointer to the top-left pixel data. Returns $null in case of failure]]
      }
      buffer_unmap {
         [[Unmap a region of this buffer, and update the internal data if needed.

           EFL will update the internal image if the map had write access.
         ]]
         params {
            @in data: void*; [[Data pointer returned by a previous call to map]]
            @in length: int; [[Must be the same as returned by map.]]
         }
         return: bool; [[This will return $false in case of failure (invalid
                         parameters or state of the object).]]
      }

      /* FIXME: naming: buffer_set, buffer_attach, external_data_set, ...? */
      buffer_data_set {
         [[Set the pixels for this buffer, or allocate a new memory region.

           EFL will use $pixels directly, and update the GPU-side texture
           if required. This will mark the image as dirty.

           If $pixels is $null, then a new empty buffer will be allocated.
           If the buffer already had pixel data, the previous image data will
           be dropped. This is the same as @.buffer_copy_set.

           The memory buffer $pixels must be large enough to hold
           $width x $height pixels encoded in the colorspace $cspace.

           See also @.buffer_copy_set if you want EFL to copy the input buffer
           internally.
         ]]
         params {
            @in pixels: void* @nullable; [[If $null, allocates an empty buffer]]
            @in width: int;
            @in height: int;
            @in stride: int @optional; [[If 0, automatically guessed from the $width.]]
            @in cspace: Efl.Gfx.Colorspace @optional; [[argb8888 by default.]]
         }
         return: bool @warn_unused; [[This function returns $false in case of failure.]]
      }
      buffer_copy_set {
         [[Set the pixels for this buffer by copying them, or allocate
           a new memory region.

           This will allocate a new buffer in memory and copy the input
           $pixels to it. The internal colorspace is not guaranteed to
           be preserved, and colorspace conversion may happen internally.

           If $pixels is $null, then a new empty buffer will be allocated.
           If the buffer already had pixel data, the previous image data will
           be dropped. This is the same as @.buffer_data_set.

           The memory buffer $pixels must be large enough to hold
           $width x $height pixels encoded in the colorspace $cspace.

           $pixels should not be the return value of @.buffer_data_get.
         ]]
         params {
            @in pixels: const(void)* @nullable; [[If $null, allocates an empty buffer]]
            @in width: int;
            @in height: int;
            @in stride: int @optional; [[If 0, automatically guessed from the $width.]]
            @in cspace: Efl.Gfx.Colorspace @optional; [[argb8888 by default.]]
         }
         return: bool @warn_unused; [[This function returns $false in case of failure.]]
      }
      buffer_data_get {
         [[Get a direct pointer to the internal pixel data, if available.

           This will return $null unless @.buffer_data_set was used to pass in an
           external data pointer.

           Note: This is different from the legacy API data, which is now
           replaced by map/unmap.
         ]]
         return: void* @warn_unused;
      }
      /* Note: border, span and buffer flags not imported from ector buffer */
   }
}