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 @beta Efl.Gfx.Buffer_Access_Mode {
   [[Graphics buffer access mode]]
   none      = 0x0, [[No buffer access]]
   read      = 0x1, [[Read access to buffer]]
   write     = 0x2, [[Write aces to buffer]]
   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 @beta 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 {
            sz: Eina.Size2D; [[Size of the buffer 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; [[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.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; [[Stride]]
         }
      }

      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 {
            @cref region: Eina.Rect @optional; [[The updated region.]]
         }
      }

      /* 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(0U); [[Left border pixels, usually 0 or 1]]
            r: uint(0U); [[Right border pixels, usually 0 or 1]]
            t: uint(0U); [[Top border pixels, usually 0 or 1]]
            b: uint(0U); [[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 {
            @in mode: Efl.Gfx.Buffer_Access_Mode; [[Specifies whether to map for read-only,
                                                    write-only or read-write access (OR combination of flags).]]
            @cref region: Eina.Rect @optional; [[The region to map.]]
            @in cspace: Efl.Gfx.Colorspace @optional; [[Requested colorspace. If different 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: Eina.Rw_Slice; [[The data slice. In case of failure, the
            memory pointer will be $null.]]
      }
      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: Eina.Rw_Slice; [[Data slice returned by a previous call to map.]]
         }
         return: bool; [[$true on success, $false otherwise]]
      }
      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 {
            @cref slice: Eina.Slice; [[If $null, allocates an empty buffer]]
            @in size: Eina.Size2D; [[The size in pixels.]]
            @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; [[$true on success, $false otherwise]]
      }
      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 {
            @cref slice: Eina.Slice; [[If $null, detaches the previous buffer.]]
            @in size: Eina.Size2D; [[The size in pixels.]]
            @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; [[$true on success, $false otherwise]]
      }
      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.
         ]]
         params {
            @in plane: int @optional; [[Plane ID. 0 by default. Useful for
               planar formats only.]]
         }
         return: Eina.Slice; [[The data slice. The memory pointer will be $null
            in case of failure.]]
      }
      /* Note: border, span and buffer flags not imported from ector buffer */
   }
}