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

import efl_gfx_types;
import eina_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.]]
}

/* FIXME: YUV and other planar formats are not properly handled in this API! */

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

   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.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 slice: Eina.Rw_Slice; [[Pointer to the top-left pixel data.]]
            @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.]]
            @in plane: int @optional; [[Plane ID. 0 by default. Useful for planar formats only.]]
            @out stride: int @optional; [[Returns the length in bytes of a mapped line]]
         }
         return: bool;
      }
      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.

           Note: The $slice struct does not need to be the one returned
           by @.buffer_map, only its contents ($mem and $len) must match. But
           after a call to @.buffer_unmap the original $slice structure is not
           valid anymore.
         ]]
         params {
            @in slice: const(Eina.Rw_Slice)*; [[Data slice returned by a previous call to map.]]
         }
         return: bool;
      }
      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_managed_set.

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

           $slice should not be the return value of @.buffer_managed_get.
         ]]
         params {
            @in slice: const(Eina.Slice)* @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.]]
            @in plane: int @optional; [[Plane ID. 0 by default. Useful for planar formats only.]]
         }
         return: bool;
      }
      buffer_managed_set {
         [[Set the pixels for this buffer, managed externally by the client.

           EFL will use the pixel data directly, and update the GPU-side
           texture if required. This will mark the image as dirty. If $slice
           is $null, this will detach the pixel data.

           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 slice: const(Eina.Slice)* @nullable; [[If $null, detaches the previous 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.]]
            @in plane: int @optional; [[Plane ID. 0 by default. Useful for planar formats only.]]
         }
         return: bool;
      }
      buffer_managed_get {
         [[Get a direct pointer to the internal pixel data, if available.

           This will return $null unless @.buffer_managed_set was used to pass
           in an external data pointer. The returned @Eina.Slice struct must be
           freed by the caller.
         ]]
         params {
            @out slice: Eina.Slice;
            @in plane: int @optional; [[Plane ID. 0 by default. Useful for planar formats only.]]
         }
         return: bool;
      }
      /* Note: border, span and buffer flags not imported from ector buffer */
   }
}