-----------------------------------------------------------------------------


    ۿ                                             ۿ  ۿ
    ۿ  ۿۿ  ۿ  ۿ ۿۿ ۿ
    ۳   ۿ   ۿ   ۿ۳     ۳ ۳
    ۳    ۿ ۳    ۿ          ۳   ۳   ۿ۳ ۿ
    ۳    ۳ ۳  ۿ     ۳     ۿ   ۳   ۳     ۳     ۳
    ۿۿ ۿۿ    ۳    ۿ
               

                          version 1.31  23/11/1998


            DirectQB: a Game Programming Library for QuickBasic 4.5
      (but it could be easily adapted to your own programming language!)

                 by Angelo Mottola - Enhanced Creations 1998



-----------------------------------------------------------------------------

What's new in version 1.31

Here's the list of new features:

- Blended triangle and texture mapped triangle drawing; textures can be up
  to 128x128 pixels, and the "hotspot" of each vertex is totally customizable
- Most of the graphical functions have been accelerated a bit
- DQBloadRawSound now works

Now, here's the list of the new functions, including old ones which have been
modified:
DQBellipse, DQBput, DQBsPut, DQBbPut, DQBrPut, DQBxPut, DQBtri, DQBbtri,
DQBgtri, DQBttri, DQBinstallSB, DQBloadRawSound, DQBinitVGA, DQBinitText

Check out part 2 of this manual for details on each function. Also, as the
library still has limitations, be sure to check out section 1.7.

Of course DirectQB is still under development, so expect new versions in the
future. My actual goals are:

 FM or (better) MIDI music (without external drivers such as SBMIDI)
 Free EMS for the user to store any kind of data


=============================================================================


TABLE OF CONTENTS

1     Introduction to DirectQB
  1.1   Legal stuff
  1.2   What is DirectQB
  1.3   System requirements
  1.4   Features
  1.5   Installing the library
  1.6   Basic concepts
  1.7   Limits of the library
2     Functions reference
        DQBasc FUNCTION
        DQBbox SUB
        DQBboxf SUB
        DQBbPut SUB
        DQBbtri SUB
        DQBclearLayer SUB
        DQBclose SUB
        DQBcopyLayer SUB
        DQBcopyTransLayer SUB
        DQBcreateBMap FUNCTION
        DQBdir$ FUNCTION
        DQBdrive$ FUNCTION
        DQBellipse SUB
        DQBemsSeg FUNCTION
        DQBfadeIn SUB
        DQBfadeStepIn SUB
        DQBfadeStepTo SUB
        DQBfadeTo SUB
        DQBfilterBox SUB
        DQBfindCol FUNCTION
        DQBfPut SUB
        DQBget SUB
        DQBgetBMap FUNCTION
        DQBgetCol SUB
        DQBgetPal SUB
        DQBgtri SUB
        DQBinit FUNCTION
        DQBinitText SUB
        DQBinitVGA SUB
        DQBinkey$ FUNCTION
        DQBinstallKeyboard SUB
        DQBinstallSB FUNCTION
        DQBinUse FUNCTION
        DQBjoyDetected FUNCTION
        DQBjoyFire FUNCTION
        DQBjoyMove FUNCTION
        DQBkey FUNCTION
        DQBlen FUNCTION
        DQBline SUB
        DQBloadBMap FUNCTION
        DQBloadLayer FUNCTION
        DQBloadRawSound FUNCTION
        DQBloadSound FUNCTION
        DQBmouseDetected FUNCTION
        DQBmouseHide SUB
        DQBmouseLB FUNCTION
        DQBmouseRB FUNCTION
        DQBmouseShow SUB
        DQBmouseX FUNCTION
        DQBmouseY FUNCTION
        DQBnumDrives FUNCTION
        DQBpalOff SUB
        DQBpath$ FUNCTION
        DQBpauseSound SUB
        DQBplaySound SUB
        DQBpoint FUNCTION
        DQBpollJoy SUB
        DQBprint SUB
        DQBprints SUB
        DQBpset SUB
        DQBput SUB
        DQBreadBit FUNCTION
        DQBreadKey FUNCTION
        DQBremoveKeyboard SUB
        DQBremoveSB SUB
        DQBresetBit FUNCTION
        DQBresetJoy SUB
        DQBresetMouse SUB
        DQBresumeSound SUB
        DQBrPut SUB
        DQBsaveBMap FUNCTION
        DQBsaveLayer FUNCTION
        DQBscroll SUB
        DQBsetBIOSfont SUB
        DQBsetBit FUNCTION
        DQBsetBMap SUB
        DQBsetClipBox SUB
        DQBsetCol SUB
        DQBsetDrive SUB
        DQBsetFont SUB
        DQBsetMousePos SUB
        DQBsetMouseRange SUB
        DQBsetMouseShape SUB
        DQBsetMouseSpeed SUB
        DQBsetPal SUB
        DQBsetSamplingRate SUB
        DQBsetSolidPut SUB
        DQBsetSolidText SUB
        DQBsetTextBackCol SUB
        DQBsetTextStyle SUB
        DQBsetTextureSize SUB
        DQBsetTransPut SUB
        DQBsetTransText SUB
        DQBsetVoiceVol SUB
        DQBsetVolume SUB
        DQBshiftLeft FUNCTION
        DQBshiftRight FUNCTION
        DQBsize FUNCTION
        DQBsort SUB
        DQBsPut SUB
        DQBstopVoice SUB
        DQBtoggleBit FUNCTION
        DQBtri SUB
        DQBttri SUB
        DQBver FUNCTION
        DQBwait SUB
        DQBwaitKey SUB
        DQBxPut SUB
APPENDIX A    Library constants
APPENDIX B    Keyboard scancodes list
APPENDIX C    Palette, cursor, font and blender map data format
APPENDIX D    Known bugs
APPENDIX E    Versions history
Credits and final words

-----------------------------------------------------------------------------


=============================================================================
1.  INTRODUCTION TO DIRECTQB
=============================================================================


-----------------------------------------------------------------------------
1.1 - Legal stuff
-----------------------------------------------------------------------------

THIS SOFTWARE FOLLOWS THE RULES OF THE FREEWARE CONCEPT: YOU CAN SHARE IT
WITH YOUR FRIENDS, AND YOU'RE ENCOURAGED IN DOING SO, BUT THE AUTHOR IS ANYWAY
NOT LIABLE FOR ANY DAMAGES CAUSED BY THE USE OF THIS LIBRARY. IT IS NOT
COPYRIGHTED, BUT IF YOU WANT TO MODIFY IT, PLEASE TELL ME FIRST.
IF YOU USE THE DIRECTQB ROUTINES, PLEASE GIVE ME SOME CREDITS IN YOUR PROGRAM.


-----------------------------------------------------------------------------
1.2 - What is DirectQB
-----------------------------------------------------------------------------

DirectQB is a game programming library entirely written in assembly 386 for
QuickBasic 4.5. It has been mainly coded to fill the void into the weak
graphics, input and sound capabilities of QB; it works in screen mode 13h
(320x200 with 256 colors - the common SCREEN 13 for QB), supports keyboard,
mouse and joysticks as input devices, and has a built-in sound engine that
works with almost any SB. It has really lots of features, as you'll discover
reading this manual...


-----------------------------------------------------------------------------
1.3 - System requirements
-----------------------------------------------------------------------------

First of all you'll need a copy of QuickBasic 4.5. DirectQB is a quicklibrary,
and therefore is made to run only under this programming environment.
As DirectQB has been entirely coded in assembly using several advanced 386
instructions, a 386 or better CPU is required. EMS is also needed in order
to have off-screen buffers, the so named "layers", as we'll see later.
For every layer you need 64 KB of free EMS memory; if you don't know what is
EMS, or you've problems with it, try adding these lines at the beginning of
your CONFIG.SYS file:

DEVICE=C:\WINDOWS\HIMEM.SYS
DEVICE=C:\WINDOWS\EMM386.EXE <amount> RAM

Where <amount> must be a number specifying the amount of EMS memory in KB to
make available under DOS. Here I also suppose you have Windows 95 under the
C:\WINDOWS directory. So to have 4 MB of free EMS memory, you should add:

DEVICE=C:\WINDOWS\EMM386.EXE 4000 RAM

That's all. After adding those lines, reboot your system, and EMS will be
available, and ready to be used by the library.

To work with the sound engine, you'll need at least a SoundBlaster 2.0
compatible sound card; DirectQB uses autoinit mode for DMA transfers, so
a DSP version 2.00 (contained in the SB 2.0) or better is required. If you
use DQBinstallSB with autodetection mode, you must have set the BLASTER
environmental variable. Add the following line to your AUTOEXEC.BAT file:

SET BLASTER=Aaaa Ii Dd

Where "aaa" is the exadecimal base address of your sound card (commonly 220),
"i" is the IRQ number and "d" is the DMA channel to be used. A common setting
would be like this:

SET BLASTER = A220 I7 D1

which sets the base address as 220h, IRQ 7 and DMA channel 1. There are other
settings for the BLASTER variable, such as H and T, but I'll not explain them
here, as they're not required for our purposes.

To create a blender map to use with the blending graphical functions, you'll
also need other additional 64K of free CONVENTIONAL memory. The blender map is
automatically stored in base memory to speed things up; the allocation and
deallocation of it is hidden to the user, who must just be sure to have enough
free available memory.

Well, as by now there are no more requirements to run DirectQB.


-----------------------------------------------------------------------------
1.4 - Features
-----------------------------------------------------------------------------

DirectQB version 1.3 has the following features:

Graphical features:

- Supports 320x200 with 256 colors video mode, with almost unlimited number
  of off-screen buffers stored into EMS memory. EMS is automatically handled
- All the functions act on the screen as well as on the off-screen buffers
- Several drawing primitives, including pset, line, ellipse, box and full box
- Fast sprite handling functions, compatible with standard GET and PUT, also
  with support for sprite scaling, roto-zooming and translucency, and direct
  sprite drawing from EMS without requiring any external QB array
- Color blending routines to handle a customizable blender map, allowing to
  create any color combination
- Clipping for almost all the graphical functions
- Loads and saves images in BSAVE, BMP and PCX format
- Font routines with customizable font set, non-fixed sized fonts support and
  custom styles, such as bold, italic, underlined, or a combination of them
- Smooth palette handling with routines to fade the current palette into any
  new one as well as into any specified color
- Multidirectional scrolling
- Transparent screen copy for parallax scrolling effects
- Very fast flat-shaded or gouraud-shaded triangle drawing primitives

Input features:

- Custom keyboard interrupt handler that allows to know the state (pressed or
  released) of any key at any time
- Several keyboard handling functions working under this IRQ handler, to read
  a key, to get the ascii code from its scancode, and more
- Fast and easy to use joystick routines, with auto detection and auto
  calibration, with support for 1 or 2 2-button joysticks or 1 4-button joypad
- Mouse handler: the mouse variables (coordinates and buttons status) are
  automatically updated when you move the mouse, allowing you to know the
  actual mouse state at any time without calling other routines
- Mouse routines to change the cursor shape, mouse range, speed and position

Sound features:

- IRQ driven sound engine for easy sounds playback via DMA transfers
- Loads and plays sound effects directly from EMS
- Supports only 8-bit mono WAV files up to 22000 Hz
- Customizable number of channels, from 1 up to 32, for up to 32 sound effects
  simultaneously playing
- Customizable volume setting for each of the voices
- Customizable master volume setting and sampling rate (from 4 up to 22 KHz)

Misc features:

- Bit handling routines, including read/set/reset/toggle bit, shift left and
  right
- Routine to find the color in the current palette that best fits with the
  specified red, green and blue hues
- Directory scanning routines
- Integer array sorting routine


-----------------------------------------------------------------------------
1.5 - Installing the library
-----------------------------------------------------------------------------

The DirectQB library is given into different formats. You should have these
files into the library directory:

DIRECTQB.ASM    - Assembly source code
DIRECTQB.OBJ    - Library object file (compiled with Microsoft MASM 5.1)
DQB.LIB         - Library file
DQB.QLB         - Runtime quicklibrary file

To load the library under QuickBasic, run QB at the DOS prompt by typing:

QB/LDQB

The IDE will appear, and you'll be able to use the DirectQB functions.

If you've problems running the quicklibrary, try building it again, by
following these simple steps (it is supposed that you have a working copy
of QuickBasic 4.5 under the C:\QB45 directory, and you're currently under
the path where you've unzipped the library)

At the DOS prompt, type:

C:\QB45\LINK /Q C:\QB45\QB.LIB DIRECTQB,ASMDQB.QLB,,C:\QB45\BQLB45.LIB

and

C:\QB45\LIB ASMDQB.LIB C:\QB45\QB.LIB +DIRECTQB;

All should go ok, and you should have the files ASMDQB.QLB and ASMDQB.LIB
into the library directory. What you've just typed has linked the library
object file together with the default QB quicklibrary (the one which holds
the code for the ABSOLUTE, INTERRUPTX and other procedures), to create the
LIB and QLB files you've got. In this way you can still use the functions
of the default quicklibrary while using DirectQB.
Another step and the library will be ready...

To simplify the calls to some DirectQB functions, I've written a small QB
file named DQBCALLS.BAS; what we're going to do is to link this BAS file with
the library files we've just created.
Load QuickBasic by typing this:

QB/LASMDQB

And then choose the "Load file" option from the File menu (I have the Italian
QB 4.5 version, so I don't know the right option translation; anyway it's the
option to insert a file into the current project and NOT the option to open
a new file loosing the one in memory). Choose DQBCALLS.BAS from the file list.
Now choose the "Create library" option from the Run menu; type "DQB" as the
new library name and hit enter. When the operation is completed, quit QB.
You can now delete the ASMDQB.LIB and ASMDQB.QLB files, as they'll never be
used again; congratulations, you've just built the DirectQB library.

At this point you'll be able to run the library without problems; if you want
to link it with other libraries, follow these steps:

C:\QB45\LINK /Q DQB <otherlib>.LIB, <newlib>.QLB,,C:\QB45\BQLB45.LIB

and

C:\QB45\LIB <newlib>.LIB DQB.LIB <otherlib>.LIB;

Where <otherlib> is the other library you want to link with DirectQB, and
<newlib> is the new library filename you want to create.


-----------------------------------------------------------------------------
1.6 - Basic concepts
-----------------------------------------------------------------------------

The DirectQB library makes an extensive use of the EMS memory to store off-
screen buffers, named "layers", plus sounds. A layers is basically a buffer
where you act as you do with the screen. You can draw pixels on it, as well as
using all the graphical functions of this library. The EMS memory is
automatically handled for you, so all you have to do when calling every
graphical function is to specify a layer where to act. To draw something
directly to the screen, just use layer number 0 (there's also a constant named
VIDEO, as specified into APPENDIX A). You can specify the number of layers to
allocate by calling the DQBinit function, as well as the number of sounds to
allocate space for in EMS; DQBinit must be ALWAYS called before calling any
other function of this library, or you'll probably crash your system. 
Remember also to call DQBclose just before ending your programs; this will
free previously allocated memory and it'll turn off the custom keyboard
handler and the sound engine if they were on.

Other than this, you should also keep in mind the following things:

 To speed things up, a lot of checks are skipped, so for example if you
  initialize the library with 3 extra layers, DO NOT refer to layer -1 or 4!

 Every graphical function that draws something, except DQBbox, DQBboxf,
  DQBfPut and DQBfilterBox supports clipping; this means that every pixel that
  lies outside the current clipping box will not be drawn. Clipping box is set
  at startup (when calling DQBinit) to (0,0)-(319,199), and it can be changed
  at any time by calling the DQBsetClipBox function.

 The sprite data format for DQBget, DQBput, DQBfPut, DQBsPut, DQBrPut and
  DQBbPut is the same used by the standard GET and PUT statement; the
  advantage of using DirectQB functions is that they act on layers, they
  support clipping (except DQBfPut) and they're faster than GET and PUT...

 DQBxPut has the great advantage that it does not require you to store the
  sprites into an array and then to use this to draw it; this means you save
  extra memory for your application, but the bad thing is that DQBxPut is
  slower than normal DQBput, and it can handle only sprites with an height up
  to 50 pixels.

 The transparent color is color number 0 and cannot be changed.

 When calling a function that requires a box by passing the upper-left
  (x1,y1) and lower-right (x2,y2) corners, always remember that it must be
  x1<x2 and y1<y2, or you'll probably crash your system.

 By default, when calling DQBprint, the standard BIOS font is used. This can
  be changed by calling the DQBsetFont procedure; to restore the BIOS font,
  just call DQBsetBIOSfont.

 When referring to a color hue, the red, green and blue components must
  always be in the range 0-63, otherwise your system may crash.

 The blending functions requires a blender map. If the blender map has not
  been created by DQBcreateBMap, any calls to DQBsetBMap, DQBgetBMap,
  DQBloadBMap, DQBsaveBMap, DQBbPut or DQBfilterBox will do nothing; to
  create the blender map, you'll need 64K of free base memory. See
  DQBcreateBMap for details.

 Creating a blender map is not an easy job. It depends on the current palette
  and, of course, on what are your needs. Once created, it is suggested that
  you store your blender map into a file, so that you can load it at any time,
  without having to repeat the often slooow process.

 When the custom keyboard handler has been turned on by calling the
  DQBinstallKeyboard function, the standard QB functions that handle the
  keyboard should not be used, or you'll probably lock up your machine.
  These functions can be called again only after restoring the old keyboard
  handler by calling DQBremoveKeyboard.

 If you want to use the mouse, after calling DQBinit and entering the VGA
  mode, it is recommended that you call the DQBmouseReset function. This will
  set the default cursor shape and range.

 The mouse status (coordinates and buttons status) is automatically updated
  when you move it; you don't have to call any other function to update it.

 For the joystick it's different: before calling the DQBjoyMove and
  DQBjoyFire functions, you have to update the internal joystick variables
  by calling the DQBpollJoy function. This is a relatively slow operation,
  expecially if no joysticks are connected, so be warned.

 The sound engine still has limitations: it supports only 8-bit mono WAV
  files for now, and you need a sound card with a DSP 2.00 or better...
  
Well, I hope it's all.
One last thing: when coding your programs, remember to include this line at
the very beginning of your code:

'$INCLUDE:'DIRECTQB.BI'

This will include the file DIRECTQB.BI into your project; this file contains
function and constant declarations used by the library and is needed in order
to use it.


-----------------------------------------------------------------------------
1.7 - Limits of the library
-----------------------------------------------------------------------------

This library operates only in 320x200 with 256 colors video mode. I really
don't know if I'll ever release an hires/hicolor version... About the sound
engine, only 8-bit mono WAV files are supported for now.
The routines are written thinking about speed, so a lot of range checks are
skipped; this is wanted, so don't get hangry if your computer crashes, if it
does so, it's due to you.
About the joystick, DirectQB can handle up to two joysticks with 2 buttons
each, OR only 1 joystick with 4 buttons. In addition, the routines are mainly
written to handle joypads, so they work great with them. Analog joysticks are
also supported, but the routines will let you know only if the joystick has
been moved into a direction, and not the exact axis positions.
Fonts can have a maximum size of 8x8 pixels; the height is the same for all
the characters, while the width can vary. For the font format I strongly
suggest you to take a look at appendix C.


=============================================================================
2.  FUNCTIONS REFERENCE
=============================================================================


-----------------------------------------------------------------------------
DQBasc FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBasc(BYVAL ScanCode,BYVAL ShiftFlag)

Calling:

   ScanCode    Scancode of the character
   ShiftFlag   See function description

Returns:

An INTEGER value holding the ascii code number of specified character


Description:

This function is used to retrieve the ascii code of a specified character,
when you know its scancode. The problem is that for each scancode there can
be one or two associated characters... For example, the "A" character is
associated to the scancode number 30, but also "a" is associated to 30;
DirectQB has two internal tables holding all the possible combinations, so
you must specify in which table to search for specified character. That's the
purpose of the ShiftFlag parameter: if true, in our example you'll get an "A",
otherwise an "a".

Notes:

This function can be called even if the keyboard handler is off.


Example:

none


-----------------------------------------------------------------------------
DQBbox SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBbox (BYVAL Layer, BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2,
                    BYVAL Col)

Calling:

   Layer       Layer where to draw the box
   x1          Upper left corner x coordinate
   y1          Upper left corner y coordinate
   x2          Lower right corner x coordinate
   y2          Lower right corner y coordinate
   Col         Drawing color

Returns:

none


Description:

Draws an empty box on the given layer, with (x1,y1) and (x2,y2) as the upper
left and lower right corners, with Col color.

Notes:

This function is not affected by the clipping box, and no range checks are
done, so pay attention. In addition, remember that it must be x1<x2 and y1<y2.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

' Draws a box on the screen
DQBbox VIDEO, 0, 0, 319, 199, 15

' Ends the program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBboxf SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBboxf (BYVAL Layer, BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2,
                     BYVAL Col)

Calling:

   Layer       Layer where to draw the box
   x1          Upper left corner x coordinate
   y1          Upper left corner y coordinate
   x2          Lower right corner x coordinate
   y2          Lower right corner y coordinate
   Col         Drawing color

Returns:

none


Description:

Same as DQBbox, but draws a full box filled with Col color.

Notes:

See DQBbox.


Example:

See DQBbox example


-----------------------------------------------------------------------------
DQBbPut SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBbPut (BYVAL Layer, BYVAL x, BYVAL y, BYVAL SpriteSeg,
                     BYVAL SpriteOff)

Calling:

   Layer       Layer where to draw the sprite
   x           X position of upper left corner of the sprite
   y           Y position of upper left corner of the sprite
   SpriteSeg   Segment of the array holding the sprite data; use VARSEG
   SpriteOff   Offset of the array holding the sprite data; use VARPTR

Returns:

none


Description:

DQBbPut draws a sprite blending its colors with the background; the way the
colors are blended depends on the actual blender map. If a bmap has not been
created by calling DQBcreateBMap, this function does nothing. There are
virtually unlimited special color effects allowed by using the blender map
system: by setting up an appropriate bmap for your palette, you can obtain
a translucency effect for example.

Notes:

DQBbPut is affected by the clipping box, so pixels outside this box will not
be drawn; transparency is also supported. See also DQBcreateBMap, DQBsetBMap,
DQBgetBMap, DQBloadBMap, DQBsaveBMap, DQBput, DQBfPut, DQBsPut and DQBrPut.

Example:

*****************************************************************************

' Use integers for speed
DEFINT A-Z

'$INCLUDE: 'DIRECTQB.BI'

' Let's initialize the library
r = DQBinit(1, 0)
IF r <> 0 THEN
  ' Something went wrong while initializing
  PRINT "Initialization error" + STR$(r)
  DQBclose
  END
END IF

' Let's build the blender map
IF DQBcreateBMap THEN
  ' Not enough memory
  PRINT "64000 bytes of free base memory are needed for the blender map!"
  DQBclose
  END
END IF

' Here we set our only color combination: if a pixel of color 40 (bright red)
' is drawn over another of color 32 (bright blue), the pixel is drawn with
' color 13 (bright purple)
DQBsetBMap 40, 32, 13

' Let's dimension our two sprites using DQBsize
size = DQBsize(0, 0, 63, 7)
DIM Sprite(size)

DQBclearLayer 1
DQBprint 1, "DirectQB", 0, 0, 32
DQBprint 1, "Power!", 0, 8, 40

' Get our sprites
DQBget 1, 0, 0, 63, 7, VARSEG(Sprite(0)), VARPTR(Sprite(0))
DQBget 1, 0, 8, 63, 15, VARSEG(Sprite(0)), (VARPTR(Sprite(0)) + size)

DQBinitVGA

' Let's begin the demo
FOR x = -64 TO 320
  ' Clean our hidden layer
  DQBclearLayer 1

  ' Draws our sprites on layer 1
  DQBput 1, x, 96, VARSEG(Sprite(0)), VARPTR(Sprite(0))
  DQBbPut 1, (256 - x), 96, VARSEG(Sprite(0)), (VARPTR(Sprite(0)) + size)

  ' Copies layer 1 on the screen
  DQBwait 3
  DQBcopyLayer 1, VIDEO
NEXT x

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBbtri SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBbtri (BYVAL Layer, BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2,
                     BYVAL x3, BYVAL y3, BYVAL Col)

Calling:

   Layer       Layer where to draw the triangle
   x1          x coordinate of the first vertex
   y1          y coordinate of the first vertex
   x2          x coordinate of the second vertex
   y2          y coordinate of the second vertex
   x3          x coordinate of the third vertex
   y3          y coordinate of the third vertex
   Col         color


Returns:

none


Description:

Draws a triangle with (x1,y1), (x2,y2) and (x3,y3) as vertex, and fills it
by blending specified color with the background, using the current blender
map. This function does not support transparency, but it's affected by the
clipping box.

Notes:

See also DQBtri, DQBgtri, DQBttri


Example:

none


-----------------------------------------------------------------------------
DQBchangeDrive SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBchangeDrive (Drive AS STRING)

Calling:

   Drive       New drive letter

Returns:

none


Description:

This function changes the current drive to the new one specified by the letter
of the Drive parameter. 

Notes:

None


Example:


-----------------------------------------------------------------------------
DQBclearLayer SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBclearLayer (BYVAL Layer)

Calling:

   Layer       Layer to clear

Returns:

none


Description:

Clears the contents of a given layer: all the pixels are set to color 0. This
function is automatically called for all the allocated layers when calling
DQBinit.

Notes:

None


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

PRINT "Press a key to clear the screen!"
WHILE INKEY$="":WEND

' Clears the screen
DQBclearLayer VIDEO

' Ends the program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBclose SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBclose ()

Calling:

none

Returns:

none


Description:

This function deallocates the EMS memory used by the layers initialized by
DQBinit and turns off the keyboard interrupt handler and the sound engine if
they were on; it also deallocates the blender map if it was created. DQBclose
must always be called before ending your programs, otherwise allocated EMS
memory will be lost, and you'll have to reboot your computer to free it.

Notes:

See also DQBinit.


Example:

none


-----------------------------------------------------------------------------
DQBcopyLayer SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBcopyLayer (BYVAL SourceLayer, BYVAL DestLayer)

Calling:

   SourceLayer   Source layer to copy data from
   DestLayer     Destination layer where to copy data

Returns:

none


Description:

Copies the contents of SourceLayer into DestLayer. All the data previously
into DestLayer will be lost. This function can be used to create double
buffered animations; just draw every sprite onto a layer on EMS, and then use
DQBcopyLayer to copy its contents to the screen.

Notes:

none


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with one extra layer and no sounds
Result = DQBinit(1, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

' Draws a box on the hidden layer
DQBbox 1, 0, 0, 319, 199, 15

' Copies the hidden layer on the screen
DQBcopyLayer 1, VIDEO

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBcopyTransLayer SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBcopyTransLayer (BYVAL SourceLayer, BYVAL DestLayer)

Calling:

   SourceLayer   Source layer to copy data from
   DestLayer     Destination layer where to copy data

Returns:

none


Description:

This function is similar to DQBcopyLayer, but the pixels with color 0 of the
source layer are skipped and not copied onto the destination layer; this
allows transparent layer copy. With some practice, it is possible to obtain
a parallax scrolling effect using this function with DQBscroll.

Notes:

Needless to say, DQBcopyTransLayer is slower than DQBcopyLayer, be warned.


Example:

See DQBcopyLayer example


-----------------------------------------------------------------------------
DQBcreateBMap FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBcreateBMap ()

Calling:

none

Returns:

An INTEGER value holding the operation result:

>   0     Blender map successfully created and initialized
>   1     Not enough free conventional memory
>   2     Blender map already created


Description:

This function attempts to create a blender map in *conventional* memory; this
requires 64K of free RAM. A blender map is a table with all the possible
color combinations: 256 fore colors * 256 back colors = 65536 combinations.
The fore color is the color of each pixel of your sprite, and the back color
is the one of each pixel of the background layer where you're drawing. Suppose
you have a palette with color 1 as bright red, color 2 as bright green, and
color 3 as bright purple. Well, you could call DQBsetBMap 1,2,3: this way
every time you use DQBbPut to draw a sprite with some pixels of color 1,
and the background is filled with color 2, you'll see a purple sprite...
It's a hard thing to explain, but once you've understood it, you'll also
understand the system offers virtually any special effect, depending on your
palette and, of course, on the blender map you set.

Notes:

So you have to set your blender map on your needs: as it's often a slow
process, there're the DQBsaveBMap and DQBloadBMap functions that help you.
It is also suggested that you use DQBfindCol to create your blender map
independently from the current palette. Keep also in mind that any blending
function will not work unless the blender map has not been created by calling
DQBcreateBMap. See also DQBsetBMap, DQBgetBMap, DQBloadBMap, DQBsaveBMap,
DQBbPut, DQBfilterBox.


Example:

See DQBbPut example


-----------------------------------------------------------------------------
DQBdir$ FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBdir$ (Mask AS STRING, Attrib AS INTEGER)

Calling:

   Mask          Mask for file(s) to search for
   Attrib        Attributes of the file(s) to search for

Returns:

A STRING holding the filename of the next file found


Description:

DQBdir scans the directory for the files matching specified mask; the mask
can include full path and wildcards. If no files are found, the function
returns a null string. The first time DQBdir is called with a mask, it
searches for the first file matching it; if a file is found, then you can
continue to scan the directory by calling this function again, but by passing
a null string as mask. Repeat this process until you get a null string, and
you'll obtain a full directory scan. The attrib parameter specifies which
kind of files to search for: there are constants made up for you, which you
can also sum to search for a larger variety of files (for example, to search
simultaneously for normal archive files and directories), so just take a look
at appendix A for them.

Notes:

A hint: you can determine if a file exists by simply checking if DQBdir$ of
that file as mask, with ATTRIB.A as attribute, gives a null string or the
file name itself...
See also DQBdrive$, DQBpath$, DQBnumDrives, DQBsetDrive


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

CLS

' Prints available drives
PRINT "Available drives: ";
FOR i = 1 TO DQBnumDrives
  PRINT "[" + CHR$(64 + i) + "] ";
NEXT i
PRINT

' Prints volume label
PRINT "Current volume label is " + DQBdir$("*.*",ATTRIB.L)

' Prints current drive and directory
PRINT "Directory of " + DQBdrive$ + ":\" + DQBpath$

' Let's search for normal archive ".BAS" files
File$ = DQBdir$("*.BAS", ATTRIB.A)
IF File$ = "" THEN
  ' No files matching
  PRINT "No .BAS files found!"
ELSE
  ' A first file was found! Let's print it
  PRINT File$

  ' Now we search for the next files... if any
  DO
    ' This second time we don't need the mask nor the attributes
    File$ = DQBdir$("",0)

    ' If no more files are found, then exit the loop
    IF File$ = "" THEN EXIT DO

    ' Prints our next file
    PRINT File$
  LOOP
END IF

' Ends program
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBdrive$ FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBdrive$ ()

Calling:

none

Returns:

The drive letter character


Description:

This function simply returns a string of 1 character holding the current
drive letter.

Notes:

See also DQBsetDrive, DQBnumDrives, DQBdir$, DQBpath$


Example:

See DQBdir$ example


-----------------------------------------------------------------------------
DQBellipse SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBellipse (BYVAL Layer, BYVAL x, BYVAL y, BYVAL rx, BYVAL ry,
                        BYVAL Col)

Calling:

   Layer         Source layer to copy data from
   x             x coordinate of the center of your ellipse
   y             y coordinate of the center of your ellipse
   rx            Horizontal radius in pixels
   ry            Vertical radius in pixels
   Col           Ellipse color

Returns:

none


Description:

This function is useful to draw ellipses (and, needless to say, a circle is
a particular ellipse with equal radiuses); the radiuses can range from 0 up
to 256.

Notes:

Also DQBellipse is affected by the clipping box


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with one extra layer and no sounds
Result = DQBinit(1, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

FOR i = 10 TO 90 STEP 10
  ' Draws our ellipses
  DQBellipse VIDEO, 160, 100, 90, i, 40
  DQBellipse VIDEO, 160, 100, i, 90, 40
NEXT i

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBemsSeg FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBemsSeg ()

Calling:

none

Returns:

An INTEGER value holding the EMS pageframe segment


Description:

Returns the EMS pageframe segment. The only target of this function is to
allow you to show the pageframe somewhere in your program, if you want;
there're no particular needs to call it anyway.

Notes:

none


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with one extra layer and no sounds
Result = DQBinit(1, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

' Informs the user on the location of the pageframe
PRINT "The EMS pageframe segment is located at " + HEX$(DQBemsSeg)
+ "h"

' Ends program
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBfadeIn SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBfadeIn (Pal AS STRING)

Calling:

   Pal         A string of 768 characters holding the palette to fade into

Returns:

none


Description:

Fades the current palette into the given one; current palette may be
completely different from the target one. The Pal string can be obtained by
calling the DQBgetPal or the DQBloadLayer functions, or it can be set
manually; just keep in mind that there're three bytes for each color,
representing the red, green and blue components of them, in the range 0-63.

Notes:

See also DQBfadeTo, DQBgetPal, DQBsetPal, DQBpalOff, DQBgetCol, DQBsetCol


Example:

See DQBfadeTo example


-----------------------------------------------------------------------------
DQBfadeStepIn SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBfadeStepIn (Pal AS STRING)

Calling:

   Pal         A string of 768 characters holding the palette to fade into

Returns:

none


Description:

Works exactly like DQBfadeIn, but this will only fade all the colors by a
single step. To be sure of fading all your colors to the new palette, you
should call this function 64 times repeatedly. DQBfadeStepIn can be useful to
move your stuff around while fading.

Notes:

See also DQBfadeIn


Example:

none


-----------------------------------------------------------------------------
DQBfadeStepTo SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBfadeStepTo (BYVAL Red, BYVAL Green, BYVAL Blue)

Calling:

   Red         Red hue to fade colors into
   Green       Green hue to fade colors into
   Blue        Blue hue to fade colors into

Returns:

none


Description:

Works exactly like DQBfadeTo, but this function will only fade all the colors
by a single step. As with DQBfadeStepIn, to be sure to fade all your palette,
you should call this function 64 times. DQBfadeStepTo can be useful to move
your stuff around while fading.

Notes:

See also DQBfadeTo


Example:

none


-----------------------------------------------------------------------------
DQBfadeTo SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBfadeTo (BYVAL Red, BYVAL Green, BYVAL Blue)

Calling:

   Red         Red hue to fade colors into
   Green       Green hue to fade colors into
   Blue        Blue hue to fade colors into

Returns:

none


Description:

Fades all the colors in current palette to the specified red, green and blue
hues. To fade a palette to black, just call this function with 0,0,0 as
parameters; it's quite powerful, as it can fades any palette to any specified
color.

Notes:

See also DQBfadeIn, DQBgetPal, DQBsetPal, DQBpalOff, DQBgetCol, DQBsetCol


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

DIM Pal AS STRING * 768

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

' Stores the default palette into Pal
DQBgetPal Pal

' Turns all the colors to black
DQBpalOff

' Draws randomly 500 pixels on the screen
FOR i = 1 TO 500
    RANDOMIZE TIMER
    DQBpset VIDEO, (RND*320), (RND*200), (RND*256)
NEXT i

' Fades the palette into the original one
DQBfadeIn Pal

' Fades the palette to white
DQBfadeTo 63, 63, 63

' and then to black
DQBfadeTo 0,0,0

' Restores the original palette
DQBsetPal Pal

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBfilterBox SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBfilterBox (BYVAL Layer, BYVAL x1, BYVAL y2, BYVAL x2, BYVAL y2,
                          BYVAL Col)

Calling:

   Layer       Layer where to draw the filter box
   x1          Upper left corner x coordinate
   y1          Upper left corner y coordinate
   x2          Lower right corner x coordinate
   y2          Lower right corner y coordinate
   Col         Filter color

Returns:

none


Description:

DQBfilterBox draws a full box blending specified color with the background,
using the current blender map; if no blender map has been created, this
function will not draw the box.

Notes:

The filter color acts as the fore color; it's up to you to set an appropriate
blender map. Remember also that it must be x2>=x1 and y2>=y1. See also
DQBcreateBMap, DQBloadBMap, DQBsaveBMap, DQBsetBMap, DQBgetBMap and DQBbPut.


Example:

none


-----------------------------------------------------------------------------
DQBfindCol FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBfindCol (BYVAL Red, BYVAL Green, BYVAL Blue)

Calling:

   Red         Red hue of the color to find
   Green       Green hue of the color to find
   Blue        Blue hue of the color to find

Returns:

An INTEGER value ranging 0-255, holding the index of the color found


Description:

DQBfindCol searches the current palette for the color that best fits with the
specified red, green and blue hues. It can be really useful to create a
blender map in conjunction with the DQBsetBMap routine.

Notes:

This function may return bad results, depending on the current palette and
the specified hues, so use it with caution.


Example:

none


-----------------------------------------------------------------------------
DQBfPut SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBfPut (BYVAL Layer, BYVAL x, BYVAL y, BYVAL SpriteSeg,
                     BYVAL SpriteOff)

Calling:

   Layer       Layer where to draw the sprite
   x           X position of upper left corner of the sprite
   y           Y position of upper left corner of the sprite
   SpriteSeg   Segment of the array holding the sprite data; use VARSEG
   SpriteOff   Offset of the array holding the sprite data; use VARPTR

Returns:

none


Description:

Like DQBput, DQBfPut draws a sprite on specified layer, but using a faster
algorithm. This function does not allow clipping nor transparency, and works
better with big sprites with a width which is a multiple of 4.

Notes:

See DQBput, DQBsPut, DQBrPut and DQBbPut


Example:

See DQBput example


-----------------------------------------------------------------------------
DQBget SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBget (BYVAL Layer, BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2,
                    BYVAL SpriteSeg, BYVAL SpriteOff)

Calling:

   Layer       Layer where to get the sprite
   x1          Upper left corner x coordinate
   y1          Upper left corner y coordinate
   x2          Lower right corner x coordinate
   y2          Lower right corner y coordinate
   SpriteSeg   Segment of the array where to store the sprite; use VARSEG
   SpriteOff   Offset of the array where to store the sprite; use VARPTR

Returns:

none


Description:

Gets a sprite from the given layer in the box (x1,y1)-(x2,y2) and places the
data into specified array. Array must be dimensioned as (((Width*Height)*2)+4)
INTEGERs; you can use the DQBsize function and divide the result by 2 to
retrieve the size of your array without worring about this formula. Sprites
get with DQBget can be then used by DQBput to create animations.

Notes:

DQBget is not affected by the clipping box. Also, it must be x1<x2 and y1<y2.
This routine is optimized if your sprite width is a multiple of 4 or 2.
Several sprites can be stored into the same array; just pass the sprite with
a different index. In addition, the format of DQBget and DQBput is compatible
with the one of GET and PUT, so you can use them with the same sprite arrays.
See also DQBfPut, DQBsPut, DQBrPut and DQBbPut

Example:

See DQBput example


-----------------------------------------------------------------------------
DQBgetBMap FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBgetBMap (BYVAL ForeCol, BYVAL BackCol)

Calling:

   ForeCol     Foreground color
   BackCol     Background color

Returns:

An INTEGER value holding the color set for the specified combination in the
current blender map


Description:

Returns the color set on the current blender map for the color combination
given by the specified foreground and background colors.

Notes:

See also DQBcreateBMap and DQBsetBMap


Example:

none


-----------------------------------------------------------------------------
DQBgetCol SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBgetCol (BYVAL Col, Red, Green, Blue)

Calling:

   Col         Color index to retrieve data from
   Red         INTEGER variable where to store the red hue
   Green       INTEGER variable where to store the green hue
   Blue        INTEGER variable where to store the blue hue

Returns:

none


Description:

Gets the red, green and blue hues of the given color and stores them into the
Red, Green and Blue INTEGER variables. Hues ranges from 0-63.

Notes:

See also DQBsetCol


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'
DIM r, g, b

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

' Gets the hues for color 2 (dark green in default BIOS palette)
DQBgetCol 2, r, g, b

PRINT "Color 2 hues:"
PRINT "Red:", r
PRINT "Green:", g
PRINT "Blue:", b

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBgetPal SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBgetPal (Pal AS STRING)

Calling:

   Pal         String of 768 character where to store the palette

Returns:

none


Description:

Gets the current palette and stores it into the Pal string. Such a palette
can be then used by the DQBsetPal, DQBfadeIn and DQBsaveLayer functions.

Notes:

See appendix A to know how the palette is stored into the string


Example:

See DQBfadeTo example


-----------------------------------------------------------------------------
DQBgtri SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBgtri (BYVAL Layer, BYVAL x1, BYVAL y1, BYVAL c1, BYVAL x2,
                     BYVAL y2, BYVAL c2, BYVAL x3, BYVAL y3, BYVAL c3)

Calling:

   Layer       Layer where to draw the triangle
   x1          x coordinate of the first vertex
   y1          y coordinate of the first vertex
   c1          color of the first vertex
   x2          x coordinate of the second vertex
   y2          y coordinate of the second vertex
   c2          color of the second vertex
   x3          x coordinate of the third vertex
   y3          y coordinate of the third vertex
   c3          color of the third vertex


Returns:

none


Description:

Draws a gouraud-shaded triangle with (x1,y1), (x2,y2) and (x3,y3) as vertex,
interpolating specified colors, using the current palette. DQBgtri does not
support transparency, but it's affected by the clipping box.

Notes:

Gouraud shading works better when you set a palette with lots of shades of the
same color; it is up to you to find the best settings for your needs. See also
DQBtri, DQBbtri, DQBttri


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
IF DQBinit(0, 0) THEN PRINT "Initialization error!": DQBclose: END

DQBinitVGA

' Sets up the palette with shades of red
FOR i = 0 TO 63
  DQBsetCol i, i, 0, 0
  DQBsetCol 64 + i, 63, i, i
NEXT i

' Draws 500 gouraud-shaded triangles; uses only the first 128 colors we set
FOR i = 1 TO 500
  DQBgtri VIDEO, (RND * 320), (RND * 200), (RND * 128), (RND * 320), (RND * 200), (RND * 128), (RND * 320), (RND * 200), (RND * 128)
NEXT i

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBinit FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBinit (BYVAL NumLayers, BYVAL NumSounds)

Calling:

   NumLayers   Number of layers to allocate memory for
   NumSounds   Number of sounds to allocate memory for

Returns:

An INTEGER value holding the initialization result. It can be:

>   0     Initialization successful
>   1     386 or better CPU not detected
>   2     Unable to find an expanded memory manager
>   3     Not enough free EMS memory to allocate specified number of layers


Description:

The DQBinit function must be called before any of the other library functions.
It allocates a specified number of layers and sounds into EMS, and does other
initializations; remember that you can allocate as much layers as you want,
and up to 256 sounds, as long as enough free memory is available, otherwise
you'll get an error 3 when calling this function. The only thing you need to
know is that each layer or sound takes 64KB of EMS. Also, please keep in mind
that if you refer to a layer or a sound number that has not been allocated
with this procedure, your system will probably crash: I mean that if you
allocate 3 layers with DQBinit, you must not refer to layer 4. If you get an
error 2, please refer to section 1.3 of this manual, that explains how to
install EMS on your system.

Notes:

As DQBinit must be called at the beginning of your program, remember to call
DQBclose at its end.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with four extra layers and no sounds
Result = DQBinit(4, 0)

SELECT CASE Result
CASE 0
    PRINT "Initialization successful"
CASE 1
    PRINT "Error: 386 or better CPU not detected!"
CASE 2
    PRINT "Error: unable to find an expanded memory manager!"
CASE 3
    PRINT "Error: not enough free EMS memory!"
END SELECT

' Ends program
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBinitText SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBinitText()

Calling:

none


Returns:

none


Description:

Initializes plain 80x25 text mode (mode 03h).

Notes:

By using this function instead of SCREEN 0, you can obtain smaller executables
once you compile your programs. See also DQBinitVGA


Example:

none


-----------------------------------------------------------------------------
DQBinitVGA SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBinitVGA()

Calling:

none


Returns:

none


Description:

Initializes 320x200 with 256 colors VGA video mode (mode 013h), and resets
the mouse if it was found.

Notes:

By using this function instead of SCREEN 13, you can obtain smaller executables
once you compile your programs. See also DQBinitText


Example:

none


-----------------------------------------------------------------------------
DQBinkey$ FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBinkey$ ()

Calling:

none

Returns:

If a key is pressed, it returns its character, otherwise a null string


Description:

DQBinkey$ works just like the usual INKEY$ QB statement. If any key is being
pressed, this function returns its associated character, otherwise it returns
a null string.

Notes:

This function works only while the custom keyboard handler is on, otherwise
you'll probably crash your system. In addition, as DQBinkey$ does not get the
character from the standard keyboard buffer, you'll loose your character if
you do not store it in some variable.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
IF DQBinit(0, 0) THEN PRINT "Initialization error!": DQBclose: END

' Installs the keyboard handler
DQBinstallKeyboard

' Let's prompt the user for a question
PRINT "Press 'Y' if you like DirectQB, otherwise 'N'"
DO
  DO: k$ = DQBinkey$: LOOP WHILE k$ = ""
  SELECT CASE k$
  CASE "Y": PRINT "Thank you!": EXIT DO
  CASE "N": PRINT "Too bad!!": EXIT DO
LOOP

' Removes the keyboard handler
DQBremoveKeyboard

' Ends program
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBinstallKeyboard SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBinstallKeyboard ()

Calling:

none

Returns:

none


Description:

Installs a custom keyboard interrupt handler that allows you to detect the
exact state (pressed or released) of any key at any time. Once activated by
calling this function, the standard QB routines like INPUT, INKEY$ or whatever
other routine that uses the keyboard as input, will be unavailable. Calling
them will probably result into your machine to crash, so pay attention. These
standard routines can be called only when the interrupt handler will be
uninstalled by calling DQBremoveKeyboard; this last function is automatically
called by DQBclose, so usually you don't have to bother about it. When the
handler is active, you can know the state of each key by simply calling the
DQBkey function.

Notes:

none


Example:

See DQBkey example


-----------------------------------------------------------------------------
DQBinstallSB FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBinstallSB (BYVAL Voices,BYVAL BaseAddr, BYVAL IRQ,
                               BYVAL DMA)

Calling:

   Voices      Number of voices to mix at real-time
   BaseAddr    Base address of your soundcard
   IRQ         IRQ number setting
   DMA         Low DMA channel to be used

Returns:

An INTEGER value holding the initialization result. It can be:

>   0     Initialization successful
>   1     No sounds were allocated by DQBinit
>   2     Soundcard not found or DSP failed to reset
>   3     Old soundcard not supported
>   4     Specified DMA channel is not supported
>   5     Autodetection failed as the BLASTER variable is not set


Description:

DQBinstallSB installs a custom IRQ routine and starts the sound engine if all
goes ok. If you don't know your sound settings (base address, IRQ or DMA), you
can pass the AUTO constant as the missing parameter(s); this will force the
function to search the BLASTER environmental variable (if available) for the
right setting. The number of voices can range from 1 up to 32, and tells the
sound engine how many digital sound channels to mix at real-time; needless to
say, on older computers, too many voices will slow down your programs...

Notes:

To turn it off, call DQBremoveSB; this is anyway automatically called for you
by DQBclose. See also DQBloadSound, DQBplaySound, DQBstopVoice


Example:

See DQBplaySound example


-----------------------------------------------------------------------------
DQBinUse FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBinUse (BYVAL Voice)

Calling:

   Voice       Voice number to retrive the status of

Returns:

True if a sound is playing on specified voice


Description:

DQBinUse returns true if any sound is currently playing on the specified
voice, otherwise false.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBjoyDetected FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBjoyDetected (BYVAL JoyNum)

Calling:

   JoyNum      Joystick number to detect

Returns:

True if specified joystick has been detected, otherwise false


Description:

This function should be called before using the other joystick functions, to
detect if a joystick is available. The parameter JoyNum can be 0 for joystick
1, 1 for joystick 2 or 2 for 4-button joystick. If you can't remember this,
just call this function, as well as the other joystick functions, with the
constants JOY1, JOY2 and GAMEPAD defined into the file DIRECTQB.BI, and
explained into appendix A.

Notes:

none


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

' Finds if joystick 1 is available
IF DQBjoyDetected(JOY1) THEN
    PRINT "Joystick 1 detected"
ELSE
    PRINT "Joystick 1 not detected"
END IF

' Ends program
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBjoyFire FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBjoyFire (BYVAL JoyNum, BYVAL Button)

Calling:

   JoyNum      Joystick number to retrieve status of
   Button      Button number to check

Returns:

True if specified button of specified joystick is pressed, otherwise false


Description:

This function is used to check if a button of a specified joystick is being
pressed. About the parameter JoyNum, please refer to the DQBjoyDetected
function. The other parameter, Button, can be 0 for button A, or 1 for button
B. If you're handling a 4-buttons joystick, you can also use 2 and 3 for
buttons 3 and 4. As for the joystick number, also the buttons have constants
named BUTA, BUTB, BUTC and BUTD declared into the file DIRECTQB.BI, and
explained into appendix A.

Notes:

none


Example:

See DQBjoyMove example


-----------------------------------------------------------------------------
DQBjoyMove FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBjoyMove (BYVAL JoyNum, BYVAL Direction)

Calling:

   JoyNum      Joystick number to retrieve status of
   Direction   Direction to check, see below

Returns:

True if the joystick is moved into the given direction, otherwise false


Description:

Call this function to know where the joystick has been moved. About the JoyNum
parameter refer to the DQBjoyDetected function. The Direction parameter is an
integer that must be set to: 

-   0     to check if the joystick has been moved up
-   1     to check if the joystick has been moved down
-   2     to check if the joystick has been moved left
-   3     to check if the joystick has been moved right

There are of course four constants for this parameter, named UP, DOWN, LEFT
and RIGHT, declared into the file DIRECTQB.BI, and explained into appendix A.

Notes:

none


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'
DIM X, Y, Col

' Let's initialize the library with one extra layer and no sounds
Result = DQBinit(1, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

IF NOT DQBjoyDetected(JOY1) THEN
    PRINT "Joystick 1 not detected, program aborted."
    DQBclose
    END
END IF

DQBinitVGA

X = 150: Y = 90

DO
    ' Polls joystick 1
    DQBpollJoy JOY1
    
    ' Checks movements
    IF DQBjoyMove(JOY1, UP) THEN Y = Y - 1      ' Joystick 1 up

    IF DQBjoyMove(JOY1, DOWN) THEN Y = Y + 1    ' Joystick 1 down

    IF DQBjoyMove(JOY1, LEFT) THEN X = X - 1    ' Joystick 1 left

    IF DQBjoyMove(JOY1, RIGHT) THEN X = X + 1   ' Joystick 1 right

    ' Adjust coordinates
    IF X < 0 THEN X = 0
    IF X > 299 THEN X = 299
    IF Y < 0 THEN Y = 0
    IF Y > 179 THEN Y = 179

    ' Resets box color to white
    Col = 15

    ' If button A is pressed, change color to red
    IF DQBjoyFire(JOY1, BUTA) THEN Col = 40

    ' If button B is pressed, change color to green
    IF DQBjoyFire(JOY1, BUTB) THEN Col = 2

    ' Clears the contents of layer 1
    DQBclearLayer 1

    ' Draws the box
    DQBboxf 1, X, Y, (X + 19), (Y + 19), Col

    ' Waits for vertical retrace 1 time
    DQBwait 1

    ' Copies out layer to the screen
    DQBcopyLayer 1, VIDEO

    ' Prints a message
    LOCATE 1
    PRINT "  Joystick demo - press a key to exit!"

LOOP WHILE INKEY$ = ""

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBkey FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBkey (BYVAL ScanCode)

Calling:

   ScanCode    Scancode of the key to retrieve status of

Returns:

True if the key is pressed, otherwise false


Description:

This function returns useful information only when the custom keyboard
interrupt handler has been installed by calling DQBinstallKeyboard. For a
complete list of keyboard scancodes, refer to appendix B. There're also a few
constants declared into the file DIRECTQB.BI, such as KEYESC, KEYENTER, KEYUP,
KEYDOWN, KEYLEFT, KEYRIGHT and others, explained into appendix A.

Notes:

none


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

' Let's install the custom keyboard handler
DQBinstallKeyboard

CLS
PRINT "Keyboard demo - press any key to see its scancode. Multiple
keypresses are allowed; press ESC to exit."

DO
    LOCATE 3, 1

    ' Scans every possible key
    FOR i = 0 TO 127
        ' If the key is pressed, prints its scancode
        IF DQBkey(i) THEN PRINT "[" + LTRIM$(STR$(i)) + "] ";
    NEXT i

    ' Clears a portion of the screen
    PRINT SPACE$(40)

' Loops while the ESC key is not pressed
LOOP UNTIL DQBkey(KEYESC)

' Uninstalls the keyboard handler (this is not really needed when we're
' going to end the program by calling DQBclose)
DQBremoveKeyboard

' Ends program
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBlen FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBlen (Text AS STRING)

Calling:

   Text        Text string to retrieve the length of

Returns:

An INTEGER holding the length in pixels of the given string, assuming the
current font characters length


Description:

Like LEN, DQBlen returns the length of a specified string, but in pixel units.
As DirectQB supports non-fixed sized fonts, this function is useful to
retrieve the length of a string in pixels, calculated using the length of
the characters of the current font.

Notes:

none


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

Length = DQBlen("The length of this string is:")
DQBprint VIDEO, "The length of this string is:" + STR$(Length) + " pixels", 0, 0, 31

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBline SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBline (BYVAL Layer, BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2,
                     BYVAL Col)

Calling:

   Layer       Layer where to draw the line onto
   x1          First point x coordinate
   y2          First point y coordinate
   x2          Second point x coordinate
   y2          Second point y coordinate
   Col         Drawing color

Returns:

none


Description:

This procedure draws a line from point at (x1,y1) to point at (x2,y2), on the
given layer and with specified color. The Bresenham's line algorithm is used.

Notes:

DQBline is affected by the clipping box set by DQBsetClipBox.


Example:

none


-----------------------------------------------------------------------------
DQBloadBMap FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBloadBMap (FileName AS STRING)

Calling:

   FileName    Blender map file name with full extension

Returns:

An INTEGER value holding the loading results:

>   0     Loading successful
>   1     Blender map not yet created
>   2     Cannot open file, or file does not exist
>   3     General reading error


Description:

Loads data from a specified binary file into the blender map; the blender map
must have been previously created by calling DQBcreateBMap.

Notes:

See also DQBcreateBMap and DQBsaveBMap


Example:

none


-----------------------------------------------------------------------------
DQBloadLayer FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBloadLayer (Layer AS INTEGER, FileName AS STRING,
                               Pal AS STRING)

Calling:

   Layer       Layer where to load the image onto
   FileName    Image file name with full extension
   Pal         String where the image palette is loaded into

Returns:

An INTEGER value holding the loading results:

>   0     Loading successful
>   1     Cannot open file, or file does not exist
>   2     General reading error
>   3     Bad or unknown file format


Description:

Loads an image into specified layer. Images must be 320x200 pixels with 256
colors, and can be BMP, PCX or BSAVEd files; the format is automatically
detected and it's independent from the file extension. The function returns 0
if the operation is successful, otherwise an error code (see above). When
loading a BMP or a PCX image, the palette is stored into the Pal string;
current palette is not changed, allowing you to change it only when you want,
by calling DQBsetPal or DQBfadeIn, or any way you like.

Notes:

See appendix C to know the palette string format


Example:

none


-----------------------------------------------------------------------------
DQBloadRawSound FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBloadRawSound (Slot AS INTEGER, FileName AS STRING,
                                  Offset AS LONG, Length AS INTEGER)

Calling:

   Slot        Sound slot to load the sound into
   FileName    Sound file name with full extension
   Offset      File position where to begin to load in bytes
   Length      Sound data length in bytes

Returns:

An INTEGER value holding the loading results:

>   0     Loading successful
>   1     Cannot open file, or file does not exist
>   2     General reading error
>   3     Cannot read past the end of file
>   4     Specified sound slot does not exist


Description:

Loads sound data from a specified position on a given file. This function
does not check for the data format, and directly stores the sound into the
specified slot. DQBloadRawSound can be useful to handle sound data files
holding multiple sounds data, as well as when DQBloadSound fails the sound
data format check.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBloadSound FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBloadSound (Slot AS INTEGER, FileName AS STRING)

Calling:

   Slot        Sound slot to load sound into
   FileName    Sample file name with full extension

Returns:

An INTEGER value holding the loading results:

>   0     Loading successful
>   1     Cannot open file, or file does not exist
>   2     General reading error
>   3     Bad or unknown file format
>   4     Sound format not yet supported
>   5     Sound file exceeds the 64K length limit
>   6     Specified sound slot does not exist


Description:

Loads a sound sample from file and stores it into EMS. The "Slot" parameter
identifies the sound effect and is used by the DQBplaySound function.

Notes:

Only 8-bit mono WAV files are supported for now, so be warned.


Example:

See DQBplaySound example


-----------------------------------------------------------------------------
DQBmouseDetected FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBmouseDetected ()

Calling:

none

Returns:

An INTEGER value holding the mouse initialization result:

>   0     Mouse not detected
>   -1    Mouse detected and successfully initialized


Description:

Returns true if a mouse has been detected on your system; you should call this
before calling any other mouse routine.

Notes:

It is recommended that you also call DQBresetMouse just after setting mode
13h by calling SCREEN 13, before using any other mouse routine.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with one extra layer and no sounds
Result = DQBinit(1, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

' Checks if a mouse has been detected
IF NOT DQBmouseDetected THEN
    ' Mouse has not been detected
    PRINT "This demo requires a mouse to run!"
    DQBclose
    END
END IF

DQBinitVGA

' Resets the mouse cursor and range
DQBresetMouse

' Sets a new mouse range
DQBsetMouseRange 6, 6, 314, 148

DO
    ' Let's clear layer 1
    DQBclearLayer 1

    DQBbox 1, 5, 5, 315, 149, 32

    ' Prints some stats
    DQBprint 1, "PRESS ANY KEY TO EXIT DEMO", 0, 170, 40

    ' Prepares our info string
    Info$ = "Mouse is at" + str$(DQBmouseX) + "," + str$(DQBmouseY)
    Info$ = Info$ + " - Buttons: " + str$(DQBmouseLB) + " " + str$(DQBmouseRB)

    DQBprint 1, Info$, 0, 180, 40

    ' Hides the mouse cursor before drawing to the screen
    DQBmouseHide

    ' Copies layer 1 onto the screen
    DQBcopyLayer 1, VIDEO

    ' Shows the cursor again
    DQBmouseShow

' Loops while no keys are pressed
LOOP WHILE INKEY$ = ""

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBmouseHide SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBmouseHide ()

Calling:

none

Returns:

none


Description:

Hides the mouse cursor if it was visible. Though the mouse is not visible, it
remains active.

Notes:

See DQBmouseShow


Example:

See DQBmouseDetected example


-----------------------------------------------------------------------------
DQBmouseLB FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBmouseLB ()

Calling:

none

Returns:

-1 if the left mouse button is currently pressed, otherwise 0


Description:

Call this function to know if the left mouse button is pressed or released.
It can be called at any time, as the mouse status is automatically checked.

Notes:

none


Example:

See DQBmouseInit example


-----------------------------------------------------------------------------
DQBmouseRB FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBmouseRB ()

Calling:

none

Returns:

-1 if the right mouse button is currently pressed, otherwise 0


Description:

Call this function to know if the right mouse button is pressed or released.
It can be called at any time, as the mouse status is automatically checked.

Notes:

none


Example:

See DQBmouseInit example


-----------------------------------------------------------------------------
DQBmouseShow SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBmouseShow ()

Calling:

none

Returns:

none


Description:

Shows the mouse cursor if it was not visible.

Notes:

none


Example:

See DQBmouseInit example


-----------------------------------------------------------------------------
DQBmouseX FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBmouseX ()

Calling:

none

Returns:

An INTEGER value holding the current mouse x coordinate


Description:

Call this function at any time to know the current mouse x position.

Notes:

The position is given in pixel units, and ranges depending on the actual
mouse range box. This can be changed by calling DQBsetMouseRange.


Example:

See DQBmouseInit example


-----------------------------------------------------------------------------
DQBmouseY FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBmouseY ()

Calling:

none

Returns:

An INTEGER value holding the current mouse y coordinate


Description:

Call this function at any time to know the current mouse y position.

Notes:

The position is given in pixel units, and ranges depending on the actual
mouse range box. This can be changed by calling DQBsetMouseRange.


Example:

See DQBmouseInit example


-----------------------------------------------------------------------------
DQBnumDrives FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBnumDrives

Calling:

none

Returns:

An INTEGER value holding the number of drives


Description:

This function returns the number of available logical drives. A value of 3
for example means you have A: B: and C:, and so on.

Notes:

See also DQBdir$, DQBpath$, DQBdrive$, DQBsetDrive


Example:

See DQBdir$ example


-----------------------------------------------------------------------------
DQBpalOff SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBpalOff ()

Calling:

none

Returns:

none


Description:

By calling this function, the current palette is all set to black. This can
be used to turn off the screen when preparing it.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBpath$ FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBpath$ ()

Calling:

none

Returns:

A string holding the current drive path


Description:

DQBpath$ returns the actual full path of the current drive.

Notes:

See also DQBdir$, DQBdrive$, DQBnumDrives, DQBsetDrive


Example:

See DQBdir$ example


-----------------------------------------------------------------------------
DQBpauseSound SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBpauseSound ()

Calling:

none

Returns:

none


Description:

Pauses voices sound output.

Notes:

See also DQBresumeSound


Example:

none


-----------------------------------------------------------------------------
DQBplaySound SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBplaySound (BYVAL Slot, BYVAL Voice, BYVAL LoopFlag)

Calling:

   Slot        Slot holding the sound data
   Voice       Sound channel to use
   LoopFlag    Specifies to play the sound once or repeatedly

Returns:

none


Description:

Plays a sound effect previously stored into EMS by the DQBloadSound function
into a specified slot. The voice parameter can range from 1 to the maximum
number of voices specified when calling DQBinstallSB, and tells which sound
channel to use. If LoopFlag is 0, the sound is played once, while if the
LoopFlag is 1 the sound is looped. There are two constants defined into
DIRECTQB.BI that helps you using the LoopFlag parameter: they are the ONCE
and the LOOPED constants.

Notes:

If you play a sound while another one is still playing on the same voice,
the old one is stopped and the new starts. To stop any sound playing on a
voice, call DQBstopVoice.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layer and one sound
Result = DQBinit(0, 1)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

' Initializes the sound engine, by passing 220h as the base address and by
' autodetecting the IRQ and DMA settings. 2 voices are initialized
Result = DQBinstallSB(2, &H220, AUTO, AUTO)

IF Result<>0 THEN
    ' Bad initialization
    PRINT "Failed to initialize the sound engine; error" + STR$(Result)
    DQBclose
    END
END IF

' Asks the user for the location of a WAV file to load
INPUT "Insert the WAV file name to load:", File$

' Loads the sound in memory
Result = DQBloadSound(1, File$)

IF Result<>0 THEN
    ' Failed to load sound file
    PRINT "Failed to load " + File$ + "; error"+ STR$(Result)
    DQBclose
    END
END IF

PRINT "Press a key to exit..."

' Plays sound 1 on voice 2 once
DQBplaySound 1, 2, ONCE

' Waits a key
WHILE INKEY$ = "": WEND

' Turns off the sound engine (that's not really needed, as it's automatically
' done for you by the DQBclose function)
DQBremoveSB

' Ends program
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBpoint FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBpoint (BYVAL Layer, BYVAL x, BYVAL y)

Calling:

   Layer       Layer where to get the pixel from
   x           Pixel x coordinate
   y           Pixel y coordinate

Returns:

An INTEGER value holding the color number of specified pixel


Description:

Call this function to retrieve the color number of a specified pixel.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBpollJoy SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBpollJoy (BYVAL JoyNum)

Calling:

   JoyNum      Joystick number to retrieve information of

Returns:

none


Description:

This function must be always called before calling DQBjoyMove or DQBjoyFire,
as it updates the internal joystick variables. The JoyNum parameter must be
0 or 1 for joystick 1 and 2; there're two contants for this purpose, as
explained into appendix A.

Notes:

This is a relatively slow operation; in addition, if specified joystick is
not connected, this will be even slower, so it is recommended that you check
if the joystick is available before calling DQBpollJoy.


Example:

See DQBjoyMove example


-----------------------------------------------------------------------------
DQBprint SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBprint (Layer AS INTEGER, Text AS STRING, x AS INTEGER,
                      y AS INTEGER, Col AS INTEGER)

Calling:

   Layer       Layer where to draw the text
   Text        String to print
   x           X position of upper left corner of the first character
   y           Y position of upper left corner of the first character
   Col         Text color

Returns:

none


Description:

This function will print the specified string onto the given layer. By
default, the VGA BIOS font is used, but any font can be used by first calling
DQBsetFont. Also, the last style selected by DQBsetTextStyle is used. The x
and y parameters are in pixel units, so you can print the text anywhere on
specified layer.

Notes:

DQBprint supports clipping, so pixels outside the clipping box will not be
drawn. See also DQBprints, DQBsetTextStyle, DQBsetFont and DQBsetBIOSfont.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

' Prints text on the center of the screen in bright red
DQBprint VIDEO, "This is a DQBprint test!", 64, 96, 40

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBprints SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBprints (Layer AS INTEGER, Text AS STRING, x AS INTEGER,
                       y AS INTEGER, Col AS INTEGER, Style AS INTEGER)

Calling:

   Layer       Layer where to draw the text
   Text        String to print
   x           X position of upper left corner of the first character
   y           Y position of upper left corner of the first character
   Col         Text color
   Style       Custom text style

Returns:

none


Description:

DQBprints works exactly like DQBprint, but it requires an additional parameter
that allows to specify the style of the output text. Specified style is
applied only to one call of this function; once the text has been drawn, the
original text style is restored. For the styles, see appendix A for a list of
constants, and take a look at the DQBsetTextStyle function.

Notes:

DQBprints supports clipping, so pixels outside the clipping box will not be
drawn. See also DQBprint, DQBsetTextStyle, DQBsetFont and DQBsetBIOSfont.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

' Uses normal font with DQBprint
DQBprint VIDEO, "This is a normal text", 0, 0, 31

' Uses normal font with the bold style
DQBprints VIDEO, "I'm big and fat, I'm bold style!", 0, 10, 31, BOLD
' Uses italic style on the same font
DQBprints VIDEO, "Italic style is very nice", 0, 20, 31, ITALIC
' Uses underlined style again on the same font
DQBprints VIDEO, "Pay attention to underlined text", 0, 30, 31, UNDERLINED
' Uses a combination of styles on the same font
DQBprints VIDEO, "Bold and italic together!", 0, 40, 31, BOLD + ITALIC

' Back to normal text
DQBprint VIDEO, "That's all folks!", 0, 50, 31

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBpset SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBpset (BYVAL Layer, BYVAL x, BYVAL y, BYVAL Col)

Calling:

   Layer       Layer where to draw the pixel
   x           Pixel x coordinate
   y           Pixel y coordinate
   Col         Pixel color

Returns:

none


Description:

Sets a pixel onto specified layer, at given coordinates and with Col color.

Notes:

This function is affected by the clipping box set by DQBsetClipBox.


Example:

none


-----------------------------------------------------------------------------
DQBput SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBput (BYVAL Layer, BYVAL x, BYVAL y, BYVAL SpriteSeg,
                    BYVAL SpriteOff)

Calling:

   Layer       Layer where to draw the sprite
   x           X position of upper left corner of the sprite
   y           Y position of upper left corner of the sprite
   SpriteSeg   Segment of the array holding the sprite data; use VARSEG
   SpriteOff   Offset of the array holding the sprite data; use VARPTR

Returns:

none


Description:

Draws the sprite contained into the given array on specified layer, at the
given coordinates. DQBput can operate both in transparent and solid mode:
when the first mode is set, pixels with color 0 of the sprite are skipped,
allowing a transparent put, when the second mode is set, all the pixels are
copied to the layer, destroying the background. By default the put mode is
set to transparent, but it can be changed at any time by simply calling
DQBsetTransPut and DQBsetSolidPut.

Notes:

DQBput is affected by the clipping box, so pixels outside this box will not
be drawn. The sprite data format is compatible with normal GET and PUT, so
you can get you sprite data by calling either GET or DQBget. See also DQBfPut,
DQBsPut, DQBrPut and DQBbPut.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE: 'DIRECTQB.BI'

' Let's initialize the library with one extra layer and no sounds
Result = DQBinit(1, 0)

IF Result <> 0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

' We're going to use 15 sprite 16x16 pixels each; let's call DQBsize to
' know the dimension of our sprite array (we'll store all the sprites into
' the same array) in bytes
Size = DQBsize(0, 0, 15, 15)
' Our array is made of INTEGERs, so we divide Size by 2
DIM Sprite((Size \ 2) * 15)

' Let's prepare our sprites
FOR i = 0 TO 14

  ' Let's clear layer 1
  DQBclearLayer 1

  ' Draws a frame of our sprite
  DQBbox 1, 0, 0, 15, 15, 4
  DQBline 1, (15-i), 15, i, 0, 40
  DQBline 1, 15, i, 0, (15 - i), 40

  ' Saves the frame into our array
  DQBget 1, 0, 0, 15, 15, VARSEG(Sprite(0)), VARPTR(Sprite(0)) + (Size * i)

NEXT i

DQBinitVGA

FOR i = -16 TO 320

  ' Empties layer 1
  DQBclearLayer 1

  ' Finds what frame to draw
  Frame = ((i + 16) \ 2) MOD 15

  ' Draws our frame into layer 1
  DQBput 1, i, 92, VARSEG(Sprite(0)), (VARPTR(Sprite(0)) + (Size * Frame))

  ' Waits for vertical retrace 1 time
  DQBwait 1

  ' Copies layer 1 onto the screen
  DQBcopyLayer 1, VIDEO

NEXT i

' Ends program
DQBinitText
DQBclose

*****************************************************************************

-----------------------------------------------------------------------------
DQBreadBit FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBreadBit (BYVAL Value, BYVAL Bit)

Calling:

   Value       INTEGER value to read bit status from
   Bit         Bit number, ranging 0-15, to retrieve status of

Returns:

True if specified bit is set, otherwise false


Description:

This function returns true if a specified bit of a specified integer value
is set. It can be useful to store boolean variables into an unique INTEGER
one, as QB does not support booleans. An integer can contain up to 16 boolean
variables!

Notes:

See DQBsetBit, DQBresetBit and DQBtoggleBit


Example:

none


-----------------------------------------------------------------------------
DQBreadKey FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBreadKey ()

Calling:

none

Returns:

An INTEGER value holding the scancode number of the key that has been pressed


Description:

DQBreadKey wait for the user to press a key, and then returns its scancode.
This function works only if the keyboard interrupt handler has been installed
by calling DQBinstallKeyBoard.

Notes:

See DQBinstallKeyboard, DQBkey, DQBwaitKey


Example:

none


-----------------------------------------------------------------------------
DQBremoveKeyboard SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBremoveKeyboard ()

Calling:

none

Returns:

none


Description:

Turns off the custom keyboard interrupt handler if it was on, giving the
keyboard control back to the old BIOS routines. This function is automatically
called by DQBclose.

Notes:

See also DQBinstallKeyboard


Example:

See DQBkey example


-----------------------------------------------------------------------------
DQBremoveSB SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBremoveSB ()

Calling:

none

Returns:

none


Description:

Stops all the sounds playing and turns off the sound engine. This function is
automatically called for you by DQBclose, so there's no particular need to
call it.

Notes:

See also DQBinstallSB


Example:

none


-----------------------------------------------------------------------------
DQBresetBit FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBresetBit (BYVAL Value, BYVAL Bit)

Calling:

   Value       INTEGER variable to reset bit of
   Bit         Bit number to reset, ranging 0-15

Returns:

An INTEGER value representing the old variable value with specified bit reset


Description:

Call this function to zero a bit of a specified variable. This can be useful
to handle boolean variables.

Notes:

See DQBsetBit, DQBreadBit and DQBtoggleBit


Example:

none


-----------------------------------------------------------------------------
DQBresetJoy SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBresetJoy ()

Calling:

none

Returns:

none


Description:

Resets the joysticks by recalibrating them (where they are available).

Notes:

none


Example:

none



-----------------------------------------------------------------------------
DQBresetMouse SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBresetMouse ()

Calling:

none

Returns:

none


Description:

Resets the default mouse cursor shape and sets mouse range to (0,0)-(319,199).
This function should be called just after entering mode 13h.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBresumeSound SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBresumeSound ()

Calling:

none

Returns:

none


Description:

Resume sound output paused by DQBpauseSound.

Notes:

See also DQBpauseSound


Example:

none


-----------------------------------------------------------------------------
DQBrPut SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBrPut (BYVAL Layer, BYVAL x, BYVAL y, BYVAL SpriteSeg,
                     BYVAL SpriteOff, BYVAL Angle, BYVAL Zoom)

Calling:

   Layer       Layer where to draw the sprite
   x           X position of upper left corner of the sprite
   y           Y position of upper left corner of the sprite
   SpriteSeg   Segment of the array holding the sprite data; use VARSEG
   SpriteOff   Offset of the array holding the sprite data; use VARPTR
   Angle       Rotation angle ranging 0-255
   Zoom        Zoom factor

Returns:

none


Description:

DQBrPut draws a sprite rotated and scaled of the specified values. The angle
can range from 0 to 255 (256=0), while the zoom factor represents the zooming
percentage: a value of 100 will draw the sprite in its original size, a value
of 50 will draw a sprite of half its original size, etc... The rotation uses
a pixel-perfect algorithm, but rotated pixels that lie outside the original
sprite mask will not be drawn; this means that if you want to rotate a sprite
without loosing graphics, you must get it into a bigger area. For example,
let's suppose you have a 16x16 pixels sprite: you should get an area of 22x22
pixels to be sure not to loose any pixel when rotating. The same goes when
zooming in: the original sprite area is respected.

Notes:

DQBrPut supports clipping and transparency. See also DQBput, DQBfPut, DQBsPut
and DQBbPut.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE: 'DIRECTQB.BI'

' Let's initialize the library with one extra layer and no sounds
Result = DQBinit(1, 0)

IF Result <> 0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

' Let's use an 80x80 pixels sprite
Size = DQBsize(0, 0, 79, 79)
' Our array is made of INTEGERs, so we divide Size by 2
DIM Sprite(Size \ 2)

' Let's prepare our sprite
DQBclearLayer 1
DQBprint 1, "DirectQB!", 8, 36, 40
DQBget 1, 0, 0, 79, 79, VARSEG(Sprite(0)), VARPTR(Sprite(0))

DQBinitVGA

FOR i = 0 TO 90

  ' Empties layer 1
  DQBclearLayer 1

  ' Draws our roto-zoomed sprite into layer 1
  DQBrPut 1, 120, 60, VARSEG(Sprite(0)), VARPTR(Sprite(0)), (90 - i), (10 + i)

  ' Waits for vertical retrace 1 time
  DQBwait 1

  ' Copies layer 1 onto the screen
  DQBcopyLayer 1, VIDEO

NEXT i

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBsaveBMap FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBsaveBMap (FileName AS STRING)

Calling:

   FileName    Blender map file name with full extension

Returns:

An INTEGER value holding the saving results:

>   0     Operation successful
>   1     Blender map not yet created
>   2     Cannot create file or disk error
>   3     Unable to write data or disk full


Description:

This function saves the current blender map data to disk. The bmap can be
then loaded again in memory by calling DQBloadBMap.

Notes:

See also DQBcreateBMap, DQBloadBMap


Example:

none


-----------------------------------------------------------------------------
DQBsaveLayer FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBsaveLayer (Layer AS INTEGER, FileName AS STRING,
                               Pal AS STRING, Format AS INTEGER)

Calling:

   Layer       Layer to save
   FileName    New image file name with full extension
   Pal         String holding the palette to save (only for BMP and PCX)
   Format      Image file format

Returns:

An INTEGER value holding the saving results:

>   0     Operation successful
>   1     Cannot create file or disk error
>   2     Unable to write data or disk full


Description:

Call this function to save the contents of a layer to a file. Layers can be
saved in three different formats: BSAVE compatible, BMP or PCX. When saving
in the BSAVE format, you can load the image by simply calling the QB command
BLOAD, but the palette will be lost. In addition, BSAVEd images are large
files, but they're the fastest to load. When using the BMP format, the
resulting file will be even larger, but it'll contain the palette and you'll
also have the benefits of a common file format. PCX is the smallest available
file format, and contains the palette, but it's also the slowest to load.
The palette to save with the file (if using the BMP or PCX formats) must have
been previously stored into a string as explained into appendix A, by calling
DQBgetPal or even DQBloadLayer. This is done to allow saving hidden layers
with a palette different from the current one.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBscroll SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBscroll (BYVAL Layer, BYVAL dx, BYVAL dy)

Calling:

   Layer       Layer to be scrolled
   dx          Horizontal scrolling offset
   dy          Vertical scrolling offset

Returns:

none


Description:

Scrolls selected layer. A positive dx value will scroll the layer right, a
negative one will scroll it left. Positive dy value scrolls down, negative up;
by combining these parameters you can scroll the layer in any direction. The
newly visible area will be filled with garbage, to it's up to the programmer
to fill it with new graphics.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBsetBIOSfont SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetBIOSfont ()

Calling:

none

Returns:

none


Description:

Resets the current font to the standard VGA BIOS one. Nexts calls to DQBprint
will use the BIOS font.

Notes:

none


Example:

See DQBprint example


-----------------------------------------------------------------------------
DQBsetBit FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBsetBit (BYVAL Value, BYVAL Bit)

Calling:

   Value       INTEGER variable to set bit of
   Bit         Bit number to set, ranging 0-15

Returns:

An INTEGER value representing the old variable value with the new bit set


Description:

Call this function to set a bit of a specified variable. This can be useful
to create boolean variables.

Notes:

See DQBresetBit, DQBreadBit and DQBtoggleBit


Example:

none


-----------------------------------------------------------------------------
DQBsetBMap SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetBMap (BYVAL ForeCol, BYVAL BackCol, BYVAL NewCol)

Calling:

   ForeCol     Foreground color
   BackCol     Background color
   NewCol      Color of the resulting combination

Returns:

none


Description:

Sets a color for the specified combination on the blender map.

Notes:

See also DQBcreateBMap, DQBgetBMap, DQBloadBMap and DQBsaveBMap


Example:

See DQBbPut example


-----------------------------------------------------------------------------
DQBsetClipBox SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetClipBox (BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2)

Calling:

   x1          Upper left corner x coordinate of clipping box
   y1          Upper left corner y coordinate of clipping box
   x2          Lower right corner x coordinate of clipping box
   y2          Lower right corner y coordinate of clipping box

Returns:

none


Description:

Sets the current clipping box to (x1,y1)-(x2,y2). Next calls to all the
drawing functions (except DQBbox and DQBboxf) will be affected by the new
clipping box.

Notes:

The clipping box is set to (0,0)-(319,199) at startup.


Example:

none


-----------------------------------------------------------------------------
DQBsetCol SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetCol (BYVAL Col, BYVAL Red, BYVAL Green, BYVAL Blue)

Calling:

   Col         Color to change
   Red         New red hue
   Green       New green hue
   Blue        New blue hue

Returns:

none


Description:

Sets the hues of a given color index. The red, green and blue hues must be in
the range 0-63.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBsetDrive SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetDrive (Drive AS STRING)

Calling:

   Drive       New drive letter

Returns:

none


Description:

This function changes the current drive to the new one specified by the letter
of the Drive parameter.

Notes:

See also DQBdrive$, DQBdir$, DQBpath$, DQBnumDrives


Example:

none


-----------------------------------------------------------------------------
DQBsetFont SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetFont (Font AS STRING)

Calling:

   Font        String of 2305 characters holding the new font data

Returns:

none


Description:

Sets the current font to specified one held into the Font string (see appendix
C for details on the font data format). Next calls to DQBprint or DQBprints
will use the new font to draw characters.

Notes:

Font data format in DQB 1.3 is different than in the previous versions; the
data string now must be of 2305 characters, as it also holds characters width
and height. I suggest you to use DirectQB Tools to create your own fonts, and
to convert your old ones into the new format.
See also DQBsetBIOSfont


Example:

none


-----------------------------------------------------------------------------
DQBsetMousePos SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetMousePos (BYVAL x, BYVAL y)

Calling:

   x           x coordinate of new mouse position
   y           y coordinate of new mouse position

Returns:

none


Description:

Sets the new mouse position to (x,y).

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBsetMouseRange SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetMouseRange (BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2)

Calling:

   x1          Upper left corner x coordinate of new range box
   y1          Upper left corner y coordinate of new range box
   x2          Lower right corner x coordinate of new range box
   y2          Lower right corner y coordinate of new range box

Returns:

none


Description:

Sets the new mouse range to (x1,y1)-(x2,y2).

Notes:

Mouse range is set to (0,0)-(319,199) at startup.


Example:

none


-----------------------------------------------------------------------------
DQBsetMouseShape SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetMouseShape (hotX AS INTEGER, hotY AS INTEGER, Shape AS
                              STRING)

Calling:

   hotX        New cursor x hotspot coordinate
   hotY        New cursor y hotspot coordinate
   Shape       New cursor shape data string

Returns:

none


Description:

Sets the new cursor shape to specified one. There's no need to hide the mouse
before calling this function, and then to show it again after the operation,
as this is automatically done for you by this function. See appendix C for
details on the mouse cursor shape data format.

Notes:

Call DQBresetMouse to restore the default mouse cursor shape. This will also
reset the mouse range box to (0,0)-(319,199), so be warned.


Example:

none


-----------------------------------------------------------------------------
DQBsetMouseSpeed SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetMouseSpeed (BYVAL Hor, BYVAL Ver)

Calling:

   Hor         New horizontal mouse speed
   Ver         New vertical mouse speed

Returns:

none


Description:

Sets the new mouse horizontal and vertical speed. By default, both speeds are
set to 16; smaller values will make the mouse movement faster, bigger values
will have the opposite effect.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBsetPal SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetPal (Pal AS STRING)

Calling:

   Pal         New palette data string

Returns:

none


Description:

Sets the current palette to the new specified one. See appendix C for details
on the palette data format.

Notes:

See also DQBgetPal


Example:

See DQBfadeTo example


-----------------------------------------------------------------------------
DQBsetSamplingRate SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetSamplingRate (Rate AS INTEGER)

Calling:

   Rate        New sampling rate in Hz

Returns:

none


Description:

Sets the current sampling rate for the sound engine; it can range from 4000
up to 22000 Hz. By default, the sampling rate is set to 11000 Hz at startup.

Notes:

See also DQBinstallSB


Example:

none


-----------------------------------------------------------------------------
DQBsetSolidPut SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetSolidPut ()

Calling:

none

Returns:

none


Description:

Sets the solid put mode. Next calls to DQBput or DQBscaledPut will ignore
transparent color.

Notes:

See also DQBsetTransPut


Example:

See DQBput example


-----------------------------------------------------------------------------
DQBsetSolidText SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetSolidText ()

Calling:

none

Returns:

none


Description:

Sets the solid text mode. Next calls to DQBprint will fill the text background
with the current text background color.

Notes:

This function is obsolete; use DQBsetTextStyle instead.
See also DQBsetTextStyle, DQBsetTransText and DQBsetTextBackCol


Example:

See DQB print example


-----------------------------------------------------------------------------
DQBsetTextBackCol SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetTextBackCol (BYVAL Col)

Calling:

   Col         New text background color

Returns:

none


Description:

Sets the current text background color; this will be used only if in solid
text mode.

Notes:

By default, the text background color is 0. See also DQBsetSolidText,
DQBsetTransText, DQBsetTextStyle and DQBprint.


Example:

none


-----------------------------------------------------------------------------
DQBsetTextStyle SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetTextStyle (BYVAL Style)

Calling:

   Style       New text style

Returns:

none


Description:

Sets the current text style used by DQBprint. The style is indipendent from
the current font; the available styles are bold, italic and underlined. To use
no styles just pass the NONE constant to this function. DQBsetTextStyle allows
also to set the transparent or solid text mode; by default, the transparent
mode is set, but by passing the SOLID constant, next calls to DQBprint will
print solid text. You can use combinations of all the styles, by simply
adding the right constants, that can be found in appendix A.

Notes:

See also DQBprint, DQBprints, DQBsetSolidText and DQBsetTransText.


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
Result = DQBinit(0, 0)

IF Result<>0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

DQBinitVGA

' Uses normal font with DQBprint
DQBprint VIDEO, "This is a normal text", 0, 0, 31

' Let's set solid italic style...
DQBsetTextStyle SOLID + ITALIC
' ...and red background color
DQBsetTextBackCol 4

' Prints something using the new style
DQBprint VIDEO, "And this is solid italic text!", 0, 50, 31

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBsetTextureSize SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetTextureSize (BYVAL Size)

Calling:

   Size        New texture width

Returns:

none


Description:

Unlike the name says, DQBsetTextureSize is used to set only the width of the
texture used by subsequent calls to DQBttri. The width must be specified in
pixels and must be a power of 2; values that are not powers of 2 will be
rounded to the previous power, so that if you give 63 the function will assume
it's a 32, and if you give a 64, it'll assume it's a 64, etc... There are no
limits about the height of a texture, you only have to care about the texel
coordinates of the vertexes of your triangle.

Notes:

By default, the texture size is set to 64; see also DQBttri.


Example:

none


-----------------------------------------------------------------------------
DQBsetTransPut SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetTransPut ()

Calling:

none

Returns:

none


Description:

Sets the transparent put mode. Next calls to DQBput or DQBscaledPut will draw
transparent sprites.

Notes:

See also DQBsetSolidPut


Example:

See DQBput example


-----------------------------------------------------------------------------
DQBsetTransText SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetTransText ()

Calling:

none

Returns:

none


Description:

Sets the transparent text mode. Next calls to DQBprint will not destroy the
text background, allowing transparency.

Notes:

This function is obsolete; use DQBsetTextStyle instead.
By default, the transparent text mode is set at startup. See also
DQBsetSolidText and DQBsetTextStyle.


Example:

See DQBprint example


-----------------------------------------------------------------------------
DQBsetVoiceVol SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetVoiceVol (BYVAL Voice,BYVAL Volume)

Calling:

   Voice       Voice to change volume of
   Volume      New voice volume setting

Returns:

none


Description:

Sets the volume setting for a specified voice; it may range from 0 to 31.

Notes:

By default the volume setting for all the voices is 31; remember that the
volume of a voice also depends on the master volume setting.


Example:

none


-----------------------------------------------------------------------------
DQBsetVolume SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsetVolume (BYVAL Volume)

Calling:

   Volume      New master volume setting

Returns:

none


Description:

Sets the master volume setting for sound output; it may range from 0 to 15.

Notes:

There's no default volume setting, so it is recommended that you set the
volume as you wish just after calling DQBinstallSB in your programs.

Example:

none


-----------------------------------------------------------------------------
DQBshiftLeft FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBshiftLeft (BYVAL Value, BYVAL NumBits)

Calling:

   Value       INTEGER value to shift
   NumBits     Number of bits to shift left

Returns:

An INTEGER value representing the shifted number


Description:

Performs a logical shift left of the given integer value, and returns the
result. This can be useful to multiply by powers of 2 a given number, as this
operation is faster than *.

Notes:

See also DQBshiftRight


Example:

none


-----------------------------------------------------------------------------
DQBshiftRight FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBshiftRight (BYVAL Value, BYVAL NumBits)

Calling:

   Value       INTEGER value to shift
   NumBits     Number of bits to shift right

Returns:

An INTEGER value representing the shifted number


Description:

Performs a logical shift right of the given integer value, and returns the
result. This can be useful to divide by powers of 2 a given number, as this
operation is faster than \.

Notes:

See also DQBshiftLeft


Example:

none


-----------------------------------------------------------------------------
DQBsize FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBsize (BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2)

Calling:
                
   x1          Upper left corner x coordinate
   y1          Upper left corner y coordinate
   x2          Lower right corner x coordinate
   y2          Lower right corner y coordinate

Returns:

An INTEGER value holding the sprite size in bytes


Description:

DQBsize returns the number of bytes needed to store the image contained into
the box given by (x1,y1)-(x2,y2) with DQBget. This value can be then used to
dimension arrays to store the sprite data for the DQBget and DQBput routines.
Remember that the array is made of INTEGERs while this function returns the
number of bytes; just divide its result by 2 to obtain the array dimension.

Notes:

This function can be useful when storing several sprites into the same array,
to know the exact offset of each frame.


Example:

See DQBput example


-----------------------------------------------------------------------------
DQBsort SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsort (BYVAL ArraySeg, BYVAL ArrayOff, BYVAL NumElems)

Calling:
                
   ArraySeg    Segment of the array of integers to sort; use VARSEG
   ArrayOff    Offset of the array of integers to sort; use VARPTR
   NumElems    Number of elements to sort

Returns:

none


Description:

DQBsort uses a bubble sort algorithm to sort a given array of integers from
the lower value to the higher one.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBsPut SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBsPut (BYVAL Layer, BYVAL x, BYVAL y, BYVAL SpriteSeg,
                     BYVAL SpriteOff, BYVAL NewWidth, BYVAL NewHeight)

Calling:

   Layer       Layer where to draw the sprite
   x           X position of upper left corner of the sprite
   y           Y position of upper left corner of the sprite
   SpriteSeg   Segment of the array holding the sprite data; use VARSEG
   SpriteOff   Offset of the array holding the sprite data; use VARPTR
   NewWidth    New sprite width in pixel units
   NewHeight   New sprite height in pixel units

Returns:

none


Description:

DQBsPut works like DQBput, but allows to draw a scaled version of your sprite,
by specifying its new width and height; the sprite data is not modified during
this operation. This function also supports clipping and transparency.

Notes:

See DQBput, DQBfPut, DQBrPut and DQBbPut


Example:

See DQBput example


-----------------------------------------------------------------------------
DQBstopVoice SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBstopVoice (BYVAL Voice)

Calling:
                
   Voice       Voice to stop

Returns:

none


Description:

Stops any sound coming from specified voice; you can use this to stop a
looping sample...

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBtoggleBit FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBtoggleBit (BYVAL Value, BYVAL Bit)

Calling:

   Value       INTEGER value to toggle bit of
   Bit         Bit number to toggle

Returns:

An INTEGER value representing the original number with specified bit toggled.


Description:

Toggles specified bit of the given number, and returns the result.

Notes:

See also DQBsetBit, DQBresetBit and DQBreadBit


Example:

none


-----------------------------------------------------------------------------
DQBtri SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBtri (BYVAL Layer, BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2,
                    BYVAL x3, BYVAL y3, BYVAL Col)

Calling:

   Layer       Layer where to draw the triangle
   x1          x coordinate of the first vertex
   y1          y coordinate of the first vertex
   x2          x coordinate of the second vertex
   y2          y coordinate of the second vertex
   x3          x coordinate of the third vertex
   y3          y coordinate of the third vertex
   Col         color


Returns:

none


Description:

Draws a flat-shaded triangle with (x1,y1), (x2,y2) and (x3,y3) as vertex,
filled with specified color. DQBtri does not support transparency, but it's
affected by the clipping box.

Notes:

See also DQBgtri


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
IF DQBinit(0, 0) THEN PRINT "Initialization error!": DQBclose: END

DQBinitVGA

' Draws 500 flat-shaded triangles
FOR i = 1 TO 500
  DQBtri VIDEO, (RND * 320), (RND * 200), (RND * 320), (RND * 200), (RND * 320), (RND * 200), (RND * 256)
NEXT i

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBttri SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBttri (BYVAL Layer, BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2,
                     BYVAL x3, BYVAL y3, BYVAL u1, BYVAL v1, BYVAL u2,
                     BYVAL v2, BYVAL u3, BYVAL v3, BYVAL TextureSeg,
                     BYVAL TextureOff)

Calling:

   Layer       Layer where to draw the triangle
   x1          x coordinate of the first vertex
   y1          y coordinate of the first vertex
   x2          x coordinate of the second vertex
   y2          y coordinate of the second vertex
   x3          x coordinate of the third vertex
   y3          y coordinate of the third vertex
   u1          x coordinate of first vertex on texture
   v1          y coordinate of first vertex on texture
   u1          x coordinate of second vertex on texture
   v1          y coordinate of second vertex on texture
   u1          x coordinate of third vertex on texture
   v1          y coordinate of third vertex on texture
   TextureSeg  Array segment holding the texture (use VARSEG)
   TextureOff  Array offset holding the texture (use VARPTR)


Returns:

none


Description:

Draws a texture-mapped triangle with (x1,y1), (x2,y2) and (x3,y3) as vertexes.
The texture used must be stored into specified array with GET or DQBget, and
its width must be a power of 2, equal to the one specified by calling
DQBsetTextureSize (the default texture width is 64 pixels). Each vertex of
the triangle has also its own texture coordinates, that can be anywhere on
the texture itself. DQBttri supports transparency (color 0 on the texture is
*always* handled as transparent color) and clipping.

Notes:

See also DQBsetTextureSize, DQBtri, DQBbtri, DQBgtri


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Dimension our 64x64 pixels texture array
DIM Texture(2049)

' Let's initialize the library with no extra layers nor sounds
IF DQBinit(0, 0) THEN PRINT "Initialization error!": DQBclose: END

DQBinitVGA

' Let's build our sample texture
FOR i = 0 TO 15
  DQBbox VIDEO, i, i, 63 - i, 63 - i, 31 - i
  DQBbox VIDEO, 16 + i, 16 + i, 47 - i, 47 - i, 16 + i
NEXT i
DQBbox VIDEO, 0, 0, 63, 63, 40
DQBline VIDEO, 0, 0, 63, 63, 4
DQBellipse VIDEO, 32, 32, 24, 24, 43

' Gets our texture and clears the screen
DQBget VIDEO, 0, 0, 63, 63, VARSEG(Texture(0)), VARPTR(Texture(0))
DQBclearLayer VIDEO

' Draws 500 textured triangles
FOR i = 1 TO 500
  DQBttri VIDEO, (RND * 320), (RND * 200), (RND * 320), (RND * 200), (RND * 320), (RND * 200), 0, 0, 63, 0, 0, 63, VARSEG(Texture(0)), VARPTR(Texture(0))
NEXT i

' Ends program
DQBinitText
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBver FUNCTION
-----------------------------------------------------------------------------

Prototype:

DECLARE FUNCTION DQBver ()

Calling:

none

Returns:

An INTEGER value holding the library version


Description:

DQBver returns the current DirectQB library version into an integer value. The
higher byte represents the major version, and the lower byte the minor version
number.

Notes:

none


Example:

*****************************************************************************

' All integers for speed
DEFINT A-Z

'$INCLUDE:'DIRECTQB.BI'

' Let's initialize the library with no extra layers nor sounds
IF DQBinit(0, 0) THEN PRINT "Initialization error!": DQBclose: END

' Finds major and minor library version numbers
major = DQBver \ &H100
minor = DQBver AND &HFF

' Prints them
PRINT "You are using DirectQB version" + STR$(major) + "." + LTRIM$(STR$(minor))

' Ends program
DQBclose

*****************************************************************************


-----------------------------------------------------------------------------
DQBwait SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBwait (BYVAL Times)

Calling:

   Times       Times to wait for the video vertical retrace

Returns:

none


Description:

Waits for the video vertical retrace Times times. It is suggested to wait for
the vertical retrace a time before drawing anything on the screen: this will
produce flickerless animations. The vertical retrace occurs 60 times per
second, so you can use this function also as delay routine.

Notes:

none


Example:

none


-----------------------------------------------------------------------------
DQBwaitKey SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBwaitKey (BYVAL ScanCode)

Calling:

   Scancode    Scancode of the key to wait for

Returns:

none


Description:

Waits for the user to press the key specified by the scancode passed to the
function. DQBwaitKey works only if the keyboard interrupt handler has been
installed by calling DQBinstallKeyboard.

Notes:

See DQBinstallKeyboard, DQBkey, DQBreadKey


Example:

none


-----------------------------------------------------------------------------
DQBxPut SUB
-----------------------------------------------------------------------------

Prototype:

DECLARE SUB DQBput (BYVAL SourceLayer, BYVAL x1, BYVAL y1, BYVAL x2, BYVAL y2,
                    BYVAL DestLayer, BYVAL x, BYVAL y)

Calling:

   SourceLayer   Layer where to get the sprite (source)
   x1            x position of upper left corner of the sprite on source
   y1            y position of upper left corner of the sprite on source
   x2            x position of lower right corner of the sprite on source
   y2            y position of lower right corner of the sprite on source
   DestLayer     Layer where to draw the sprite (destination)
   x             x position of upper left corner of the sprite on destination
   y             y position of upper left corner of the sprite on destination

Returns:

none


Description:

Like normal DQBput, this function draws a sprite onto a specified layer, but
with a huge difference: DQBxPut does not require that you first get your
sprite into a QB array, as it automatically gets the data by assuming you
want to draw the sprite contained into the (x1,y1)-(x2,y2) box on the source
layer. Sprite data is directly copied into the destination layer at specified
(x,y) coordinates; this is great, but it has its weak spots... DQBxPut is
slower than DQBput, and it can only handle sprites with a height up to 50
pixels; higher sprites will not be drawn (but there are no limits for the
width).

Notes:

DQBxPut supports transparency and it's affected by the clipping box, so pixels
outside this box will not be drawn. See also DQBput, DQBfPut, DQBsPut, DQBrPut
and DQBbPut.


Example:

*****************************************************************************

' Here's a modified version of the DQBput example; this time we'll not use
' arrays to store our sprites...

' All integers for speed
DEFINT A-Z

'$INCLUDE: 'DIRECTQB.BI'

' Let's initialize the library with two extra layers and no sounds
Result = DQBinit(2, 0)

IF Result <> 0 THEN
    ' Something went wrong while initializing
    PRINT "Initialization error" + STR$(Result)
    DQBclose
    END
END IF

' Let's clear layer 2
DQBclearLayer 2

' Let's prepare our sprites on layer 2
FOR i = 0 TO 14

  ' Draws a frame of our sprite
  DQBbox 2, (i * 16), 0, (i * 16) + 15, 15, 4
  DQBline 2, (i * 16) + (15-i), 15, (i * 16) + i, 0, 40
  DQBline 2, (i * 16) + 15, i, (i * 16), (15 - i), 40

NEXT i

DQBinitVGA

FOR i = -16 TO 320

  ' Empties layer 1
  DQBclearLayer 1

  ' Finds what frame to draw
  Frame = ((i + 16) \ 2) MOD 15

  ' Draws our frame into layer 1
  DQBxPut 2, (Frame * 16), 0, (Frame * 16) + 15, 15, 1, i, 92

  ' Waits for vertical retrace 1 time
  DQBwait 1

  ' Copies layer 1 onto the screen
  DQBcopyLayer 1, VIDEO

NEXT i

' Ends program
DQBinitText
DQBclose

*****************************************************************************


=============================================================================
APPENDIX A - Library constants
=============================================================================

To simplify the use of certain functions, the file DIRECTQB.BI contains some
useful constants. Here's the list:

Constant name     Value   Can be used by
-----------------------------------------------------------------------------
TRUE              -1      General purpose, no specific function
FALSE             0       General purpose, no specific function
VIDEO             0       All the graphical functions that refer to a layer
BSV               0       DQBsaveLayer to specify to save in BSAVE format
BMP               1       DQBsaveLayer to specify to save in BMP format
PCX               2       DQBsaveLayer to specify to save in PCX format
NONE              0       DQBsetTextStyle, DQBprints to specify no styles
SOLID             1       DQBsetTextStyle, DQBprints to specify solid style
BOLD              2       DQBsetTextStyle, DQBprints to specify bold style
ITALIC            4       DQBsetTextStyle, DQBprints to specify italic style
UNDERLINED        8       DQBsetTextStyle, DQBprints to specify underlined st.
KEYESC            1       DQBkey to check the ESC key (see appendix B)
KEYENTER          28      DQBkey to check the ENTER key (see appendix B)
KEYSPACE          57      DQBkey to check the SPACE key (see appendix B)
KEYUP             72      DQBkey to check the up arrow key (see appendix B)
KEYDOWN           80      DQBkey to check the down arrow key (see appendix B)
KEYLEFT           75      DQBkey to check the left arrow key (see appendix B)
KEYRIGHT          77      DQBkey to check the right arrow key (see appendix B)
UP                0       DQBjoyMove to check if the joystick is moved up
DOWN              1       DQBjoyMove to check if the joystick is moved down
LEFT              2       DQBjoyMove to check if the joystick is moved left
RIGHT             3       DQBjoyMove to check if the joystick is moved right
JOY1              0       All the joystick routines to refer to joystick 1
JOY2              1       All the joystick routines to refer to joystick 2
GAMEPAD           2       All the joystick routines to refer to 4-buttons joys
BUTA              0       DQBjoyFire to check if joystick button A is pressed
BUTB              1       DQBjoyFire to check if joystick button B is pressed
BUTC              2       DQBjoyFire to check if gamepad button C is pressed
BUTD              3       DQBjoyFire to check if gamepad button D is pressed
AUTO              -1      DQBinstallSB to autodetect the soundcard settings
ONCE              0       DQBplaySound to play a sound once
LOOPED            1       DQBplaySound to play a sound repeatedly
ATTRIB.R          &H1     DQBdir$ attribute to search for read-only files
ATTRIB.H          &H2     DQBdir$ attribute to search for hidden files
ATTRIB.S          &H4     DQBdir$ attribute to search for system files
ATTRIB.L          &H8     DQBdir$ attribute to search for volume labels
ATTRIB.D          &H10    DQBdir$ attribute to search for directories
ATTRIB.A          &H20    DQBdir$ attribute to search for archive files


=============================================================================
APPENDIX B - Keyboard scancodes list
=============================================================================

To check the state (pressed or released) of a certain key with the DQBkey
function, you must pass its keyboard scancode as parameter. For the most used
keys there're some constants that help you, so check out appendix A.
For the other keys, here's the complete list of scancodes for all them (please
note that a single scancode can represent more than a single key):

Scancode  Key                           Scancode  Key
-----------------------------------------------------------------------------
 1        ESC                           44        Z
 2        1                             45        X
 3        2                             46        C
 4        3                             47        V
 5        4                             48        B
 6        5                             49        N
 7        6                             50        M
 8        7                             51        , or <
 9        8                             52        . or >
10        9                             53        / or ?
11        0                             54        RIGHT SHIFT
12        - or _                        55        * or PRINT SCREEN
13        = or +                        56        ALT (RIGHT and LEFT)
14        BACKSPACE                     57        SPACE
15        TAB                           58        CAPSLOCK
16        Q                             59        F1
17        W                             60        F2
18        E                             61        F3
19        R                             62        F4
20        T                             63        F5
21        Y                             64        F6
22        U                             65        F7
23        I                             66        F8
24        O                             67        F9
25        P                             68        F10
26        [ or {                        69        NUMLOCK
27        ] or }                        70        SCROLL LOCK
28        ENTER                         71        7 or HOME
29        CONTROL (RIGHT and LEFT)      72        8 or UP
30        A                             73        9 or PAGE UP
31        S                             74        -
32        D                             75        4 or LEFT
33        F                             76        5
34        G                             77        6 or RIGHT
35        H                             78        +
36        J                             79        1 or END
37        K                             80        2 or DOWN
38        L                             81        3 or PAGE DOWN
39        ; or :                        82        0 or INSERT
40        ' or "                        83        . or DEL
41        \ or ~                        87        F11
42        LEFT SHIFT                    88        F12


=============================================================================
APPENDIX C - Palette, cursor, font and blender map data format
=============================================================================

-----------------------------------------------------------------------------
The palette data format
-----------------------------------------------------------------------------

The palette parameter used by DQBsetPal, DQBgetPal, DQBfadeIn, DQBloadLayer
and DQBsaveLayer must be a string of 768 character. This string holds the
hues data for each of the 256 colors: three bytes per color, representing
the red, green and blue intensities ranging 0-63. So if you want to know the
green intesity of color 45 of given palette stored into the Pal string, here's
the simple code:

green = ASC(MID$(Pal, ((45 * 3) + 2), 1))
                        |         |
                        |          \ Change this with 1,2 or 3 to know the
                        |            red, green and blue hues
                         \ This is the color number; let's multiply it by 3
                          

-----------------------------------------------------------------------------
The mouse cursor data format
-----------------------------------------------------------------------------

When calling DQBsetMouseShape, you must pass a string of 64 characters as the
third parameter; this represents the cursor shape data.
Each cursor shape is a 16x16 pixels bitmap, composed of two masks of bits: the
so called "screen mask" and "cursor mask". The data is stored so that the
first 32 bytes of our string are the screen mask, and the other 32 are the
cursor mask. Two bytes (16 bits) make a cursor line, so we have 64 bytes
to define the two 16x16 pixels masks.
The screen mask specifies what part of the cursor is to be the shape and what
part is to be the background: a 0 means the background, a 1 means the shape.
The cursor mask tells what color to use into the mask. By combining these two
masks, the cursor is drawn onto the screen. Here are the combinations, with
their results on the screen:

Bit on screen mask            Bit on cursor mask          Pixel drawn
0                             0                           Black
0                             1                           White
1                             0                           Transparent
1                             1                           Inverted

I know it's hard, but it's even harder to explain... I'll try to make an
example. Let's look at the data below: this represents the default DirectQB
mouse cursor (the arrow).

&HFF,&H3F,&HFF,&H1F,&HFF,&H0F,&HFF,&H07     \
&HFF,&H03,&HFF,&H01,&HFF,&H00,&H7F,&H00      |
&H3F,&H00,&H7F,&H00,&HFF,&H0F,&HFF,&HBF      |--- Screen mask
&HFF,&HFF,&HFF,&HFF,&HFF,&HFF,&HFF,&HFF     /
&H00,&H00,&H00,&H40,&H00,&H60,&H00,&H70     \
&H00,&H78,&H00,&H7C,&H00,&H7E,&H00,&H7F      |
&H80,&H7F,&H00,&H70,&H00,&H40,&H00,&H00      |--- Cursor mask
&H00,&H00,&H00,&H00,&H00,&H00,&H00,&H00     /

Let's examine the bytes of our masks: just remember that of the two bytes that
make a cursor line, the first represents the last 8 pixels, and the second the
first 8.

Screen mask                             Cursor mask

&HFF,&H3F =   0011111111111111          &H00,&H00 =   0000000000000000
&HFF,&H1F =   0001111111111111          &H00,&H40 =   0100000000000000
&HFF,&H0F =   0000111111111111          &H00,&H60 =   0110000000000000
&HFF,&H07 =   0000011111111111          &H00,&H70 =   0111000000000000
&HFF,&H03 =   0000001111111111          &H00,&H78 =   0111100000000000
&HFF,&H01 =   0000000111111111          &H00,&H7C =   0111110000000000
&HFF,&H00 =   0000000011111111          &H00,&H7E =   0111111000000000
&H7F,&H00 =   0000000001111111          &H00,&H7F =   0111111100000000
&H3F,&H00 =   0000000000111111          &H80,&H7F =   0111111110000000
&H7F,&H00 =   0000000001111111          &H00,&H70 =   0111000000000000
&HFF,&H0F =   0000111111111111          &H00,&H40 =   0100000000000000
&HFF,&HBF =   1011111111111111          &H00,&H00 =   0000000000000000
&HFF,&HFF =   1111111111111111          &H00,&H00 =   0000000000000000
&HFF,&HFF =   1111111111111111          &H00,&H00 =   0000000000000000
&HFF,&HFF =   1111111111111111          &H00,&H00 =   0000000000000000
&HFF,&HFF =   1111111111111111          &H00,&H00 =   0000000000000000

The hotspot is passed to DQBsetMouseShape in pixel units. A hotspot of (0,0)
represents the upper-left corner of the cursor bitmap; the hotspot coordinates
can range from (-16,-16) to (16,16).

Now I know that it's not so easy to create a mouse cursor, so I made the
CUREDIT program, which is a cursor editor. You can use it to create and save
your cursors as DATA statements as well as into a binary file as strings of
64 characters.


-----------------------------------------------------------------------------
The font data format
-----------------------------------------------------------------------------

A font is contained into a string of 2305 characters. Each font holds the
graphical data for 256 characters (8 bytes per each character, so we have
8*256=the first 2048 bytes), the width in pixels of each of them (next 256
bytes, 1 byte for each character), and the height of all the characters (last
byte).
Each bit of the 8 bytes of graphical data of a character represents the state
of a pixel: 1 means the pixel is on, 0 that the pixel is off.
So let's examine the data for the following character:

00010000 =  &H10
00111000 =  &H38
01101100 =  &H6C
01101100 =  &H6C
11000110 =  &HC6
11111110 =  &HFE
11000110 =  &HC6
00000000 =  &H00

This would obviously represent an 'A'...
The pixels off will be transparent if in transparent text mode, otherwise it
will be set to the current text background color set by DQBsetTextBackCol.

Old fixed-sized fonts are no longer supported by DQBsetFont.
Use DirectQB Tools to create your own fonts; old fonts can be still loaded
from this utility, so you can use it to convert them into the new format.


-----------------------------------------------------------------------------
The blender map data format
-----------------------------------------------------------------------------

Creating a blender map is often a slow process. For this reason, I've coded
the DQBloadBMap and DQBsaveBMap functions; there merely saves the section of
memory holding the blender map table. This table is 65536 bytes long, as it
must support 256*256 color combinations. The data is so divided into 256
chunks, each holding 256 combinations for a foreground color. The high byte
is then the fore color, and the low byte is the back color; once you know
this, you have nothing else to know.


=============================================================================
APPENDIX D - Known bugs
=============================================================================

I've worked a lot to fix all the possible bugs of this library. Anyway I'm
not sure DirectQB is totally bug-free.
The main "bug" I've found is with the mouse initialization when calling
DQBinit. Sometimes on my K6-200 it locks up the machine, and you have to
reboot; this seems not to happen on my notebook with external mouse (Logitech),
so I'm supposing it's a mouse driver problem, also because theoretically my
code should work...
Again about the mouse, I've reported that the hotspot setting when calling
DQBsetMouseShape fails under Windows 95: to obtain the correct X hotspot
coordinate you must multiply your value by 2 and then pass it to the function.
This is very strange as all works ok when running the same code under plain
DOS, so I've not fixed it.
Another bug is on DQBscroll. This function works perfectly when handling
single pixel variations, but if you give the dy parameter a value smaller than
-4 your layer will not be scrolled. This bug still has not been fixed, but I
hope to solve it soon...
I've not found any more bugs on the library as by now; if you find others,
please let me know, and I'll try to fix them.


=============================================================================
APPENDIX E - Versions history
=============================================================================

version 1.0                 First version of DirectQB, with no sound support,
August, the 30th 1998       a mouse cursor editor plus a demo of the library.
                            DQBget and DQBput use a custom sprite data format,
                            which is not compatible with standard GET and PUT.

version 1.1                 After a month of waitings, version 1.1 brings a
October, the 3rd 1998       limited sound support, as only a sound effect can
                            be played at once. Sounds are stored and played
                            directly from EMS; the user just calls a function
                            to load and another one to play them. DQBget and
                            DQBput are now compatible with GET and PUT, and
                            DQBput has been optimized a lot. Also added an
                            even faster DQBfastPut, plus a DQBscaledPut
                            routines. Other functions here and there, plus a
                            working-on one to draw gouraud shaded triangles.

version 1.11                The sound engine bug has been fixed! Now you can
October, the 5th 1998       play up to 8 sound effects simultaneously!!
                            Also added customizable volume setting for each
                            of the eight voices...

version 1.2                 Added a lot of new routines. DirectQB now supports
October, the 27th 1998      roto-zooming effects, as well as color blending.
                            With the new blender map system, you can now build
                            virtually any color effect; also fixed some bugs
                            here and there, and added some extra sound handing
                            routines.

version 1.3                 Mainly internal enhancements; added an int 24h
November, the 15th 1998     handler for critical DOS errors. DQBxPut draws a
                            sprite without using external QB arrays, saving
                            memory; new faster DQBprint function now supports
                            non-fixed sized fonts, as well as different print
                            styles (normal, bold, italic, or underlined).
                            DirectQB has its first 3D functions! DQBtri and
                            DQBgtri draw flat-shaded and gouraud-shaded
                            triangles very quickly.

version 1.31                Finally added texture mapped triangle support;
November, the 23th 1998     most of the graphical functions have been
                            accelerated a little, plus other minor changes...



=============================================================================
Credits and final words
=============================================================================

DirectQB was entirely coded by Angelo Mottola of Enhanced Creations 1998

If you have any hints, suggestions or bug reports, please contact me by
sending an e-mail to the following address:

                           angelillo@bigfoot.com

Visit also the Enhanced Creations Homepage located at:

                        http://echome.hypermart.net

DirectQB is freeware. The only thing I'm asking you is that you write my name
somewhere in the credits section of your games if you use it.
Once finished, it would be nice for me to see your work!

Thanks for using DirectQB!

One last thing: have you noticed that the assembly source file is longer than
this documentation file? Pretty nice huh?
...And excuse my bad english!

