@DATABASE QBLITLIB
@Author Conversion program
@NODE OVERVIEW "Overview of QBLITLIB"

                                  @{b}@{u}Overview@{ub}@{uu}


                          An Acid Software Library

                         Converted to AmigaGuide by

                            Red When Excited Ltd

                 Used with the permission of Acid Software

          Edited, fixed and cleaned by Toby Zuijdveld 27/02/1999.
                       mailto:hotcakes@abacus.net.au



@ENDNODE OVERVIEW

@NODE Queue "QBLITLIB"

@{fg shine}Statement: Queue@{fg text}
--------------------------------------------------------------------------------
Modes  : 
Syntax : Queue Queue#,Max Items

The Queue command creates a queue object for use with the QBlit and 
UnQueue commands. What is a queue? Well, queues (in the Blitz 2 sense) 
are used for the purpose of multi-shape animation. Before going into 
what a queue is, let's have a quick look at the basics of 
animation.

Say you want to get a group of objects flying around the screen. To 
achieve this, you will have to construct a loop similar to the 
following:

Step 1: Start at the first object
Step 2: Erase the object from the display
Step 3: Move the object
Step 4: Draw the object at it's new location on the display 
Step 5: If there are any more objects to move, go on to the next object and then go to step 2, else...
Step 6: go to step 1

Step 2 is very important, as if it is left out, all the objects will 
leave trails behind them! However, it is often very cumbersome to have 
to erase every object you wish to move. This is where queues are of 
use.

Using queues, you can 'remember' all the objects drawn through a loop, 
then, at the end of the loop (or at the start of the next loop), erase 
all the objects 'remembered' from the previous loop. Lets have a look 
at how this works:

Step 1: Erase all objects remembered in the queue
Step 2: Start at the first object
Step 3: Move the object
Step 4: Draw the object at it's new location, and add it to the end of the queue
Step 5: If there are any objects left to move, go on to the next object, then go to step 3; else...
Step 6: Go to step 1

This is achieved quite easily using Blitz 2's queue system. The UnQueue 
command performs step 1, and the QBlit command performs step 4.
.
Queues purpose is to initialize the actual queue used to remember 
objects in. Queue must be told the maximum number of items the queue is 
capable of remembering, which is specified in the Max Items 
parameter.


@ENDNODE Queue

@NODE QBlit "QBLITLIB"

@{fg shine}Statement: QBlit@{fg text}
--------------------------------------------------------------------------------
Modes  : 
Syntax : QBlit Queue#,Shape#,X,Y[,Excessonoff]

QBlit performs similarly to Blit, and is also used to draw a shape onto 
the currently used bitmap. Where QBlit differs, however, is in that it 
also remembers (using a queue) where the shape was drawn, and how big 
it was. This allows a later UnQueue command to erase the drawn 
shape.

Please refer to the Queue command for an explanation of the use of 
queues.

The optional Excessonoff parameter works identically to the Excessonoff 
parameter used by the Blit command. Please refer to the Blit command 
for more information on this parameter.


@ENDNODE QBlit

@NODE UnQueue "QBLITLIB"

@{fg shine}Statement: UnQueue@{fg text}
--------------------------------------------------------------------------------
Modes  : 
Syntax : UnQueue Queue#[,BitMap#]

UnQueue is used to erase all 'remembered' items in a queue. Items are 
placed in a queue by use of the QBlit command. Please refer to Queue 
for a full explanation of queues and their usage.

An optional BitMap# parameter may be supplied to cause items to be 
erased by way of 'replacement' from another bitmap, as opposed to the 
normal 'zeroing out' erasing.


@ENDNODE UnQueue

@NODE QBlitMode "QBLITLIB"

@{fg shine}Statement: QBlitMode@{fg text}
--------------------------------------------------------------------------------
Modes  : 
Syntax : QBlitMode BLTCON0

QBlitMode allows you to control how the blitter operates when QBlitting 
shapes to bitmaps. Please refer to BlitMode for more information on 
this command.


@ENDNODE QBlitMode

@NODE FlushQueue "QBLITLIB"

@{fg shine}Statement: FlushQueue@{fg text}
--------------------------------------------------------------------------------
Modes  : 
Syntax : FlushQueue Queue#

FlushQueue will force the specified queue object to be 'emptied', 
causing the next UnQueue command to have no effect.
@ENDNODE FlushQueue

@NODE MAIN "QBLITLIB"

.-----------------------------------------------------------------------------.
|                                  @{b}QBLITLIB@{ub}                                   |
`-----------------------------------------------------------------------------'

                             @{"     Overview     " link OVERVIEW}

                               Command Index                                

                                @{" FlushQueue " link FlushQueue}
                                @{" QBlit      " link QBlit}
                                @{" QBlitMode  " link QBlitMode}
                                @{" Queue      " link Queue}
                                @{" UnQueue    " link UnQueue}

@ENDNODE MAIN