
=====================================================================
                        Image Buffers
=====================================================================

the image buffer code uses a small and specialized inheritance
mechanism.  it's basically a stripped down version of the one
used by the gtkobject system.

image buffers manage a three dimensional block of memory.  the block
is measured in (pixels x pixels x bytes).

the z dimension is described by a Tag.  every image buffer has a Tag
assigned at creation which never changes.

the x and y dimensions are each described by a pair of integers,
'period' and 'phase'.  these numbers describe the tiling of the memory
in the image.  period is the tile size in that dimension, and phase is
the offset into the first tile where the image begins (ie: partial
left/top tiles).  there may also be partial right/bottom tiles, do the
math on width and height to find out.  partial tiles are always fully
allocated.  ie: all tiles in a buffer have memory chunks which are
identical in size.

since the image tiling structure is fairly arbitrary, a method called
'focus' is used.  this takes a region-of-interest on the image and
focusses on it.  ie: it calculates the actual contiguous area in the
upper left corner of the ROI and returns the boundaries.  the lower
right parts of the roi may be clipped if they rest on another chunk of
memory.  the info is passed back in a GimpPortion structure which is
the primary means of communication with the other routines.

the memory in each tile has the lifecycle of the underlying GimpMemPtr.
see the memmgmt docs for more details.

an addition is the concept of a 'valid' state.  this is introduced
between the alloc and use of the memory.  by default, memory is
validated by memsetting it to zero.  interfaces will exist in the
subclasses to register a custom validator.

the alloc/validate/use cycle is chained together internally so that
using an unallocated tile will automatically alloc and validate it.
these automatic actions can be suppressed if required.

interfaces will need to be written to exploit the COW abilities of the
memory manager.  these will reside in the subclasses.



=====================================================================
                Comparison to Existing Image Buffers
=====================================================================

this section describes the existing (Dec 14 1998) gimp 1.1 image
memory management as i see it.  the existing interfaces are grouped
and described according to the design principles of the new package.
therefore, the various tile_* header files are thoroughly mixed
together.



Public Interfaces
-----------------

these routines are used throughout gimp.  the new design must provide
public interfaces with equivalent functionality.

  need:
    custom validators
    COW interface

  update:
    tile_manager_new to use tags


#define TileManager GimpBuffer
typedef struct
{
        GimpPortion p;
        GimpPixelArray a;
} Tile;


#define tile_manager_new(w,h,t)     gimp_tile_buffer_new ((t),(w),(h),0,0)
#define tile_manager_destroy        gimp_buffer_delete
#define tile_manager_level_width    gimp_buffer_width
#define tile_manager_level_height   gimp_buffer_height
#define tile_manager_level_bpp      gimp_buffer_depth


  System Initialization
  ---------------------

    tile_swap_add
    tile_swap_exit
      these are only used in app_procs.c (the default swapper) the one
      in xcf.c is commented out.  swapping has been started in the new
      implementation and requires a call to gimp_memory_init().



  Image Creation/Destruction/Attributes
  -------------------------------------

    tile_manager_new
    tile_manager_destroy
    tile_manager_level_width
    tile_manager_level_height
    tile_manager_level_bpp
      a tile_manager_new equivalent is provided by each buffer
      subclass.  the others routines apply to all buffers and are
      present in buffer.h as gimp_buffer_{delete,width,height,depth}.



  Image Data Allocation/Initialization/Accessing
  ----------------------------------------------

      all these routines relate to the image memory lifecycle.  see
      the section on that for a description of the new functionality.

    tile_manager_get_tile
      this is the gimp_buffer_use method with the associated autoalloc
      and autovalidate.  after the use succeeds, do a gimp_buffer_data
      to get the dimensions of the tile you just used.
        - each call returns a newly alloced Tile
        - Tile gets freed in tile_release
        - except it wantread is false, may want to return a static here
          or just fix up callers

    tile_release
      this is a combination of release, invalidate and unalloc.  the
      idea of a separate refcount on the tile which destroys the tile
      when it reaches zero now lives in the bowels of the MemMgr.
      image data is freed by the MemMgr when no MemPtr (and hence no
      Tile or anyone else for that matter) refers to it.  the tile
      itself is never shared by anyone, just the image data.
        - release mem
        - delete Tile

    tile_is_valid
      replaced by gimp_buffer_query.  this is fairly special purpose
      anyway, used only in gimp_image_invalidate and places that do
      mapping

    tile_manager_set_validate_proc
    tile_manager_set_user_data
    tile_manager_get_user_data
      these will be in the subclass specific routines which register a
      custom validator.
      
    tile_manager_map_tile
    tile_manager_map_over_tile
      GimpTileBuffer will add methods to replace the map routines.
      it's unlikely there is any benefit in using COW for the
      GimpFlatBuffer class.  perhaps for the brush/pattern dialogs?
      in any event, the COW interface exported by a tiled buffer will
      probably be different than that for a non-tiled buffer.  thus
      these routines belong in the subclasses, not the base class.
      obviously you won't be mapping over GimpShmBuffers.


  Image Data Usage
  ----------------

    tile_data_pointer
    tile_ewidth
    tile_eheight
    tile_bpp
    tile_size
       these routines are replaced by the GimpPixelArray structure and
       the gimp_buffer_data() routine.




  Unneeded Interfaces
  -------------------

    tile_manager_get_tile_coordinates
      this exists because the initialization interface for
      tilemanagers uses tiles, not coordinates.  image buffers do
      everything in terms of GimpPortion which is in pixels already
      so it's not needed.

    tile_mark_valid
    tile_invalidate_tile
      what good are this routines?  fix gimp_image_invalidate instead.

    tile_manager_get_async
      i haven't thought about this yet.  it doesn;t do anything anyway
      so this can probably be dropped for now.



Protected Interfaces
--------------------

these routines are used internally and shared with xcf.c and plugin.c.
both xcf and plugins arguably require privileged access to the
internal image structure.

    tile_lock
    tile_alloc
    tile_manager_map
    tile_manager_get  (plugins too)
    tile_swap_remove



Private Interfaces
------------------

these routines are used only inside tile*.c.  since they are not
exported to the world, no attempt is made to relate them to public
methods of the new design.  rather, they are listed to complete the
catalog of existing functionality.  the new design should somehow
provide these services as well.

    tile_init
    tile_attach
    tile_detach
    tile_manager_validate
    tile_invalidate
    tile_manager_invalidate_tiles


    tile_swap_in
    tile_swap_in_async
    tile_swap_out
    tile_swap_delete
    tile_swap_compress
    tile_cache_insert
    tile_cache_flush
    tile_cache_set_size
      these will all be internal to MemMgr since memory is now shared,
      not tiles.  they'll be triggered by d_read, d_write, d_release
      primarily.











