image grids
Image grids, or images, are like regular grids except they're invisible.  Graphics operations directed at them are stored in a memory image, not displayed.  Image grids can be saved on disk, loaded from disk, copied into other image grids, and copied into regular grids.

Image grids are created by XgrCreateGrid(), when gridType = 1.  All graphics operations that apply to regular grids can be directed at image grids too.

  XgrCreateGrid  (@grid, 0, x, y, w, h, win, 0, 0)         ' create grid
  XgrCreateGrid  (@image0, 1, x, y, w, h, win, 0, 0)       ' and image0
  XgrCreateGrid  (@image1, 1, x, y, w, h, win, 0, 0)       ' and image1
  XgrLoadImage   (yourFace$, @image[])                     ' image[]=face
  XgrSetImage    (image0, @image[])                        ' image0=face
  XgrDrawImage   (image1, image0, x1, y1, x2, y2, dx, dy)  ' image1=face
  XgrDrawImage   (grid, image0, x1, y1, x2, y2, dx, dy)    ' grid=face
  XgrDestroyGrid (image0)                                  ' trash image0

When one window is moved over another, contents of the covered window are lost.  When the top window is removed, the obscured area of the covered window is exposed, revealing an invalid image.  Under such circumstances, programs must redraw their grids to update their windows.  But some programs may find it difficult, time consuming, or even impossible to reconstruct the drawing area.  Image grids provide an easy way around this problem.

Image grids can be attached to regular displayable grids.  Graphics operations directed at the grid are also performed on the image.  This has the effect of buffering the displayable grid.

  XgrSetGridBuffer (grid, image0)             ' buffer grid with image0
  XgrDrawLine (grid, $$Blue, x1, y1, x2, y2)  ' line in grid and image0
  XgrDrawCircle (image0, $$Red, radius)       ' draw circle on image0 only
  XgrSetGridBuffer (grid, 0)                  ' stop buffering grid
  XgrClearGrid (grid, $$Black)                ' clear grid to black
  XgrRefreshGrid (grid)                       ' line and circle on grid
  XgrDestroyGrid (image0)                     ' release image0 memory

When a grid needs to be redrawn, XgrRefreshGrid() will do it quickly and efficiently.   Buffering displayable grids with image grids is convenient, but involves two costs.   First, graphics operations directed at buffered grids are slowed significantly, since they are performed twice, once to the displayable grid and once to the image grid.   Second, image grids consume memory.  A 64x64 pixel image consumes between 2KB and 32KB, depending on the image type, while a 512x512 pixel image consumes 128KB to 2MB.

Buffering is performed automatically for grids that have a valid image grid attached.   When image grids are created, their pixels are cleared to zero (black).