home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / util / blank / blitzblank / developer / blitzblanklib.doc < prev    next >
Encoding:
Text File  |  1995-05-14  |  23.3 KB  |  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.   flags     - BBF_Interleaved for an interleaved screen.
  249.  
  250.     RESULTS
  251.   screen - Cloned first screen or NULL.
  252.  
  253.     SEE ALSO
  254.   BB.Goats
  255.  
  256. blitzblank.library/BBL_CloseScreenSafe blitzblank.library/BBL_CloseScreenSafe
  257.  
  258.     NAME
  259.     BBL_CloseScreenSafe -- Close a screen safely.
  260.  
  261.     SYNOPSIS
  262.     BBL_CloseScreenSafe( screen )
  263.                            A0
  264.  
  265.     void BBL_CloseScreenSafe( struct Screen * )
  266.  
  267.     FUNCTION
  268.   This function calls intuition's CloseScreen(). But if it can't close
  269.   the screen (because there are windows left open on it), it waits
  270.   until it really can close the screen. If you get the screen from
  271.   BlitzBlank, you will never need this function, because BlitzBlank
  272.   closes the screen for you (safely). But if you open the blankscreen
  273.   yourself, you should use this function to close it (after closing
  274.   all your own windows, of course), because there may be "visitor"-
  275.   windows from some nasty programs (eg ARQ, TrapDoor) on your
  276.   screen.
  277.  
  278.     INPUTS
  279.     screen - Pointer to an open screen.
  280.            (It is safe, to pass a NULL here -> nothing will be done)
  281.  
  282.     RESULTS
  283.  
  284.     SEE ALSO
  285.   BB.Tiles.c
  286.  
  287. blitzblank.lib/BBL_CopyOriginalColors   blitzblank.lib/BBL_CopyOriginalColors
  288.  
  289.     NAME
  290.     BBL_CopyOriginalColors -- Copy the palette of the original screen.
  291.  
  292.     SYNOPSIS
  293.     success = BBL_CopyOriginalColors( screen )
  294.                                         A0
  295.  
  296.     BOOL BBL_CopyOriginalColors( struct Screen * )
  297.  
  298.     FUNCTION
  299.   This function copies the palette of the original first screen to the
  300.   screen. It is only useful for screen-cloning modules, which want
  301.   to open their blankscreen on their own.
  302.   If you get your screen from BlitzBlank, you will never need this
  303.   function.
  304.   This function is V39-aware and knows how to copy colors with
  305.   256 levels of R, G, B.
  306.  
  307.     INPUTS
  308.     screen - Pointer to an open screen.
  309.            (It is safe, to pass a NULL here -> nothing will be done)
  310.  
  311.     RESULTS
  312.   success - TRUE if the copy was successful, otherwise FALSE.
  313.  
  314.     SEE ALSO
  315.   BB.Tiles.c
  316.  
  317. blitzblank.lib/BBL_CopyOriginalScreen   blitzblank.lib/BBL_CopyOriginalScreen
  318.  
  319.     NAME
  320.     BBL_CopyOriginalScreen -- Copy the contents of the original screen.
  321.  
  322.     SYNOPSIS
  323.     success = BBL_CopyOriginalScreen( screen )
  324.                                         A0
  325.  
  326.     BOOL BBL_CopyOriginalScreen( struct Screen * )
  327.  
  328.     FUNCTION
  329.   This function copies the contents of the original first screen to the
  330.   screen. It is only useful for screen-cloning modules, which want
  331.   to rebuild their blankscreen from time to time.
  332.  
  333.     INPUTS
  334.     screen - Pointer to an open screen.
  335.            (It is safe, to pass a NULL here -> nothing will be done)
  336.  
  337.     RESULTS
  338.   success - TRUE if the copy was successful, otherwise FALSE.
  339.  
  340.     SEE ALSO
  341.   BB.Crumble.c, BB.Melt.c, BB.Mosaic.c, BB.Tiles.c
  342.  
  343. blitzblank.library/BBL_EndDBuf                 blitzblank.library/BBL_EndDBuf
  344.  
  345.     NAME
  346.     BBL_EndDBuf -- Indicates the end of double-buffering.
  347.  
  348.     SYNOPSIS
  349.     BBL_EndDBuf( handle )
  350.                    A0
  351.  
  352.     void BBL_EndDBuf( ULONG )
  353.  
  354.     FUNCTION
  355.   Use this function at the end of your blank()-function to free all memory,
  356.   that was reserved by InitDBuf(). You should call BBL_ShowBitMap() with
  357.   the original bitmap, before calling this function. For an example of
  358.   how to use the library's double-buffering, look at the docs to
  359.   BBL_ShowBitMap().
  360.  
  361.     INPUTS
  362.     handle - An internal handle, as returned by BBL_InitDBuf().
  363.            (It is safe, to pass a 0 here -> nothing will be done)
  364.  
  365.     RESULTS
  366.  
  367.     SEE ALSO
  368.   BBL_AllocDBufBitMap(), BBL_InitDBuf(), BBL_ShowBitMap(),
  369.   BB.AmigaSign.c, BB.Clock.c, BB.Spot.c
  370.  
  371. blitzblank.library/BBL_FadeDown               blitzblank.library/BBL_FadeDown
  372.  
  373.     NAME
  374.     BBL_FadeDown -- Reduce the brightness of a screen smoothly.
  375.  
  376.     SYNOPSIS
  377.     success = BBL_FadeDown( screen, final, delay )
  378.                               A0      D0     D1
  379.  
  380.     BOOL BBL_FadeDown( struct Screen *, UBYTE, UBYTE )
  381.  
  382.     FUNCTION
  383.   Reduces the brightness of the screen to final percent. It does a
  384.   smooth fadeout with a configurable delay.
  385.   This function is V39-aware and so will fade smoother, if V39 is
  386.   available.
  387.  
  388.     INPUTS
  389.     screen - Pointer to an open screen.
  390.            (It is safe, to pass a NULL here -> nothing will be done)
  391.  
  392.     final  - remaining brightness in percent.
  393.  
  394.   delay  - 0 for immediate reduction, 1-20 for fading (20=extra slow).
  395.  
  396.     RESULTS
  397.   success - FALSE, if CTRL-C was sent during the fading. If all
  398.             went well, it returns TRUE.
  399.  
  400.     SEE ALSO
  401.   BB.Fade.c, BB.Melt.c, BB.Mosaic.c, BB.Crumble.c, BB.Tiles.c
  402.  
  403. blitzblank.library/BBL_FreeBitMap           blitzblank.library/BBL_FreeBitMap
  404.  
  405.     NAME
  406.     BBL_FreeBitMap -- Free a bitmap, that was allocated with
  407.                     BBL_AllocBitMap() or BBL_AllocDBufBitMap().
  408.  
  409.     SYNOPSIS
  410.     BBL_FreeBitMap( bitmap )
  411.                     A0
  412.  
  413.     void BBL_FreeBitMap( struct BitMap * )
  414.  
  415.     FUNCTION
  416.   Frees all RAM allocated by BBL_AllocBitMap() or BBL_AllocDBufBitMap().
  417.  
  418.     INPUTS
  419.     bitmap - Pointer to a bitmap, that was allocated with BBL_AllocBitMap()
  420.            or BBL_AllocDBufBitMap().
  421.            (It is safe, to pass a NULL here -> nothing will be done)
  422.  
  423.     RESULTS
  424.  
  425.     SEE ALSO
  426.   BBL_AllocBitMap(), BBL_AllocDBufBitMap(),
  427.   BB.AmigaSign.c, BB.Clock.c, BB.Spot.c
  428.  
  429. blitzblank.library/BBL_FreeRastPort       blitzblank.library/BBL_FreeRastPort
  430.  
  431.     NAME
  432.     BBL_FreeRastPort -- Free a rastport, that was allocated with
  433.                       BBL_AllocRastPort().
  434.  
  435.     SYNOPSIS
  436.     BBL_FreeRastPort( rastport )
  437.                        A0
  438.  
  439.     void BBL_FreeRastPort( struct RastPort * )
  440.  
  441.     FUNCTION
  442.   Frees all RAM allocated by BBL_AllocRastPort().
  443.  
  444.     INPUTS
  445.     rastport - Pointer to a rastport, that was allocated with
  446.              BBL_AllocRastPort().
  447.              (It is safe, to pass a NULL here -> nothing will be done)
  448.  
  449.     RESULTS
  450.  
  451.     SEE ALSO
  452.   BBL_AllocRastPort(), BB.Clock.c, BB.Spot.c
  453.  
  454. blitzblank.library/BBL_GetDarkestPen     blitzblank.library/BBL_GetDarkestPen
  455.  
  456.     NAME
  457.     BBL_GetDarkestPen -- Search for the darkest of a screen's colors.
  458.  
  459.     SYNOPSIS
  460.     pen = BBL_GetDarkestPen( screen )
  461.                                A0
  462.  
  463.     LONG BBL_GetDarkestPen( struct Screen * )
  464.  
  465.     FUNCTION
  466.   Scans the screen's colors and gives back the darkest color available.
  467.   This function is V39-aware and so will use the V39-function FindColor(),
  468.   if V39 is available.
  469.  
  470.     INPUTS
  471.     screen - Pointer to an open screen.
  472.            (It is safe, to pass a NULL here -> nothing will be done)
  473.  
  474.     RESULTS
  475.   pen - The pennumber of the darkest color.
  476.  
  477.     SEE ALSO
  478.   BB.Crumble.c, BB.Melt.c
  479.  
  480. blitzblank.library/BBL_GetString             blitzblank.library/BBL_GetString
  481.  
  482.     NAME
  483.     BBL_GetString -- Get a localized string.
  484.  
  485.     SYNOPSIS
  486.     resultstring = BBL_GetString( num, string )
  487.                                    D0    D1
  488.  
  489.     STRPTR BBL_GetString( UWORD, STRPTR )
  490.  
  491.     FUNCTION
  492.   If locale.library is available and it finds the locale string with number
  493.   num, then it returns a pointer to it. If something goes wrong, it just
  494.   returns the given string back.
  495.  
  496.     INPUTS
  497.   num    - number of the searched string.
  498.  
  499.   string - default string (english).
  500.  
  501.     RESULTS
  502.   resultstring - The searched string if it was found, otherwise the
  503.                  given string.
  504.  
  505.     SEE ALSO
  506.   All modules
  507.  
  508. blitzblank.library/BBL_InitDBuf               blitzblank.library/BBL_InitDBuf
  509.  
  510.     NAME
  511.     BBL_InitDBuf -- Initialize the library's double-buffering.
  512.  
  513.     SYNOPSIS
  514.     handle = BBL_InitDBuf( screen, bitmap )
  515.                              A0      A1
  516.  
  517.     ULONG BBL_InitDBuf( struct Screen *, struct BitMap * )
  518.  
  519.     FUNCTION
  520.   Initializes the library's double-buffering functions. Before you
  521.   can use BBL_ShowBitMap(), you MUST call this function. It will then
  522.   decide, which method of double-buffering will be used by
  523.   BBL_ShowBitMap(). If the system is running at least V39 and the
  524.   2 bitmaps (screen->RastPort.BitMap and bitmap) have the same
  525.   flags (BOTH interleaved ot BOTH non-interleaved), then the
  526.   double-buffering will be much faster. So, only request
  527.   an interleaved screen (and an interleaved bitmap) if you really
  528.   need them, because it is not sure, that the OS is able to
  529.   give them to you. If not, you could end up with an interleaved
  530.   screen and a non-interleaved bitmap. That would lead to
  531.   the slower double-buffering method. For an example of
  532.   how to use the library's double-buffering, look at the docs to
  533.   BBL_ShowBitMap().
  534.  
  535.     INPUTS
  536.   screen - The screen, which will be double-buffered.
  537.            (It is safe, to pass a NULL here -> nothing will be done)
  538.  
  539.   bitmap - The 2nd BitMap, which will be used for double-buffering.
  540.            It should be allocated with BBL_AllocDBufBitMap().
  541.            (It is safe, to pass a NULL here -> nothing will be done)
  542.  
  543.     RESULTS
  544.   handle - An internal handle, which must be passed also to BBL_ShowBitMap()
  545.            and BBL_EndDBuf() or 0, if the call failed.
  546.  
  547.     SEE ALSO
  548.   BBL_AllocDBufBitMap(), BBL_ShowBitMap(), BBL_EndDBuf(),
  549.   BB.AmigaSign.c, BB.Clock.c, BB.Spot.c
  550.  
  551. blitzblank.library/BBL_ModuleRunning     blitzblank.library/BBL_ModuleRunning
  552.  
  553.     NAME
  554.     BBL_ModuleRunning -- Tell BlitzBlank, that the module is running.
  555.  
  556.     SYNOPSIS
  557.     BBL_ModuleRunning()
  558.  
  559.     void BBL_ModuleRunning( void )
  560.  
  561.     FUNCTION
  562.   This function indicates the start of the main-loop of the module. It
  563.   should be called right before the main-loop and right after a check
  564.   for CTRL-C and AFTER bringing your screen to the front!!!
  565.   At this time, the library will then set the user-defined task-priority
  566.   for the module.
  567.  
  568.     INPUTS
  569.  
  570.     RESULTS
  571.  
  572.     SEE ALSO
  573.   All modules
  574.  
  575. blitzblank.library/BBL_RainbowPalette   blitzblank.library/BBL_RainbowPalette
  576.  
  577.     NAME
  578.     BBL_RainbowPalette -- Create a rainbow palette.
  579.  
  580.     SYNOPSIS
  581.     BBL_RainbowPalette( screen, lowreg, highreg )
  582.                         A0      D0       D1
  583.  
  584.     void BBL_RainbowPalette( struct Screen *, ULONG, ULONG )
  585.  
  586.     FUNCTION
  587.   Creates a rainbow-like palette for the given screen. Be careful: YOU
  588.   are responsible, that lowreg and highreg really exist in the ViewPort
  589.   of the screen. Also, highreg must be greater or equal lowreg.
  590.   Example (creates a complete rainbow palette, except color 0):
  591.   BBL_RainbowPalette (screeninfo->bbscreen,1,(1L<<screeninfo->depth)-1);
  592.  
  593.     INPUTS
  594.     screen  - Pointer to the screen.
  595.             (It is safe, to pass a NULL here -> nothing will be done)
  596.  
  597.   lowreg  - First color register to use.
  598.  
  599.   highreg - Last color register to use.
  600.  
  601.     RESULTS
  602.  
  603.     SEE ALSO
  604.   BB.Lines.c
  605.  
  606. blitzblank.library/BBL_RemainingTime     blitzblank.library/BBL_RemainingTime
  607.  
  608.     NAME
  609.     BBL_RemainingTime -- Returns the remaining blank time.
  610.  
  611.     SYNOPSIS
  612.     rem = BBL_RemainingTime()
  613.  
  614.     ULONG BBL_RemainingTime( void )
  615.  
  616.     FUNCTION
  617.   Tells you the remaining time in 1/50 seconds for your module. Of course this
  618.   only works, if BlitzBlank's Randomtime is greater than 0. If not, this
  619.   function returns always $ffffff. This function is useful, if you want to do
  620.   something in your module right BEFORE it gets the CTRL-C signal from
  621.   BlitzBlank, for example fading the screen to black.
  622.  
  623.     INPUTS
  624.  
  625.     RESULTS
  626.   rem = Remaining time in 1/50 seconds or $ffffff.
  627.  
  628.     SEE ALSO
  629.   BB.Fountain, BB.Noise
  630.  
  631. blitzblank.library/BBL_ScreenAvailable blitzblank.library/BBL_ScreenAvailable
  632.  
  633.     NAME
  634.     BBL_ScreenAvailable -- Checks the availability of a screen.
  635.  
  636.     SYNOPSIS
  637.     success = BBL_ScreenAvailable( screen )
  638.                                      A0
  639.  
  640.     BOOL BBL_ScreenAvailable( struct Screen * )
  641.  
  642.     FUNCTION
  643.   Searches the screen-list for the given screen. This should be called,
  644.   before changing the screen's colormap (if you manipulate the first
  645.   screen directly like BB.Fade) or if you want to refresh the blankscreen
  646.   with the contents of the original first screen (like some screen-
  647.   cloning modules after a while do).
  648.  
  649.     INPUTS
  650.     screen - Pointer to the searched screen.
  651.            (It is safe, to pass a NULL here -> nothing will be done)
  652.  
  653.     RESULTS
  654.   success - If the screen was found, it returns TRUE. That means, the
  655.             screen is still open. Otherwise, it returns FALSE.
  656.  
  657.     SEE ALSO
  658.   BB.Fade.c, BB.Melt.c, BB.Mosaic.c, BB.Crumble.c
  659.  
  660. blitzblank.library/BBL_SendMessage         blitzblank.library/BBL_SendMessage
  661.  
  662.     NAME
  663.     BBL_SendMessage -- Send the BB_Message to BlitzBlank.
  664.  
  665.     SYNOPSIS
  666.     success = BBL_SendMessage( message, portname )
  667.                                  A0       D0
  668.  
  669.     BOOL BBL_SendMessage( struct BB_Message *, STRPTR )
  670.  
  671.     FUNCTION
  672.   Sends the initialized message to the portname. The portname is given
  673.   as argument #2 to the module. This function has to be called by
  674.   the module, after filling the message, in all 3 cases (BLANK, CONFIG,
  675.   INFO).
  676.  
  677.     INPUTS
  678.     message  - Pointer to a struct BB_Message.
  679.  
  680.   portname - The portname from CLI-argument #2.
  681.  
  682.     RESULTS
  683.   success - Returns TRUE if everything went well, otherwise returns FALSE.
  684.             If the result was TRUE, then all the GUI-objects and the
  685.             screeninfo are filled.
  686.  
  687.     SEE ALSO
  688.   All modules
  689.  
  690. blitzblank.library/BBL_ShowBitMap           blitzblank.library/BBL_ShowBitMap
  691.  
  692.     NAME
  693.     BBL_ShowBitMap -- Show a bitmap in a screen (do double-buffering).
  694.  
  695.     SYNOPSIS
  696.     BBL_ShowBitMap( screen, bitmap, handle )
  697.                       A0      A1      A2
  698.  
  699.     void BBL_ShowBitMap( struct Screen *, struct BitMap *, ULONG )
  700.  
  701.     FUNCTION
  702.   Shows the bitmap at the next vertical blank. You must have called
  703.   BBL_InitDBuf() before you can use this function. Currently, it
  704.   knows two methods of double-buffering. Is uses them depending
  705.   on the OS-version and the flags of the screen and the bitmap
  706.   (see doc to BBL_InitDBuf()). The function itself waits for the
  707.   next vertical blank after changing the bitmap, so you don't have
  708.   to call WaitTOF() yourself.
  709.   NOTE: This function doesn't change the screen->RastPort.BitMap
  710.         pointer, so if you want to draw to the 2nd bitmap via a
  711.         rastport, you have to set this pointer to the drawing bitmap
  712.         by yourself.
  713.   Here is an example, of how to do double-buffering with this library
  714.   (without error-checking):
  715.  
  716.   struct Screen *myscreen;
  717.   struct BitMap *bm[2];
  718.   int actual=1;
  719.   ULONG dbufhandle;
  720.  
  721.   bm[0]=myscreen->RastPort.BitMap;
  722.   bm[1]=BBL_AllocDBufBitMap (myscreen);
  723.  
  724.   dbufhandle=BBL_InitDBuf (myscreen,bm[1]);
  725.   myscreen->RastPort.BitMap=bm[actual];
  726.  
  727.   loop
  728.   {
  729.     /* draw into bm[actual] or &myscreen->RastPort */
  730.  
  731.     BBL_ShowBitMap (myscreen,bm[actual],dbufhandle);
  732.     actual=1-actual;
  733.     myscreen->RastPort.BitMap=bm[actual];
  734.   }
  735.   BBL_ShowBitMap (myscreen,bm[0],dbufhandle);
  736.   myscreen->RastPort.BitMap=bm[0];
  737.   BBL_EndDBuf (dbufhandle);
  738.   BBL_FreeBitMap (bm[1]);
  739.  
  740.     INPUTS
  741.   screen - The screen, where the bitmap will be shown.
  742.  
  743.   bitmap - The bitmap, that will be shown. You should allocate it with
  744.            BBL_AllocDBufBitMap().
  745.  
  746.   handle - An internal handle, as returned by BBL_InitDBuf().
  747.            (It is safe, to pass a 0 here -> nothing will be done)
  748.  
  749.     RESULTS
  750.  
  751.     SEE ALSO
  752.   BBL_AllocDBufBitMap(), BBL_InitDBuf(), BBL_EndDBuf(),
  753.   BB.AmigaSign.c, BB.Clock.c, BB.Spot.c
  754.  
  755. blitzblank.library/BBL_UnBlankMouse       blitzblank.library/BBL_UnBlankMouse
  756.  
  757.     NAME
  758.     BBL_UnBlankMouse -- Unblank the mouse on your own screen.
  759.  
  760.     SYNOPSIS
  761.     BBL_UnBlankMouse( window )
  762.                         A0
  763.  
  764.     void BBL_UnBlankMouse( struct Window * )
  765.  
  766.     FUNCTION
  767.   Clears the pointer and closes the window, opened by BBL_BlankMouse().
  768.   If you get your screen from BlitzBlank, you will never need this
  769.   function.
  770.  
  771.     INPUTS
  772.     window - Pointer to a window, as returned from BBL_BlankMouse().
  773.            (It is safe, to pass a NULL here -> nothing will be done)
  774.  
  775.     RESULTS
  776.  
  777.     SEE ALSO
  778.   BBL_BlankMouse(), BB.Tiles.c
  779.  
  780.