
Class documentation.

$Ident: This file is part of the 'Gt-library' 1.0.0 $
$Copyright: (C) 1997 by Gran Gustafsson $

-------------------------------------------------------------------------

** GtImage **
-------------

Name:       GtImage
Superclass: GtBase
Include:    gtimage.h


  This class encapsulates a X image structure. The image may use shared
memory if the support has been compiled into the library and the server
connection allow it. If shared memory is not supported by some reason the
class will use a normal image.

  A global function, "sbool GtShmSupport(void)", is provided to allow
programs to test for shared memory support compiled into the library. The
use of shared memory images may still fail if the server connection do not
support it even if "GtShmSupport()" returns "TRUE".

  NOTE: If the program exits without explicitly destroying the GtImage
objects using shared memory that shared memory will not be removed from the
shared memory system automatically. The user may be able to remove it manually
with the tools ipcs(1) and ipcrm(1).


Tags for GtImage:
-----------------

  Name                   ISGR  Type            Defaults
  -----------------------------------------------------
  GT_Display            (I.G.) (GtDisplay *)   NULL
  GT_Visual             (I...) (Visual *)      DefaultVisual()
  GT_Depth              (I.G.) (long)          DefaultDepth()
  GT_XSize              (I.G.) (long)          1
  GT_YSize              (I.G.) (long)          1
  GT_Format             (I.G.) (long)          ZPixmap
  GT_Offset             (I.G.) (long)          0
  GT_BitmapPad          (I.G.) (long)          0
  GT_BytesPerLine       (I.G.) (long)          xsize
  GT_Data               (ISG.) (char *)        see description below
  GT_Shared             (I.G.) (sbool)         FALSE
  GT_SendComplete       (ISG.) (sbool)         FALSE
  GT_XImage             (..G.) (XImage *)      NULL
  
  
  * GT_Display
    This tag provide the GtDisplay object to for the GtImage to use. It is
    not normally used since the GtDisplay object is provided as an argument
    to the special "Init()" method of this class.
    
    
  * GT_Visual
    Visual to be used when creating the GtImage.
    
    
  * GT_Depth
    The depth of the image (bits per pixel).
    
    
  * GT_XSize, GT_YSize
    Size of the image in pixels.


  * GT_Format
    Image data layout (XYBitmap, XYPixmap or ZPixmap).
    
  
  * GT_Offset
    Extra pixels at the beginning of image lines. This tag has no effect on
    shared memory GtImage objects.
    
  
  * GT_BitmapPad
    Multiple of bit that separates each line in memory. This tag has no
    effect on shared memory GtImage objects.
    
  
  * GT_BytesPerLine
    The number of byte for each line of image memory. It is often the same
    as the width but when using shared memory it is ignored and the server
    will provide this value from the width. If the tag is not used it will
    default to the value of "GT_XSize".
    
    
  * GT_Data
    The image memory to be used. If no memory is provided (tag is not used
    or it's value is "NULL") then memory will be allocated by the object
    from the tags "GT_BytesPerLine" and "GT_YSize". It will be ignored if
    shared memory is to be used.


  * GT_Shared
    A boolean to ask for shared memory to be used by the GtImage. If shared
    memory could not be used it will try with normal memory.
    
    
  * GT_SendComplete
    A boolean to ask the X server to send or not send events to tell when
    a shared memory image has been copied after a "PutImage()".
    
    
  * GT_XImage
    The X image encapsulated by a GtImage.
    

Callbacks for GtImage:
----------------------

  ** NONE DEFINED **
  

Methods for GtImage:
--------------------

   -- User methods --
   
  void PutPixel(int xp,int yp,ulong pixel)
  ulong GetPixel(int xp,int yp)
  void AddPixel(long value)
  void PutImage(GtDrawable *dr,GtGC *gc,int sx,int sy,int dx,int dy,
                int xs,int ys)
  void GetImage(GtDrawable *dr,int sx,int sy,int xs,int ys,ulong msk,
                int fmt,int dx,int dy)
  int GetCompletionType(void)
  char *GetData(void)
  int GetBytesPerLine(void)
  XImage *XIm(void)

   -- GtBase methods --
   
  Init, Set, Get, GetClass, IsSubClassOf, InitV, SetV, GetV, GetA,
  PrtErrHeader
   
 ----------------------------------------------------------------------------

  void PutPixel(int xp,int yp,ulong pixel)
  
    - xp    : x position of pixel.
    - yp    : y position of pixel.
    - pixel : pixel to put.
    
    This method puts a normal X pixel value in a GtImage.
    
 ----------------------------------------------------------------------------

  ulong GetPixel(int xp,int yp)

    - xp    : x position of pixel.
    - yp    : y position of pixel.
    
    - <result> : pixel value at position.
    
    This method reads the normal X pixel value from a GtImage.

 ----------------------------------------------------------------------------

  void AddPixel(long value)
  
    - value : value to add to all pixel in image.
    
    This method adds a value to all pixels in a GtImage.

 ----------------------------------------------------------------------------

  void PutImage(GtDrawable *dr,GtGC *gc,int sx,int sy,int dx,int dy,
                int xs,int ys)
                
    - dr   : pointer to destination GtDrawable to put GtImage in.
    - gc   : pointer to GtGC object to use.
    - sx   : x position in GtImage object.
    - sy   : y position in GtImage object.
    - dx   : x position in GtDrawable object.
    - dy   : y position in GtDrawable object.
    - xs   : x size of rectangle in GtImage object to copy.
    - ys   : y size of rectangle in GtImage object to copy.
    
    This method copies a rectangle of the GtImage object into a GtDrawable.
    If the "GT_SendComplete" tag has been set to "TRUE" then a event will
    arrive upon completion of the copy.

 ----------------------------------------------------------------------------

  void GetImage(GtDrawable *dr,int sx,int sy,int xs,int ys,ulong msk,
                int fmt,int dx,int dy)

    - dr  : pointer to source GtDrawable to copy from.
    - sx  : x position in GtImage object.
    - sy  : y position in GtImage object.
    - xs  : x size of rectangle in GtDrawable object to copy.
    - ys  : y size of rectangle in GtDrawable object to copy.
    - msk : mask of which planes to copy.
    - fmt : format of the image data in the GtImage object.
    - dx  : x position in GtDrawable object.
    - dy  : y position in GtDrawable object.
    
    This method copies a rectangle of the GtDrawable object and stores it
    into the GtImage object. If the GtImage object uses shared memory the
    arguments <sx>, <sy>, <xs>, <ys> and <fmt> will be ignored and the
    rectangle will have the same size as the GtImage object.

 ----------------------------------------------------------------------------

  int GetCompletionType(void)
  
    - <result> : type of completion event.
    
    This method will return the type of the events sent by the server to
    inform the program that a "PutImage()" is completed (only used by shared
    memory GtImage objects).

 ----------------------------------------------------------------------------

  char *GetData(void)
  
    - <result> : pointer to image memory for a GtImage object.
    
    This method returns the a pointer to the image memory used by a GtImage
    object.

 ----------------------------------------------------------------------------

  int GetBytesPerLine(void)
  
    - <result> : bytes per line in the image.
    
    This method returns the number of bytes per line in the image memory.
    This value should always be used when working with the image memory.

 ----------------------------------------------------------------------------

  XImage *XIm(void)
  
    - <result> : X image encapsulated by the object.
    
    This method returns the X image structure encapsulated by a GtImage
    object.
