home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 10 / Fresh_Fish_10_2352.bin / new / util / blank / blitzblank / developer / blitzblanklib.doc < prev    next >
Text File  |  1995-05-14  |  24KB  |  780 lines
  1. TABLE OF CONTENTS
  2.  
  3. blitzblank.library/--background--
  4. blitzblank.library/BBL_AllocBitMap
  5. blitzblank.library/BBL_AllocDBufBitMap
  6. blitzblank.library/BBL_AllocRastPort
  7. blitzblank.library/BBL_BlankDone
  8. blitzblank.library/BBL_BlankMouse
  9. blitzblank.library/BBL_CloneFirstScreen
  10. blitzblank.library/BBL_CloseScreenSafe
  11. blitzblank.library/BBL_CopyOriginalColors
  12. blitzblank.library/BBL_CopyOriginalScreen
  13. blitzblank.library/BBL_EndDBuf
  14. blitzblank.library/BBL_FadeDown
  15. blitzblank.library/BBL_FreeBitMap
  16. blitzblank.library/BBL_FreeRastPort
  17. blitzblank.library/BBL_GetDarkestPen
  18. blitzblank.library/BBL_GetString
  19. blitzblank.library/BBL_InitDBuf
  20. blitzblank.library/BBL_ModuleRunning
  21. blitzblank.library/BBL_RainbowPalette
  22. blitzblank.library/BBL_RemainingTime
  23. blitzblank.library/BBL_ScreenAvailable
  24. blitzblank.library/BBL_SendMessage
  25. blitzblank.library/BBL_ShowBitMap
  26. blitzblank.library/BBL_UnBlankMouse
  27. blitzblank.library/--background--           blitzblank.library/--background--
  28.  
  29.     PURPOSE
  30.   This is the support-library for BlitzBlank-modules. These functions
  31.   handle the communication between BlitzBlank and the blankermodules.
  32.   Also, there are some additional functions, which may be of use for
  33.   some modules.
  34.  
  35.   ALL modules MUST use the following functions:
  36.   - BBL_GetString()
  37.   - BBL_SendMessage()
  38.   - BBL_ModuleRunning()
  39.   - BBL_BlankDone()
  40.  
  41.   Modules, which open their own screen, instead of getting one from
  42.   BlitzBlank (what most modules do), should use the following
  43.   functions in addition:
  44.   - BBL_BlankMouse()
  45.   - BBL_UnBlankMouse()
  46.   - BBL_CloseScreenSafe()
  47.  
  48.   The other functions could be useful for your module. Check them out.
  49.  
  50. blitzblank.library/BBL_AllocBitMap         blitzblank.library/BBL_AllocBitMap
  51.  
  52.     NAME
  53.     BBL_AllocBitMap -- Allocate a bitmap.
  54.  
  55.     SYNOPSIS
  56.     bitmap = BBL_AllocBitMap( width, height, depth, flags)
  57.                              D0      D1     D2      D3
  58.  
  59.     struct BitMap *BBL_AllocBitMap( ULONG, ULONG, ULONG, ULONG )
  60.  
  61.     FUNCTION
  62.   Allocates a bitmap with the given width, height, depth and flags.
  63.   This function is V39-aware and will so call V39's AllocBitMap(),
  64.   if available. You will probably need this function in modules
  65.   with doublebuffering or hidden drawing.
  66.  
  67.     INPUTS
  68.   width  - Width of the bitmap in pixels.
  69.  
  70.   height - Height of the bitmap in pixels.
  71.  
  72.   depth  - Number of planes in the bitmap.
  73.  
  74.   flags  - BMF_CLEAR to specify that the allocated raster should be
  75.            filled with color 0.
  76.  
  77.            BMF_DISPLAYABLE to specify that this bitmap data should
  78.            be allocated in such a manner that it can be displayed.
  79.            Displayable data has more severe alignment restrictions
  80.            than non-displayable data in some systems.
  81.  
  82.            BMF_INTERLEAVED tells graphics that you would like your
  83.            bitmap to be allocated with one large chunk of display
  84.            memory for all bitplanes. This minimizes color flashing
  85.            on deep displays. If there is not enough contiguous RAM
  86.            for an interleaved bitmap, graphics.library will fall
  87.            back to a non-interleaved one.
  88.  
  89.     RESULTS
  90.   bitmap - Allocated and initialized bitmap or NULL, if the call failed.
  91.  
  92.     SEE ALSO
  93.   BBL_FreeBitMap()
  94.  
  95. blitzblank.library/BBL_AllocDBufBitMap blitzblank.library/BBL_AllocDBufBitMap
  96.  
  97.     NAME
  98.     BBL_AllocDBufBitMap -- Allocate a bitmap for double-buffering.
  99.  
  100.     SYNOPSIS
  101.     bitmap = BBL_AllocDBufBitMap( screen )
  102.                                   A0
  103.  
  104.     struct BitMap *BBL_AllocDBufBitMap( struct Screen * )
  105.  
  106.     FUNCTION
  107.   Allocates a 2nd bitmap for the given screen with the same size,
  108.   depth and attributes (flags). At this time, it just calls
  109.   BBL_AllocBitMap(), but in the future, it may know how to deal
  110.   with graphic-cards.
  111.  
  112.     INPUTS
  113.   screen - An open screen, for which the bitmap is for.
  114.            (It is safe, to pass a NULL here -> nothing will be done)
  115.  
  116.     RESULTS
  117.   bitmap - Allocated and initialized BitMap or NULL, if the call failed.
  118.  
  119.     SEE ALSO
  120.   BBL_InitDBuf(), BBL_ShowBitMap(), BBL_EndDBuf(), BBL_FreeBitMap()
  121.  
  122. blitzblank.library/BBL_AllocRastPort     blitzblank.library/BBL_AllocRastPort
  123.  
  124.     NAME
  125.     BBL_AllocRastPort -- Allocate a rastport.
  126.  
  127.     SYNOPSIS
  128.     rastport = BBL_AllocRastPort( width, height, depth, flags )
  129.                                  D0      D1     D2      D3
  130.  
  131.     struct RastPort *BBL_AllocRastPort( ULONG, ULONG, ULONG, ULONG )
  132.  
  133.     FUNCTION
  134.   Allocates a rastport with the given width, height, depth and flags.
  135.   You will probably need this function in modules with doublebuffering
  136.   or hidden drawing. Actually, this function allocates a rastport and
  137.   then calls BBL_AllocBitMap().
  138.  
  139.     INPUTS
  140.   width  - Width of the rastport in pixels.
  141.  
  142.   height - Height of the rastport in pixels.
  143.  
  144.   depth  - Number of planes in the rastport.
  145.  
  146.   flags  - BMF_CLEAR to specify that the allocated raster should be
  147.            filled with color 0.
  148.  
  149.            BMF_DISPLAYABLE to specify that this bitmap data should
  150.            be allocated in such a manner that it can be displayed.
  151.            Displayable data has more severe alignment restrictions
  152.            than non-displayable data in some systems.
  153.  
  154.            BMF_INTERLEAVED tells graphics that you would like your
  155.            bitmap to be allocated with one large chunk of display
  156.            memory for all bitplanes. This minimizes color flashing
  157.            on deep displays. If there is not enough contiguous RAM
  158.            for an interleaved bitmap, graphics.library will fall
  159.            back to a non-interleaved one.
  160.  
  161.     RESULTS
  162.   rastport - Allocated and initialized RastPort or NULL, if the call failed.
  163.  
  164.     SEE ALSO
  165.   BBL_FreeRastPort()
  166.  
  167. blitzblank.library/BBL_BlankDone             blitzblank.library/BBL_BlankDone
  168.  
  169.     NAME
  170.     BBL_BlankDone -- Tell BlitzBlank that blanking is finished.
  171.  
  172.     SYNOPSIS
  173.     BBL_BlankDone()
  174.  
  175.     void BBL_BlankDone( void )
  176.  
  177.     FUNCTION
  178.   Signals BlitzBlank, that your Module is finished with the
  179.   blank()-function. The module must call it, after its blank()-function
  180.   returned. BlitzBlank will then close the blankscreen (if it opened
  181.   one).
  182.  
  183.     INPUTS
  184.  
  185.     RESULTS
  186.  
  187.     SEE ALSO
  188.   All modules
  189.  
  190. blitzblank.library/BBL_BlankMouse           blitzblank.library/BBL_BlankMouse
  191.  
  192.     NAME
  193.     BBL_BlankMouse -- Blank the mouse on your own screen.
  194.  
  195.     SYNOPSIS
  196.     window = BBL_BlankMouse( screen, mode )
  197.                              A0     D0
  198.  
  199.     struct Window *BBL_BlankMouse( struct Screen *, UBYTE )
  200.  
  201.     FUNCTION
  202.   Opens a window on the screen at position (0,0).
  203.   The window is borderless. This window will be activated and the
  204.   mousepointer for this window will be made invisible -> The mouse
  205.   is blanked. Keep the result of this function for passing it
  206.   to BBL_UnBlankMouse() later. If you get a screen from BlitzBlank,
  207.   you will never need this function, because BlitzBlank will then
  208.   do the mouseblanking for you. Normally, you will use mode 0,
  209.   but if you want to have a RastPort with clipping to draw in, you
  210.   could use mode 1 for a fullscreen-window and use this window's
  211.   RastPort to draw in, instead of the screen's RastPort.
  212.  
  213.     INPUTS
  214.     screen - Pointer to an open screen.
  215.            (It is safe, to pass a NULL here -> nothing will be done)
  216.  
  217.   mode   - 0 for small window (1x1), 1 for fullsize-window.
  218.  
  219.     RESULTS
  220.   window - Keep this for use with BBL_UnBlankMouse().
  221.  
  222.     SEE ALSO
  223.   BBL_UnBlankMouse(), BB.Tiles.c
  224.  
  225. blitzblank.lib/BBL_CloneFirstScreen       blitzblank.lib/BBL_CloneFirstScreen
  226.  
  227.     NAME
  228.     BBL_CloneFirstScreen -- Clone the first screen.
  229.  
  230.     SYNOPSIS
  231.     screen = BBL_CloneFirstScreen( moredepth, flags )
  232.                                      D0       D1
  233.  
  234.     struct Screen *BBL_CloneFirstScreen( UWORD, ULONG )
  235.  
  236.     FUNCTION
  237.   Clones the first screen. That means it opens a screen with the same
  238.   dimensions, same colors and same contents. Normally, you won't need
  239.   this function, because you can get a cloned first screen by BlitzBlank
  240.   with the flag BBF_CloneScreen in BB_Message/flags. You only need this
  241.   function, if you decide at run-time, if you want a custom screen or a
  242.   cloned screen.
  243.  
  244.     INPUTS
  245.     moredepth - If you want a deeper screen than the first screen then set
  246.               this to the number of additional bitplanes.
  247.  
  248.   fl