Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/SDI.ZIP/SDIMAGE.DOC

Text File | 1988-11-26 | 14.9 KB | 372 lines

                          SDIMAGE V1.02
                         by Michael Day
                     as of 25 November 1988


     SDImage is a Turbo Pascal unit designed to allow saving  any
BGI screen to disk. SDImage uses GetImage and PutImage to do  the
save.  The Program works by using an intermediate buffer to  save
the image. The size of the buffer is user definable.



Image Buffer:

     There  are 20 image buffers available for use.  At  startup,
the  buffers  are  not allocated on the  heap,  only  the  buffer
headers  exist.  This keeps memory usage at a minimum  since  the
buffers  are  only allocated when they are needed. You  can  also
release a buffer at any time to pick up the heap space it uses.

     You  can either predefine a buffer to the size you want,  or
the Image buffer will be automatically allocated when the  buffer
is used. Although 20 buffers should be more than enough for  most
applications, you can specify more (or fewer) buffers by changing
the constant "MaxImageBuf" to the desired value.

     Buffers  are used by direct reference in the  command.  This
makes  buffer usage unambiguous. When a buffer is  referenced  in
the  SaveImage command, it is first checked to see if it  already
has an image stored in it. If there is an image in the buffer, it
is immediately flushed to disk.

     If  the  buffer  does not have an image in it,  then  it  is
checked  to see if the buffer has not been allocated yet. If  the
buffer  has not been allocated, then a buffer of default size  is
allocated.  Currently the default buffer size is 5000,  but  this
can  be redefined by changing the constant "MaxRawImage"  to  the
desired  default buffer size. Alternately, the individual  buffer
sizes  can  be changed at run time by using  the  "AllocImageBuf"
function.

     Once a buffer has been assured to be clean and defined it is
tested  to see if the image can completely fit in the buffer.  If
the image can fit in the buffer, then it is placed in the  buffer
and no further action taken.

     If the image cannot be completely placed in the buffer, then
a  disk save is performed. The image is moved into the buffer  in
pieces and flushed to disk until then entire image has been saved
to disk. The buffer is left empty after a disk save.





Disk Files:

     When   an  image  cannot  fit  in  a  buffer  it   will   be
automatically  saved to disk instead. Alternately, the image  can
be  forced to always be directed to the disk (see the section  on
buffer control).

     Images  are  referenced  by an image  reference  number  (or
handle).  You define the image reference number to be  used  with
SaveImage  or DisplayImage. This number is used to keep track  of
the image. If you use the same number for an image, then it  will
normally be overwritten. An exception to this is if the image  is
in  a  different buffer. There are no checks made to  see  if  an
image is in another buffer.

     When an image is written to disk, a file is created using  a
name  built from the image reference number. An image  file  uses
the  first three letters "SDI" followed by a leading zero  filled
number which is the reference number that was passed, followed by
the file extension of ".IMG".

     An  image  file  will  remain on disk  until  it  is  either
explictly  erased,  or the DisplayImage function is  called  with
ImgClr  =  true which will cause the image  to  be  automatically
erased after the image has been displayed.

     Because  an  image  will remain  on  disk  unless  explictly
erased, it can be very easy to clutter up the disk with old image
files. For this reason it is recommended that you place the image
files in their own subdirectory. the "SetImagePath" function  has
been provided for this purpose.

     An  advantage  of having images on disk  referenced  by  the
image  reference  number  is that images can be  created  in  one
program  and  displayed in another. A disadvantage  is  that  the
image  is  saved using the BGI GetImage  and  PutImage  functions
which means that the display must be the same as the display used
to create the image.

     Saving  images  to  disk allows for a  much  smaller  memory
requirement  within a program to save images. This can be a  real
boon  when a program grows too large and you are forced  to  find
ways  to reduce the amount of memory usage. The  disadvantage  is
that it is much slower to save an image to disk because you  have
to deal with the physical access time of the disk drive. This can
cause  some  problems in the sluggishness of  the  display  while
saving  or displaying images to/from disk. To help relieve  this,
SDImage uses special effects to make the display look more active
and thus giving the user a feeling that the computer is  actually
doing something to the display while it is busy working with  the
disk.




Special Effects:

     Displaying images from disk can take a while to perform,  so
to  help  liven  things  up  some  special  effects  options  are
provided.

     The special effects work in conjunction with disk  accesses.
When  an  image  is  being read from disk,  it  usually  must  do
multiple  buffer writes. By controlling where those writes  occur
on the screen, special effects can be incorporated into the image
display.  To do this requires that the image be saved  originally
in the desired format.

     Since   the  special  effects  are  tied  directly  to   the
disk/buffer transfer, special effects are not operational when an
image stays in the buffer, or when there is only one buffer image
in  the disk file. Multiple image segments must be used  to  have
the  proper  special  effects. Since  only  large  images  really
benifit from special effects this usually is no problem.

     Remember,  the smaller the buffer, the smoother the  special
effect,  but  at the same time the effect will become  slower  as
well. This can be compensated for by using a ram-disk instead  of
a hard disk to store the images.

     The  Special  effects are controlled by the  "Style"  option
word  that is passed to the SaveImage function. The  DisplayImage
function cannot control special effects. The image must be stored
with the desired effect for it to be active.

     The  lower  four  Style bits  control  the  special  effects
operation. Bit 2 controls whether the image will be displayed  as
a "Pull" or via an Expand/Merge operation. Bit 1 controls whether
the image will grow in the Horizontal or vertical direction.  Bit
0 controls the edge that the image will grow from, or whether  it
will expand or merge. Bit 3 is currently unused.


                       Style
     +---+-----+---------+------+-------------+
     |bit|  3  |    2    |  1   |      0      |
     +---+-----+---------+------+-------------+
     | 1 | --- | Xpd/Mrg | Horz | Xpd/Left/Dn |
     +---+-----+---------+------+-------------+
     | 0 | --- |  Pull   | Vert | Mrg/Rght/Up |
     +---+-----+---------+------+-------------+

          0=Pull Down
          1=Pull Up
          2=Pull Right
          3=Pull Left
          4=Merge Vertical
          5=Expand Vertical
          6=Merge Horizontal
          7=Expand Horizontal

Note:  Special effects only operate when the image is  read  from
the disk, in fact it works because it uses the disk buffering  as
an inherent part of the effects control.




Buffer Control:

     The  upper  four bits of the Style byte control  the  buffer
operation. Bit 7 controls the Disk, and bit 6 controls the EMS.


   -->     EMS is not currently supported in SDImage.     <--


     If bit 7 is on, then the image will always be saved to disk.
If bit 7 is off, then the image will try to stay in the buffer if
possible.

     Bit 6 is intended for EMS control. The intent is that if Bit
6  is on, then the image will be directed to the EMS  instead  of
disk.  If  bit 6 is off, then the Disk will be  used.  In  either
case, bit 7 controls buffering activity.


                      Style
         +---+------+-------+-----+-----+
         |bit|  7   |   6   |  5  |  4  |
         +---+------+-------+-----+-----+
         | 1 | Disk |  EMS  | --- | --- |
         +---+------+-------+-----+-----+
         | 0 | Auto | NoEMS | --- | --- |
         +---+------+-------+-----+-----+


     The image flow is controlled as follows:

          $00  -> Buffer -> Disk
          $40  -> Buffer -> EMS -> Disk
          $80  -> Disk
          $C0  -> EMS -> Disk


     Another mechanism that can be used is to refer to a ram disk
for  the images instead of a hard disk. This allows  the  special
effects associated with disk operation to be used as well as  the
reduced program memory requirements while still keeping as fast a
file access as possible. And since a ram disk can be installed in
EMS memory, this would be one way to get around the current  lack
of EMS support in SDImage.



Buffer Notes:

     Although you can define just about any size buffer you wish,
there  are some limitations. The maximum buffers size is  limited
to  65521, and the minimum buffer size is limited to one  row  of
the saved image, or the buffer size of a saved image being read.

     If you change the size of a buffer while an image is in  the
buffer, the buffer will be flushed and the image will be lost.

     If a buffer does not exist or is too small for the operation
it will be automatically resized to an acceptable value.

     If  an  image will not fit in the buffer, then  it  will  be
placed on the disk. If the image is placed on the disk, then  the
buffer will be left empty at the end of the operation.


Disk Notes:

     When  an image is saved to disk a filename is created  based
on the image reference number. The filename consists of the three
letters  "SDI", followed by a left zero filled five digit  number
which is the image reference number used, followed by an filename
extension of ".IMG".

     Normally  an image will not be placed on the disk unless  it
cannot  fit  in the image buffer. Sometimes it  is  desirable  to
create a disk image for later recall in another program or in the
same  program  at  a later time. A disk save  can  be  forced  by
setting  bit  4  ($10) of the "Style"  option  in  the  SaveImage
function.

     Disk  images use one file per image. Because of  this  there
can be a lot of image files hanging around if there are a lot  of
images  saved. It is recommended that the  images  be  placed  in
their own subdirectory.  This  will  have  the added advantage of
speeding  things  up a bit  since the directory search won't have
all the other program files to deal with.

     Disk images will be left on the disk if the "ImgClr"  option
in the "DisplayImage" function is false. If ImgClr is provided as
true, then the image will be erased from the disk (and/or buffer)
after it has been displayed.

     If  an image file exists on the disk by the  same  reference
number  then it will be overwritten by the new image when  it  is
saved.

     You should be aware that if you don't delete the image  file
while  the program is running it will still be on the disk  after
the  program has been run. This was done purposely so that  image
files could be created to be read by other programs or at a later
date  with the same program. This can however cause a clutter  of
IMG files if you don't pay attention to this.

     You  can  remove  a image file by  just  erasing  the  file.
Alternately  you  can use the DeleteImage function  to  delete  a
specific image.

     If   an  image  file  is  requested  and  not   found,   the
DisplayImage function is aborted and returns a false condition.

     If  a  image  file cannot be  created,  then  the  SaveImage
function will be aborted and returns a false condition.





SDImage Functions:



AllocImageBuf(Buf:word; Size:word):boolean

     Allocates  a specified amount of heap memory to the  buffer.
The buffer is automatically allocated to the default size if  you
don't  allocate  the buffer before use. You  can  reallocate  the
buffer size at anytime. If the buffer number is invalid, or there
is  not enough heap space to allocated the specified  buffer  the
function will return false.




ReleaseImageBuf(Buf:word):boolean

     Releases the heap space used by the buffer. You can  release
the  buffer  space at anytime. If the buffer is  deallocated  the
next  time  you  try to use it, then  it  will  be  automatically
reallocated  to the default size. If the buffer number  given  is
invalid the function will return false.




SetImagePath(Path:string):boolean

     You  can  specify that the images be placed  in  a  separate
subdirectory  by using this function. It is recommended that  you
place images in a separate directory if you are saving more  than
a couple of images to keep directory clutter to a minimum. If the
Path  could not be found, then the subdirectory will be made.  If
the subdirectory could not be made, then the function will return
false. You can preceed the path with a drive letter to direct the
image  to another drive. When specifying a new path, do  not  use
the  trailing  '\' SDImage will handle that. Example: 'D:\SDI'.
You  can use the default drive by dropping the drive  letter  and
colon from the path designation.

SaveImage(Img,Buf:word; x1,y1,x2,y2:integer; Style:word):boolean

     Use  this  function to save an image to  the  buffer  and/or
disk.  "Img" specifies the Img reference number, "Buf"  specifies
the buffer to use, "x1,y1,x2,y2" specifies the area of the screen
to  save,  and "Style" specifies how to save the  image.  If  the
Image could not be saved, then SaveImage will return false.




DisplayImage(Img,Buf:word; ImgClr:boolean):boolean

     Use this function to display the image. "Img" specifies  the
image  reference  number to find. "Buf" specifies the  buffer  to
use, and ImgClr specifies whether to delete the image after it is
used. If ImgClr is false, then the image will not be deleted  and
DisplayImage  can  refer  to it again at a  later  date.  If  the
specified  image  is  not found, then  DisplayImage  will  return
false.




FlushImage(Buf:word):boolean

     Flushes  an  image to disk from the buffer if  there  is  an
image in the buffer. You can use this before changing a buffer to
insure that no images are lost. If the image could not be flushed
(such as due to a disk error), the function will return false.




DeleteImage(Img,Buf:word):boolean

     This  deletes an image from the buffer and/or disk.  If  the
specified image was not found the function will return false.

<eof>