home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 152.lha / LinkUnTmpRas / LinkUnTmpRas.doc < prev    next >
Text File  |  1988-04-26  |  4KB  |  79 lines
  1.                                                          LinkUmTmpRas()
  2. NAME
  3.      InitLinkTR, UnlinkFreeTR, FreeTmpRas -- allocate-init-link a TmpRas into
  4.         a rastport, and unlink-free a TmpRas from a rastport.
  5.         (written for Manx C 3.4a  long ints, large code and data)
  6. SYNTAX
  7.      #include  <exec/types.h>
  8.      #include  <graphics/rastport.h>
  9.      #include  <graphics/gfxbase.h>
  10.      struct  TmpRas   *InitLinkTR(rastport, width, height, return_code)
  11.      struct  RastPort  *rastport;
  12.      LONG    width,
  13.              height,
  14.              *return_code;
  15.      LONG  UnlinkFreeTR(rastport, width, height)
  16.      struct  RastPort  *rastport;
  17.      LONG    width,
  18.              height;
  19.    
  20.      LONG  FreeTmpRas(tmpras, width, height)
  21.      struct  TmpRas  *tmpras;
  22.      LONG    width,
  23.              height;
  24. DESCRIPTION
  25.      A set of three functions to allocate, init and link in TmpRas structures,
  26.      and to unlink and free TmpRas structures.
  27.      InitLinkTR() AllocMem()'s the storage for the TmpRas structure, and
  28.      AllocRaster()'s a raster of the given width and height.  It then
  29.      InitTmpRas()'s the TmpRas struct with the raster, and links it into the
  30.      given RastPort.
  31.      To link it into the RastPort, it Forbid()'s, changes the RastPort to
  32.      point to the new TmpRas structure, and then Permit()'s.
  33.      It returns the pointer that was in the TmpRas field of the RastPort.
  34.      The valid return codes from the return_code argument are:
  35.         0 == everything ok
  36.        -1 == GfxBase not open -- nothing done
  37.        -2 == can't allocate raster (not enough memory)
  38.        -3 == can't allocate TmpRas structure (not enough memory)
  39.      UnlinkFreeTR() first Forbid()'s, unlinks the TmpRas struct in the RastPort
  40.      setting the ponter to NULL, and then Permit()'s again.
  41.      Next, it calls FreeTmpRas() to free the TmpRas and raster passing on the
  42.      width and height.
  43.      The valid return codes (from the function itself) are:
  44.         0 == everything ok
  45.        -1 == GfxBase not open -- nothing done
  46.        -2 == FreeTmpRas() failed
  47.      FreeTmpRas() checks if the TmpRas pointer is NULL, if so, it returns -2.
  48.      If the TmpRas pointer is not NULL, it frees the raster by calling
  49.      FreeRaster() using the height and width as the height and width of the
  50.      raster, and then calls FreeMem on the TmpRas structure itself.
  51.      The valid return codes are:
  52.         0 == everything ok
  53.        -2 == TmpRas pointer NULL -- nothing done
  54. NOTES
  55.      FreeTmpRas can be used on the pointer returned by InitLinkTR() provided
  56.      it was allocated in a manner similar to the way InitLinkTR() does, and
  57.      the width and height are correct for the raster being freed.
  58.      Screens and windows have separate RastPorts, so linking a TmpRas structure
  59.      into one while using the other for rendering will always solicit a visit
  60.      from the GURU.
  61.      I'm not sure Forbid()'s and Permit()'s need be in these functions, but
  62.      they seemed like a reasonable precaution on a multitasking machine.
  63. BUGS
  64.      FreeTmpRas() assumes that the raster and TmpRas struct were allocated
  65.      using AllocRaster() and AllocMem() respectively.  If this is not the case
  66.      the machine will most likely GURU.
  67.      If UnlinkFreeTR() or FreeTmpRas() are not called on the TmpRas struct
  68.      allocated by InitLinkTR(), the memory will be lost when the program
  69.      ends (ie. you won't be able to get the memory back without rebooting).
  70.      Changing the width and height arguments between calls to InitLinkTR() and,
  71.      UnlinkFreeTR() or FreeTmpRas() will result in bad things happening
  72.      (GURUs?).
  73.      The width and height of the raster should be made as large as the screen
  74.      or window will ever be -- I'm not sure what will happen if the screen or
  75.      window is made larger after the raster is allocated, but I suspect GURUs.
  76. SEE ALSO
  77.      AllocMem(), AllocRaster(), FreeRaster(), FreeMem(), InitTmpRas(),
  78.      Forbid(), Permit(), OpenLibrary(), graphics.library
  79.