2D32 - Graphics Library

"The object oriented approach"

Programmer's Reference Guide

Beta Version 1.0

## Table of contents:

Introduction to the 2D32 Graphics Library Beta Version 1.0

Brief description of the library classes

Class: Graphix

Class description (overview).
Methods in class (overview).
Detailed description of the class and its methods.

Class: Bitmap

Class description (overview).
Methods in class (overview).
Detailed description of the class and its methods.

Class: Palette

Class description (overview).
Methods in class (overview).
Detailed description of the class and its methods.

Class: Keyboard

Class description (overview).
Methods in class (overview).
Detailed description of the class and its methods.

Class: Joystick

Class description (overview).
Methods in class (overview).
Detailed description of the class and its methods.

Class: Mouse

Class description (overview).
Methods in class (overview).
Detailed description of the class and its methods.

## Introduction to the 2D32 Graphics Library Beta Version 1.0.

Hi and welcome to the first official release of my graphic programming library 2D32.

This library is the result of hundreds of hours of spare time used for development during my third year of university studies at the University of Karlskrona/Ronneby. I'm now an educated Software Engineer and will hopefully make some money instead of working evenings and late nights just for fun. Well, here is the basic information about my library:

It's an optimized 32-bit C++ DOS library which hopefully will help some of you programmers out there when the need for SPEED is high, and you still want a SIMPLE and FLEXIBLE tool with all the low-level handling encapsulated into the library classes.

System requirement is: PC 386/486/Pentium with a VGA/SVGA (VESA 1.0) video card (with 2 Mb of video RAM if you want to use the highest screen resolution available together with maximum view port and page flipping. You can run the library on an ordinary 386 with a VGA card only and still do fine, but I don't recommend it! To be able to compile and link the library together with your programs you have to use Watcom C++ compiler v10.5 or higher.

If you don't have the Watcom compiler, don't worry, I have included executables for all example programs within this package. That is the reason to why I have used the internal linked protected mode handler 'pmodew' for all executables instead of the external handler 'dos/4gw' which is under protection of the copyright law.

Remember that this library is a DOS library and can therefore act strange sometimes in different screen resolutions (some of the VGA resolutions) if you are executing the example programs in Win95 (in a DOS window).

The library is object oriented and supports 23 different resolutions in VGA/SVGA, all in 256 colors. Page flipping is included for smooth animations.

My goal was to build a fast, flexible and an 'easy to use' tool with all the graphics stuff handled through transparency for the programmer. The programmer should not have to be aware of the details of how to program the VGA/SVGA card, use VESA, or the low-level routines but still achieve speed with simplicity. All the graphic primitives should work in the same way and give the same results regardless of which graphic video mode that is active for the moment. Setting the video mode should also be the same for all resolutions.

I put a lot of effort to make the library fast enough to make a neat game and still have the functionality and flexibility of creating a drawing program.

I also included support for different external devices such as the keyboard, joysticks and mouse.

Well, have I achieved my goals?

Some of them I think, but since my main goal is to make it as simple as possible for the programmer to use, some of the performance is lost. The object oriented solution can slow it down a bit even though the flexibility is enormous. There are many ways to optimize this further e.g. divide the VGA and SVGA into different libraries, change some 'dumb' classes into ordinary structs without states, use even more assembler routines, inline code and more. This can be done but first I would like to know if this library is worth working for as it is.

Now, the main reason to this beta release is for you to test the 2D32 library and see if it may do some good for you.

I would appreciate if I got some response from you regarding your opinion about this library. For example: is it easy to use/learn/understand, is it fast enough (ok, nothing can be fast enough), what functionality do you miss, any bugs found, is it worth to develop it further?

Feel free to send your comments to me. I'm a big boy and can handle it

J .

Since this version is a beta release, I consider this version of 2D32 as freeware, with some exceptions:

1. You may not change the contents within this package.

2. You may not use this package for any commercial purposes without my personal permission.

3. You may not reverse engineer or de-compile the library in any way.

(4). If you use this product in your own application I would appreciate a little greeting in your program.

The software is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

The entire risk as to the performance and operation of this product is with you. Should the software fail or prove defective, you assume the cost of all necessary repair or correction.

In no event will the author or any other party who may have distributed the software be liable to you for damages incurred by its use in any way.

Well, there is nothing more to say for the moment. Enjoy the tool!

Best regards from

Tommy Grändefors

##

## Methods of class Graphix

short int SetVideoMode(char, unsigned short int)

unsigned short int GetScreenWidth(void)

unsigned short int GetScreenHeight(void)

void SetPalette(Palette&)

void GetPalette(Palette&)

void PutPixel(short int, short int, unsigned char)

unsigned char GetPixel(short int, short int)

void SetDrawPage(unsigned int)

void SetVisiblePage(unsigned int)

void V_Line(short int, short int, short int, unsigned char)

void H_Line(short int, short int, short int, unsigned char)

void Box(short int, short int, short int, short int, unsigned char)

void FilledBox(short int, short int, short int, short int, unsigned char)

void Circle(short int, short int, short int, unsigned char)

void FilledCircle(short int, short int, short int, unsigned char)

void Line(short int, short int, short int, short int, unsigned char)

void ClearScreen(unsigned char)

void ClearVideoMemory(unsigned char)

void WaitVerticalRetrace(void)

void ScrollY(short int)

void SetScrollingSpeed(unsigned short int)

void ClearScrollingY(void)

char LoadRAW(char*, Bitmap&, Palette&, unsigned int, unsigned int, short int, unsigned char, unsigned char)

char LoadRAWTile(char*, Bitmap&, Palette&, unsigned int, unsigned int, unsigned int, unsigned int, short int, short int, unsigned char, unsigned char)

char SavedRAW(char*, Bitmap&, Palette&, short int)

char LoadPCX(char*, Bitmap&, Palette&, unsigned char, unsigned char)

char LoadPCXTile(char*, Bitmap&, Palette&, unsigned int, unsigned int, short int, unsigned char, unsigned char)

char SavePCX(char*, Bitmap&, Palette&)

void DrawBitmap(short int, short int, Bitmap&)

void GetRAMBitmap(short int, short int, short int, short int, Bitmap&, Bitmap&)

short int ConvertSolidToTransparentBitmap(Bitmap&, unsigned char)

void ConvertTransparentToSolidBitmap(Bitmap&)

void FlipBitmapVertical(Bitmap&)

void FlipBitmapHorizontal(Bitmap&)

void GetScreenBitmap(short int, short int, short int, short int, Bitmap&)

short int ScaleBitmap(Bitmap&, Bitmap&, short int, short int)

short int ScaleBitmapX(Bitmap&, Bitmap&, short int)

short int ScaleBitmapY(Bitmap&, Bitmap&, short int)

void Print(short int, short int, char[])

short int SetFontColor(unsigned char)

unsigned char GetFontColor(void)

## Methods of class Bitmap

unsigned short int GetWidth(void)

unsigned short int GetHeight(void)

unsigned short int GetXposition(void)

unsigned short int GetYposition(void)

void SetXposition(unsigned short int xPosition)

void SetYposition(unsigned short int yPosition)

void SetCollisionSensitivity(short int)

short int DetectBitmapCollision(short int, short int, Bitmap&, short int, short int)

short int DetectAreaCollision(short int, short int, short int, short int, short int, short int)

## Methods of class Palette

void ConvertToNegativePalette(void)

void ConvertToGreyScalePalette(void)

void RotatePalette(unsigned char)

void SetRed(unsigned char, unsigned char)

void SetGreen(unsigned char, unsigned char)

void SetBlue(unsigned char, unsigned char)

unsigned char GetRed(unsigned char)

unsigned char GetGreen(unsigned char)

unsigned char GetBlue(unsigned char)

void SetRGB(unsigned char, unsigned char, unsigned char, unsigned char)

void GetRGB(unsigned char, unsigned char&, unsigned char&, unsigned char&)

## Methods of class Keyboard

volatile int* InstallKeyboard(void)

void UnInstallKeyboard(void)

## Methods of class Joystick

unsigned char IsJoystickAvailable(void)

unsigned short int GetXpos(void)

unsigned short int GetYpos(void)

unsigned char IsButtonPressed(unsigned char)

void CalibrateLeft(void)

void CalibrateRight(void)

void CalibrateUp(void)

void CalibrateDown(void)

void CalibrateNeutral(void)

unsigned char MoveLeft(void)

unsigned char MoveRight(void)

unsigned char MoveUp(void)

unsigned char MoveDown(void)

void SetSensitivity(unsigned char)

##

## Methods of class Mouse

short int IsMouseAvailable(void)

short int NoOfMouseButtonsAvailable(void)

void SetSensitivity(short int, short int, short int)

void GetMousePositionAndButtons(short int&, short int&, short int&, short int&, short int&)

void GetMouseRelMotions(short int&, short int&)

## Brief description of the library classes.

##

## Class: Graphix

This class is the main class of the library. It will work against the user screen and support you with several primitives such as put pixel, draw bitmap, scrolling, page flipping and much more.

To be able to use this library, you must always instantiate one, and only one, object of this class and use it for all communication towards the user screen. When instantiating an object of this class, several internal tables will be created and to be able to initiate a new graphic screen resolution you must use the method: 'SetVideoMode()' (see section: Methods).

Note:

In all examples found in the 'Method' section, I assume that an object of this class has already been instantiated (i.e. Graphix myGfx).

## Class: Bitmap

Objects of this class will hold all your image data. You don't have to worry about memory allocation/de-allocation or how the data is stored (planar or linear) or when to de-reference pointers and other internal management stuff. Just associate the object to a file or another object, or to the screen through a 'Graphix' object. Many operations can be done on an object of this class through several methods. It also includes very fast collision detection methods including the possibility of setting the collision sensitivity of each individual object.

This class has a copy constructor and an assignment operator overload method that allows you to assign a 'Bitmap' object to another without inconsistency and shared pointers.

## Class: Palette

This class will handle different color tables used in your application. You have the opportunity of handling multiple palette tables in different palette objects and to manipulate its contents to a very high degree. You will be able to set the active palette, get color tables from files and system, make negative palettes, set/change RGB, rotate the colors and much more.

This class allows you to assign a 'Palette' object to another without inconsistency and shared pointers.

## Class: Keyboard

Here you have the opportunity of using a new fast keyboard device handler (interrupt chained) instead of the lousy 'getch()' function found in the 'conio' library. Of course, if you want to get external user input without requirements of fast response within a critical time limit (e.g. typing your name to a high-score list or user input to an adventure game), then you still can use your favorite methods/functions to handle the input. But in real-time action games, these old methods will not do! It doesn't matter how fast your methods/functions are, if you don't have a fast and a reliable input handler, the game will die because of the time delay caused by a slow device handler. This class prevents this!

## Class: Joystick

Here is another device handler. You will now, in a simple fashion, be able to incorporate the support of one, or two, joystick(s) into your application.

Just like the keyboard handler, all the low-level management is encapsulated in a class through a simple interface, just for making your life much easier.

You are able to detect the state of four buttons and nine possible positions from one joystick, or if you use an Y-cable you will be able to detect the state of two buttons of each joystick and nine positions from each joystick. And of course, you will be able to detect if there are any joysticks present in the joystick port.

Since PC uses the analog method (with potentiometers), you must calibrate the joystick(s) in at least five different positions (left-right-up-down-neutral). This class also provides you with these calibrating methods.

You are also able to set the detection sensitivity of the joystick's movements.

## Class: Mouse

This class will give you the basic primitives for handling a 2 or 3 button mouse in an easy and correct way through a very simple interface. The class can handle all mice as long as they work fine with the standard DOS mouse driver. Some of the methods available will give you the possibility of detecting a mouse, track the mouse's relative position and detect the state of the buttons (pressed/not pressed).

## Methods of class Graphix

short int SetVideoMode(char mode, unsigned short int viewport = 0)

Description:

Will set the wanted screen resolution with wanted view port size active. Class 'Graphix' supports 23 different graphic screen resolutions (these modes can be found defined in the file 'videodef.hh'). View port means that you are able to define a screen size greater than the visible screen. This can be used for scrolling and bitmap clipping. This version only provides a view port defined size in y-axis and with a maximum size of 32 extra lines at the top and bottom (a total of 64 lines) of the visible screen i.e. you are able to set view port between 0 and 32 lines.

You are able to change the resolution of the screen at any time in your application without affecting/destroying the functionality and data of the other classes contained in this library.

As default the view port size is set zero.

TEXT | 0
VGA256x224x256 | 1
VGA256x240x256 | 2
VGA256x256x256 | 3
VGA256x480x256 | 4
VGA320x200x256 | 5
VGA320x240x256 | 6
VGA320x400x256 | 7
VGA320x480x256 | 8
VGA360x200x256 | 9
VGA360x240x256 | 10
VGA360x270x256 | 11
VGA360x360x256 | 12
VGA360x400x256 | 13
VGA360x480x256 | 14
VGA376x282x256 | 15
VGA376x564x256 | 16
VGA400x300x256 | 17
VGA400x600x256 | 18
SVGA640x400x256 | 19
SVGA640x480x256 | 20
SVGA800x600x256 | 21
SVGA1024x768x256 | 22
SVGA1280x1024x256 | 23

Warnings:

Most of the methods in this class require you to set a video mode before using them.

Don't give a negative value as the parameter, or a value greater then 23, it won't work I promise you.

Make sure that your monitor also supports the wanted resolution even though your card does so, to avoid damages.

Every time you set a new video mode, you have to set your palette as the active palette again (if you use one of course), or else the default system's palette will be the active palette.

There is no error check for sending a value less than 0 or greater than 32 as view port parameter.

Parameters:

mode

is the wanted video mode. Range from 0 - 23.

viewport

is the size of the view port in y-axis. Range from 0 - 32.

Returns:

The numbers of available pages in video memory, to support page flipping. If a negative value is returned, your video card is not able to support the wanted resolution.

Example:

myGfx.SetVideoMode(VGA320x240x256); //Initiate ModeX (x-size = 320 pix. y-size = 240 pix. Using 256 colors) myGfx.SetVideoMode(TEXT); //Go back to normal text mode

unsigned short int GetScreenWidth(void)

Description:

This method returns the width (in number of pixels in x-axis) of the current graphic screen resolution.

Warnings:

None

Parameters:

None

Returns:

The number of pixels in x-axis if a graphic resolution is active, else value zero is returned (i.e. if text mode is active).

Example:

myGfx.SetVideoMode(VGA320x240x256); //Initiate ModeX (x-size = 320 pix. y-size = 240 pix. Using 256 colors) unsigned short int width = myGfx.GetScreenWidth(); //width will contain value 320

unsigned short int GetScreenHeight(void)

Description:

This method returns the height (in number of pixels in y-axis) of the current graphic screen resolution.

Warnings:

None

Parameters:

None

Returns:

The number of pixels in y-axis if a graphic resolution is active, else value zero is returned (i.e. if text mode is active).

Example:

myGfx.SetVideoMode(VGA320x240x256); //Initiate ModeX (x-size = 320 pix. y-size = 240 pix. Using 256 colors) unsigned short int height = myGfx.GetScreenHeight(); //height will contain value 240

void SetPalette(Palette& myPal)

Description:

This method will set the system palette to be the same as the palette sent as parameter.

Warnings:

None

Parameters:

myPal

is a reference to a valid palette object.

Returns:

Nothing

Example:

Palette myPal; //Instantiate a palette object. myGfx.SetPalette(myPal); //Set 'myPal' to the active system palette.

void GetPalette(Palette& myPal)

Description:

This method will store the current active palette in the object sent as parameter.

Warnings:

The sent parameter object will get its old data (palette information) destroyed using this method.

Parameters:

myPal

is a reference to a valid palette object.

Returns:

Nothing

Example:

Palette myPal; //Instantiate a palette object. myGfx.GetPalette(myPal); //Get and store the active palette into the palette object.

void PutPixel(short int x, short int y, unsigned char color)

Description:

Puts a single pixel in video memory. If the active screen is the visible screen, the pixel will be shown there.

Warnings:

No internal check is done to see if the pixel is in between the screen limits.

Parameters:

x

is the position in x-axis.

y

is the position in y-axis.

color

is the color of the pixel, range from 0 - 255.

Returns:

Nothing

Example:

myGfx.SetVideoMode(VGA320x240x256); //Initiate ModeX myGfx.PutPixel(0,0,5); //Put a pixel in the upper left corner with color value 5.

unsigned char GetPixel(short int x, short int y)

Description:

Get the color from a given screen position.

Warnings:

No internal check is done to see if the wanted position is in between the screen limits.

Parameters:

x

is the position in x-axis.

y

is the position in y-axis.

Returns:

The color (0 - 255) from the given screen position.

Example:

myGfx.SetVideoMode(VGA320x240x256); //Initiate ModeX unsigned char pixel = myGfx.GettPixel(0, 0); //Get the color of the pixel located in the upper left corner.

void SetDrawPage(unsigned int thePage)

Description:

If you are able to use multiple pages in the video memory, then you can use this method to draw on one screen in video memory and at the same time show another page on the visible screen (i.e. all your drawing operations will only affect the page chosen as the drawing page). Then you can change pages. This is called page flipping and is needed if you want to perform really smooth animation. Many games use is this strategy to avoid flickering and bad animation. Use the method '

SetVideMode()' to see how many pages that are available for your wanted resolution. If the numbers of available pages are 1 (meaning that there is just the visible screen available), then you have to use a double buffer (virtual page flipping) to perform page flipping.

If you set the draw page to equal the visible page, then you will see all your drawing results appear immediately on your monitor screen.

As default, the drawing page and the visible page are the same (page 0).

Warnings:

No internal check will be made for you giving a page number greater then the number of available pages.

Parameters:

thePage

is the number of the page that you want to be the current drawing page.

Returns:

Nothing

Example:

myGfx.SetVisiblePage(0); //Page 0 will be shown on your monitor screen myGfx.SetDrawPage(1); //Draw on next page in video memory myGfx.PutPixel(0,0,5); //Draw a pixel on page 2 getch(); //Get a key, note that the pixel can't be seen yet. myGfx.SetVisiblePage(1); //Flip pages. Now the pixel can be seen on the monitor screen.

void SetVisiblePage(unsigned int thePage)

Description:

Same as above but with the difference that your chosen page will be the one that is shown on the monitor screen.

Warnings:

Same as above

Parameter:

thePage

is the number of the page that you want to be the current visible page for the user.

Returns:

Nothing

Example:

myGfx.SetVisiblePage(0); //Page 0 will be shown on your monitor screen myGfx.SetDrawPage(1); //Draw on next page in video memory myGfx.PutPixel(0,0,5); //Draw a pixel on page 2 getch(); //Get a key, note that the pixel can't be seen yet. myGfx.SetVisiblePage(1); //Flip pages. Now the pixel can be seen on the monitor screen.

void V_Line(short int x, short int y, short int length, unsigned char color)

Description:

This method is used for drawing a vertical line.

The parameter

y is meant to be the top y position of the vertical line.

Warnings:

It's up to you to make sure that the line will fit inside the screen. No check for crossing the screen's border is done.

Parameters:

x

is the start position in x-axis for the line.

y

is the top start position in y-axis for the line.

length

is the length of your line.

color

is your wanted color (0 - 255).

Returns:

Nothing

Example:

myGfx.V_Line(0,0,100,5); //Draw a 100 pixel long vertical line starting at the upper left corner, with color 5.

void H_Line(short int x, short int y, short int length, unsigned char color)

Description:

Draw a horizontal line with specified length and color.

Warnings:

Same as for vertical line

Parameters:

x

is the left start position in x-axis for the line.

y

is the start position in y-axis for the line.

length

is the length of your line.

color

is your wanted color (0 - 255).

Returns:

Nothing

Example:

myGfx.H_Line(0,0,100,5); //Draw a 100 pixel long horizontal line starting at the upper left corner, with color 5.

void Box(short int x1, short int y1, short int x2, short int y2, unsigned char color)

Description:

Draw a box consisting of 4 attached lines with specified size and color.

Warnings:

It's up to you to make sure that the box will fit inside the screen. No check for crossing the screen's border is done.

Make sure that parameter

x1 and y1 are less then x2 and y2.

Parameters:

x1

is the upper left start position in x-axis.

y1

is the upper left start position in y-axis.

x2

is the lower right end position in x-axis.

y2

is the lower right end position in y-axis.

color

is your wanted color (0 - 255).

Returns:

Nothing

Example:

myGfx.Box(0,0,100,100,5); //Draw a square in the upper left corner with size of 100 and color value 5.

void FilledBox(short int x1, short int y1, short int x2, short int y2, unsigned char color)

Description:

Same as the above with the exception of the box being filled with the specified color.

Warnings:

Same as above

Parameters:

Same as above

Returns:

Nothing

Example:

myGfx.FilledBox(0,0,100,100,5); //Draw a filled square in the upper left corner with size of 100 and color value 5.

void Circle(short int x, short int y, short int r, unsigned char color)

Description:

Drawing a simple circle at specified position on screen and with specified radius and color.

Warnings:

It's up to you to make sure that the circle will fit inside the screen. No check for crossing the screen's border is done.

Parameters:

x

is the center position of the circle in x-axis.

y

is the center position of the circle in y-axis.

r

is the radius of the circle specified in numbers of pixels.

color

is your wanted color (0 - 255).

Returns:

Nothing

Example:

myGfx.Circle(50,50,50,5); //Draw a circle touching the screen borders in the upper left corner.

void FilledCircle(short int x, short int y, short int r, unsigned char color)

Description:

Drawing a simple filled circle at specified position on screen and with specified radius and color.

Warnings:

It's up to you to make sure that the circle will fit inside the screen. No check for crossing the screen's border is done.

Parameters:

x

is the center position of the circle in x-axis.

y

is the center position of the circle in y-axis.

r

is the radius of the circle specified in numbers of pixels.

color

is your wanted color used to fill the circle (0 - 255).

Returns:

Nothing

Example:

myGfx.FilledCircle(50,50,50,5); //Draw a fileld circle touching the screen borders in the upper left corner.

void Line(short int x1, short int y1, short int x2, short int y2, unsigned char color)

Description:

Draw a line with any slope.

Warnings:

It's up to you to make sure that the line will fit inside the screen. No check for crossing the screen's border is done.

Parameters:

x1

is the start position in x-axis.

y1

is the start position in y-axis.

x2

is the end position in x-axis.

y2

is the end position in y-axis.

color

is your wanted color (0 - 255).

Returns:

Nothing

Example:

//Draw a big x on the screen. myGfx.Line(0,0,50,50,5); myGfx.Line(0,50,50,0,5);

void ClearScreen(unsigned char color)

Description:

This method will fill the active screen (the active page) including the view port area with a specified color.

Warnings:

None

Parameters:

color

is your wanted color (0 - 255).

Returns:

Nothing

Example:

myGfx.ClearScreen(0); //Fill the drawing page with color 0.

void ClearVideoMemory(unsigned char color)

Description:

Same as '

ClearScreen()', but this method clear the whole video memory (all available pages). If the active page has the same size as the video memory, then this method is the same as the 'ClearScreen()' method.

Warnings:

None

Parameters:

color

is your wanted color (0 - 255).

Returns:

Nothing

Example:

myGfx.ClearVideoMemory(0); //Fill the whole video memory with color 0.

void WaitVerticalRetrace(void)

Description:

This method will halt the program's execution until the monitor's raster beam has reached the lower right corner of the screen to let the beam go back to the upper left corner again. This method is essential to use if you want to perform flicker-free animations.

Make sure to write your data to the visible screen (or flip page) directly after this method when the beam is retracing.

Warnings:

None

Parameters:

None

Returns:

Nothing

Example:

myGfx.WaitVerticalRetrace(); //Wait for raster beam retrace.

void ScrollY(short int direction)

Description:

This method will allow you to scroll the whole screen in y-axis. The view port on the visible screen goes max. 32 lines above and max. 32 lines below the actual screen resolution. This means that if you, for example, use the resolution of 320x200 pixels and a view port size of 32 lines, then the actual screen size will be 320x264, but the visible screen will be 320x200. This also means that you will be able to perform clipping in y-axis as long as the sprite is not larger than 32 lines in y-axis. Since there are 32 lines outside the visible screen, you can now smooth scroll the whole screen one or more lines (using the '

SetScrollingSpeed()' method) at each scroll frame. When the 32 lines view port buffer is reached, the visible screen will be set to zero again (the library will assure you to never get out of bounds when scrolling in y-axis). This method is specialized for tiled based games.

The parameter

direction will tell the method if you want to scroll the screen up or down.

Warnings:

When you scroll one page, the other pages will also be scrolled with the same amount of lines i.e. when you flip a page the other page(s) will also have the same screen position in y-axis.

Parameters:

direction

tells the method in which direction to scroll the screen (0 = up, 1 = down).

Returns:

Nothing

Example:

char key = getch(); while(key != 'q') //Quit the program if we press the 'q' key. { if(key == 'a') myGfx.ScrollY(0); //Scroll the whole screen upwards 1 line. else if(key == 'z') myGfx.ScrollY(1); //Scroll the whole screen downwards 1 line. key = getch(); //Get user input again! }

void SetScrollingSpeed(unsigned short int ySpeed)

Description:

Here you can set how many lines in y-axis that will be scrolled in each frame. Default value is one line at each scroll. The maximum lines per scrolling frame are 32. Notice that this value is valid for both directions i.e. the scrolling speed is the same for both up and down.

Warnings:

If parameter

ySpeed is greater than the size of the view port (max. 32), or less than zero the scrolling value is set to zero.

Parameters:

ySpeed

is the actual scrolling speed in y-axis (number of lines to scroll), range between 0 - 32.

Returns:

Nothing

Example:

char key = 0; unsigned short int val = 1; while(1) //Quit the program if we press the 'q' key. { if(key == '+') myGfx.SetScrollingSpeed(++val); //Increase current scroll value by 1. else if(key == '-') myGfx.SetScrollingSpeed(--val); //Increase current scroll value by 1. else if(key == 'q') break; //Quit myGfx.ScrollY(1); //Scroll the whole screen downwards key = getch(); //Get user input again! }

void ClearScrollingY(void)

Description:

Call this method if you for some reason want to restore the screen during a scrolling session without having reached the last line in the view port. For example if you have scrolled the screen 5 lines and the view port is 10 lines in height and you want to set the scrolling position to zero again (center the screen).

Warnings:

None

Parameters:

None

Returns:

Nothing

Example:

myGfx.ClearScrollingY(); //Center the screen in y-axis

char LoadRAW(char* filename, Bitmap& myBitmap, Palette& myPal, unsigned int xSize, unsigned int ySize, short int palStart, unsigned char transparent, unsigned char transpColor)

Description:

This method will let you load a RAW picture (binary data without any compression) into a Bitmap object. You can choose to use the picture (bitmap) as a solid picture or a transparent (sprite) one. Using the parameter

palStart you can tell the method to find the color table (768 bytes large) in the beginning or in the end of the RAW file. You can even skip the color table and just load the binary data into the bitmap object.

Warnings:

Any earlier stored data in the 'Bitmap' and 'Palette' objects will be destroyed after the execution of this method.

If you choose not to load the color table into the 'Palette' object, then make sure that there is no color table stored in the file, just the ordinary binary data.

Parameters:

filename

is the name of your RAW-file.

myBitmap

is a reference to your 'Bitmap' object in which you want the picture to be stored.

myPal

is a reference to your 'Palette' object in which the palette of the picture will be stored if you specify so, else the object won't be used.

xSize

is the width of the picture.

ySize

is the height of the picture.

palStart

tells the method where to find the color table. 0 = there is no color table, 1 = color table can be found in the beginning of the file, 2 = color table is in the end of the file.

transparent

is a flag to indicate if you want the picture to be stored as transparent or solid. The value can be TRUE (1) or FALSE (0).

transpColor

will let you choose the color value to be the transparent color if want the bitmap to be transparent (if not, you can specify any value you want to).

Returns:

1 if everything went fine.

-1 if the file can't be found.

-2 if the required memory can't be allocated.

-3 if you have given an invalid color table start (a value less than 0 or greater than 2).

-4 if you have chosen the bitmap to be transparent and the required memory for it can't be allocated.

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load the RAW-file 'picture.raw' with size 320x200 and store the data in the bitmap object and the picture's palette (is stored in the end of the RAW file) in the palette object. Make it solid and just put a dummy value to be the transparent color. myGfx.LoadRAW("picture.raw", myPicture, myPal, 320, 200, 2, 0, 0); myGfx.DrawBitmap(0, 0, myPicture); //Draw the bitmap on the screen!

char LoadRAWTile(char* filename, Bitmap myBitmaps[], Palette& myPal, unsigned int picXSize, unsigned int picYSize, unsigned int tileXSize, unsigned int tileYSize, short int palStart, short int nrOfTiles, unsigned char transparent, unsigned char transpColor)

Description:

This method will let you load a RAW tiled picture (binary data without any compression) into a vector of 'Bitmap' objects (each 'Bitmap' object will contain a tile extracted from the RAW file). A tile is simply a rectangular bitmap with a predefined size. In many games tiles are used for assembling the particular game screen. For instance one tile may look like a crossroad while other tiles looks like curved or straight roads, and when putting them together you will have a complex road network to be dynamically changed when needed without any large memory requirements. An example: a picture contained in a file may have the size of 640 * 400 pixels and this file consists of 100 different tiles with the same size i.e. 64 * 40 pixels.

Except for the tiles functionality, this method works just the same as the method '

LoadRAW()'.

Warnings:

Any earlier stored data in the objects (including the 'Palette' object) will be destroyed after the execution of this method.

If you choose not to load the color table into the 'Palette' object, then make sure that there is no color table stored in the file, just the ordinary binary data.

Make sure that the parameter

nrOfTiles equals the number of allocated 'Bitmap' objects in the vector and equals the number of available tiles in the RAW file.

The size of all tiles must be the same e.g. 64 * 40.

Parameters:

filename

is the name of your RAW-file.

myBitmaps

is a reference to your vector of 'Bitmap' objects in which you want all tiles to be stored.

myPal

is a reference to your 'Palette' object in which the palette of the picture will be stored if you specify so, else the object won't be used.

picXSize

is the width (in number of pixels) of the picture.

picYSize

is the height (in number of pixels) of the picture.

tileXSize

is the width (in number of pixels) of all tiles contained in the picture.

tileYSize

is the height (in number of pixels) of all tiles contained in the picture.

palStart

tells the method where to find the color table. 0 = there is no color table, 1 = color table can be found in the beginning of the file, 2 = color table is in the end of the file.

nrOfTiles

is the number of tiles contained in the picture.

transparent

is a flag to indicate if you want the picture to be stored as transparent or solid. The value can be TRUE (1) or FALSE (0).

transpColor

will let you choose the color value to be the transparent color if want the bitmap to be transparent (if not, you can specify any value you want to).

Returns:

1 if everything went fine.

-1 if the file can't be found.

-2 if the required memory can't be allocated.

-3 if you have given an invalid color table start (a value less than 0 or greater than 2).

-4 if you have chosen the bitmap to be transparent and the required memory for it can't be allocated.

-5 if the total size of all wanted tiles exceeds the real size of the picture.

Example:

Bitmap *myTiles; //Create a 'Bitmap' pointer. myTiles = new Bitmap[100]; //Allocate 100 'Bitmap' objects on the heap. Palette myPal; //Create a stateless palette object. //Load 100 tiles contained in the RAW-file 'picture.raw' and store all tiles in the 'Bitmap' vector and store the picture's palette in the palette object. The picture's width is 320 and its height is 240 pixels and the color table is stored in the beginning of the file. We don't want it to be transparent. The size of each tile will be 32 * 24 and therefore the total number of tiles will be 100 (since the total width is 320 and the total height is 240). myGfx.LoadRAWTile("picture.raw", myTiles, myPal, 320, 240, 32, 24, 0, 100, 0, 0); myGfx.SetPalette(myPal); //Set active palette. for(int I = 0; I < 10; I++) //Draw 10 tiles myGfx.DrawBitmap(I * 32, 0, myTiles[I]); //32 is the width of each tile.

char SaveRAW(char* filename, Bitmap& myBitmap, Palette& myPal, short int palStart)

Description:

Save a bitmap object as a RAW-file (binary data without any compression). This will be done whether the bitmap is transparent or not (i.e. it will be saved as a solid picture).

Warnings:

This method will over-write any file with the same file name as the specified one.

Parameters:

filename

will be the name of your saved PCX-file.

myBitmap

is a reference to the bitmap you want to save.

myPal

is a reference to the palette you want to be used with the PCX picture.

palStart

tells the method where to save the color table. 0 = don't save the color table, 1 = color table must be saved in the beginning of the file, 2 = color table must be saved in the end of the file.

Returns:

1 if everything went fine.

-1 if the something went wrong (e.g. read-only disc, or something else).

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load the RAW-file 'picture.raw' (800 * 600 pixels) and store the data in the bitmap object and the picture's palette in the palette object. Make it solid and just put a dummy value to be the transparent color. The color table will be found in the end of the RAW file (i.e. value 2). myGfx.LoadRAW("picture.raw", myPicture, myPal, 800, 600, 2, 0, 0); //Now, perform a stupid file copy myGfx.SaveRAW("picture2.raw", myPicture, myPal, 2);

char LoadPCX(char* filename, Bitmap& myBitmap, Palette& myPal, unsigned char transparent, unsigned char transpColor)

Description:

This method will let you load a PCX picture (ZSoft) into a Bitmap object. You can choose to use the picture (bitmap) as a solid picture or a transparent (sprite) one

Warnings:

Any earlier stored data in the 'Bitmap' and 'Palette' objects will be destroyed after the execution of this method.

Parameters:

filename

is the name of your PCX-file.

myBitmap

is a reference to your 'Bitmap' object in which you want the picture to be stored.

myPal

is a reference to your 'Palette' object in which the palette of the picture will be stored.

transparent

is a flag to indicate if you want the picture to be stored as transparent or solid. The value can be TRUE (1) or FALSE (0).

transpColor

will let you choose the color value to be the transparent color if want the bitmap to be transparent (if not, you can specify any value you want to).

Returns:

1 if everything went fine.

-1 if the file can't be found.

-2 if the required memory can't be allocated.

-3 if any other error occurred.

-4 if you have chosen the bitmap to be transparent and the required memory for it can't be allocated.

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load the PCX-file 'picture.pcx' and store the data in the bitmap object and the picture's palette in the palette object. Make it solid and just put a dummy value to be the transparent color. myGfx.LoadPCX("picture.pcx", myPicture, myPal, 0, 0); myGfx.DrawBitmap(0, 0, myPicture); //Draw the bitmap on the screen!

char LoadPCXTile(char* filename, Bitmap myBitmaps[], Palette& myPal, unsigned int tileXSize, unsigned int tileYSize, short int nrOfTiles, unsigned char transparent, unsigned char transpColor)

Description:

This method will let you load a PCX (Zsoft) tiled picture into a vector of 'Bitmap' objects (each 'Bitmap' object will contain a tile extracted from the PCX file). A tile is simply a rectangular bitmap with a predefined size. In many games tiles are used for assembling the particular game screen. For instance one tile may look like a crossroad while other tiles looks like curved or straight roads, and when putting them together you will have a complex road network to be dynamically changed when needed without any large memory requirements. An example: a picture contained in a file may have the size of 640 * 400 pixels and this file consists of 100 different tiles with the same size i.e. 64 * 40 pixels.

Except for the tiles functionality, this method works just the same as the method '

LoadPCX()'.

Warnings:

Any earlier stored data in the objects (including the 'Palette' object) will be destroyed after the execution of this method.

Make sure that the parameter

nrOfTiles equals the number of allocated 'Bitmap' objects in the vector and equals the number of available tiles in the PCX file.

The size of all tiles must be the same e.g. 64 * 40.

Parameters:

filename

is the name of your PCX-file.

myBitmaps

is a reference to your vector of 'Bitmap' objects in which you want all tiles to be stored.

myPal

is a reference to your 'Palette' object in which the palette of the picture will be stored if you specify so, else the object won't be used.

tileXSize

is the width (in number of pixels) of all tiles contained in the picture.

tileYSize

is the height (in number of pixels) of all tiles contained in the picture.

nrOfTiles

is the number of tiles contained in the picture.

transparent

is a flag to indicate if you want the picture to be stored as transparent or solid. The value can be TRUE (1) or FALSE (0).

transpColor

will let you choose the color value to be the transparent color if want the bitmap to be transparent (if not, you can specify any value you want to).

Returns:

1 if everything went fine.

-1 if the file can't be found.

-2 if the required memory can't be allocated.

-3 if you have given an invalid color table start (a value less than 0 or greater than 2).

-4 if you have chosen the bitmap to be transparent and the required memory for it can't be allocated.

-5 if the total size of all wanted tiles exceeds the real size of the picture.

Example:

Bitmap *myTiles; //Create a 'Bitmap' pointer. myTiles = new Bitmap[100]; //Allocate 100 'Bitmap' objects on the heap. Palette myPal; //Create a stateless palette object. //Load 100 tiles contained in the PCX-file 'picture.pcx' and store all tiles in the 'Bitmap' vector and store the picture's palette in the palette object. The picture's width is 320 and its height is 240 pixels and the color table is stored in the beginning of the file. We don't want it to be transparent. The size of each tile will be 32 * 24 and therefore the total number of tiles will be 100 (since the total width is 320 and the total height is 240). myGfx.LoadPCXTile("picture.pcx", myTiles, myPal, 32, 24, 100, 0, 0); myGfx.SetPalette(myPal); //Set active palette. for(int I = 0; I < 10; I++) //Draw 10 tiles myGfx.DrawBitmap(I * 32, 0, myTiles[I]); //32 is the width of each tile.

char SavePCX(char* filename, Bitmap& myBitmap, Palette& myPal)

Description:

Save a bitmap object as a PCX-file. This will be done whether the bitmap is transparent or not (i.e. it will be saved as a solid picture).

Warnings:

This method will over-write any file with the same file name as the specified one.

Parameters:

filename

will be the name of your saved PCX-file.

myBitmap

is a reference to the bitmap you want to save.

myPal

is a reference to the palette you want to be used with the PCX picture.

Returns:

1 if everything went fine.

-1 if the something went wrong (e.g. read-only disc, or something else).

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load the PCX-file 'picture.pcx' and store the data in the bitmap object and the picture's palette in the palette object. Make it solid and just put a dummy value to be the transparent color. myGfx.LoadPCX("picture.pcx", myPicture, myPal, 0, 0); //Now, perform a stupid file copy myGfx.SavePCX("picture2.pcx", myPicture, myPal);

void DrawBitmap(short int x, short int y, Bitmap& myBitmap)

Description:

Here you can draw your bitmap object on the active page (i.e. the page set by the method '

SetDrawPage()'). This method will automatically determine which method to be the fastest way to draw your bitmap with. A hint is to use aligned sized bitmaps to achieve highest possible speed.

Warnings:

Be sure that your bitmap is not larger then the size of the page. Also make sure that your picture will fit into the page and thereby not cross its borders.

Parameters:

x

is the position (in x-axis) on the screen (page) where the upper left corner of your bitmap will be put.

y

is the position (in y-axis) on the screen (page) where the upper left corner of your bitmap will be put.

myBitmap

is a reference to the bitmap you want to draw.

Returns:

Nothing

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load a PCX-file. myGfx.LoadPCX("picture.pcx", myPicture, myPal, 1, 0); //Set the picture's palette to be the active one. myGfx.SetPalette(myPal); myGfx.DrawBitmap(0, 0, myPicture); //Draw it!

void GetRAMBitmap(short int x, short int y,short int width, short int height, Bitmap& mySrc, Bitmap& myDst)

Description:

This method will give you the possibility to extract a portion from a 'Bitmap' source object to a destination object. This means that you can get a subset image from a larger image. This is great when you have to for instance save the background image before you put another image at the same position.

Warnings:

Destination 'Bitmap' object must be equal to, or smaller than the source object. No check for this will be done.

Any earlier stored data in the destination object will be destroyed after the execution of this method.

Parameters:

x

is the start position in x-axis in source bitmap from where the image will be extracted.

y

is the start position in y-axis in source bitmap from where the image will be extracted.

width

is the width in number of pixels in x-axis.

height

is the height in number of pixels in y-axis.

mySrc

is a reference to the 'Bitmap' object from which you want to copy a portion from.

myDst

is a reference to the 'Bitmap' object in which you want to store the extracted portion.

Returns:

Nothing

Example:

Bitmap mySrcBmp; Bitmap myDstBmp; Palette myPal; //Create a stateless palette object. //Load a PCX-file. Assume the image size is 320x200 pixels myGfx.LoadPCX("picture.pcx", mySrcBmp, myPal, 1, 0); myGfx.GetScreenBitmap(0, 0, 320, 100, mySrcBmp, myDstBMp); //Now 'myDstBmp' has copied half the source bitmap's image.

short int ConvertSolidToTransparentBitmap(Bitmap& myBitmap, unsigned char transpColor)

Description:

This will convert a solid rectangular shaped bitmap into a transparent (sprite) bitmap i.e. the background behind the transparent bitmap will be visible for all pixels stored in the bitmap with the color

transpColor sent as parameter.

Warnings:

Don't convert an empty 'Bitmap' object (i.e. with no data in it).

Parameters:

myBitmap

is a reference to the bitmap you want to convert.

transpColor

is the color value for all pixels in your bitmap object that will be transparent.

Returns:

1 if everything is went fine.

-1 if you have not chosen a valid graphic video mode e.g. text mode.

-2 if the bitmap is already transparent.

-3 if needed memory couldn't be allocated.

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load a PCX-file and store it as a solid bitmap object. myGfx.LoadPCX("picture.pcx", myPicture, myPal, 0, 0); //Convert the solid bitmap into a transparent bitmap by making all //pixels with color 5 transparent. myGfx.ConvertSolidToTransparentBitmap(myPicture, 5);

void ConvertTransparentToSolidBitmap(Bitmap& myBitmap)

Description:

This will convert a transparent (sprite) bitmap into a solid bitmap.

Warnings:

Don't convert an empty 'Bitmap' object (with no data in it).

Parameters:

myBitmap

is a reference to the bitmap you want to convert.

Returns:

Nothing

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load a PCX-file and store it as a transparent bitmap object. myGfx.LoadPCX("picture.pcx", myPicture, myPal, 1, 0); //Convert the transparent bitmap into a solid bitmap. myGfx.ConvertTransparentToSolidBitmap(myPicture);

void FlipBitmapVertical(Bitmap& myBitmap)

Description:

This will flip (reverse) your bitmap image in the vertical axis (x-axis).

Warnings:

Don't try to flip an empty object (with no data in it).

Parameters:

myBitmap

is a reference to the bitmap you want to reverse.

Returns:

Nothing

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load a PCX-file. myGfx.LoadPCX("picture.pcx", myPicture, myPal, 1, 0); myGfx.FlipBitmapVertical(myPicture); //Flip it!

void FlipBitmapHorizontal(Bitmap& myBitmap)

Description:

This will flip (reverse) your bitmap image in the horizontal axis (y-axis).

Warnings:

Don't try to flip an empty object (with no data in it).

Parameters:

myBitmap

is a reference to the bitmap you want to reverse.

Returns:

Nothing

Example:

Bitmap myPicture; //Create a stateless object. Palette myPal; //Create a stateless palette object. //Load a PCX-file. myGfx.LoadPCX("picture.pcx", myPicture, myPal, 1, 0); myGfx.FlipBitmapHorizontal(myPicture); //Flip it!

void GetScreenBitmap(short int x1, short int y1, short int x2, short int y2, Bitmap& myBitmap)

Description:

Same as the method '

GetRAMBitmap()', but here you will extract an image portion from the active page (set by method 'SetDrawPage()') in video memory instead of RAM memory. This method is MUCH slower than the 'GetRAMBitmap()' method because of the needed communication with the video card.

Warnings:

The usual: make sure that your screen positions will fit inside the page. Do not cross the page's borders.

Parameters:

x1

is the upper left (in x-axis) corner in the screen from where to get the bitmap from.

y1

is the upper left (in y-axis) corner in the screen from where to get the bitmap from.

x2

is the lower right (in x-axis) corner in the screen from where to get the bitmap from.

y2

is the lower right (in y-axis) corner in the screen from where to get the bitmap from.

myBitmap

is a reference to the 'Bitmap' object in which you want to store the extracted portion.

Returns:

Nothing

Example:

Bitmap myDst; //Let us assume that we use the screen resolution of 320*240 pixels and wants to copy the whole screen: myGfx.GetScreenBitmap(0, 0, 320, 240, myDst); //Now 'myDst' contain the 'screen dump' image.

short int ScaleBitmap(Bitmap& srcBmp, Bitmap& dstBmp, short int newXSize, short int newYSize)

Description:

This method will allow you to scale (zoom) a 'Bitmap' object, both solid and transparent bitmaps, in both x- and y-axis. You are able to scale the bitmap into a size less than, or greater than the original size. The parameter

dstBmp is used for storing the result from the scaling operation since you probably do not want to destroy the original bitmap sent as parameter srcBmp. Note, this scaling method do not use anti-aliasing.

Warnings:

Don't scale the bitmap to a size of zero. Don't scale the bitmap larger than the size of the screen, inclusive the current size of your view port, since it will not fit inside the screen when you try to draw it.

Parameters:

srcBmp

is a reference to the 'Bitmap' object that you want to scale.

dstBmp

is a reference to the 'Bitmap' object where you want the scaled result to be stored.

newXSize

is the number of pixels in x-axis (width) your destination 'Bitmap' object will be scaled into.

newYSize

is the number of pixels in y-axis (height) your destination 'Bitmap' object will be scaled into.

Returns:

1 if status OK.

-1 if the 'Bitmap object' is empty (there is no picture attached to the object).

-2 if internal memory allocation failed.

Example:

Bitmap mySrc, myDst; //Create two empty 'Bitmap' objects Palette myPal; //Create a stateless palette object. //Load a PCX-file into the 'Bitmap' object 'mySrc' and make it transparent. //Let's assume that the size of the picture 'picture.pcx' has a size of 30x20 myGfx.LoadPCX("picture.pcx", mySrc, myPal, 1, 0); myGfx.ScaleBitmap(mySrc, myDst, 60, 40); //Make the bitmap twice as big. myGfx.DrawBitmap(0, 0, myDst); //Draw the new scaled transparent bitmap.

short int ScaleBitmapX(Bitmap& srcBmp, Bitmap& dstBmp, short int newXSize)

Description:

Same as the method '

ScaleBitmap()', but this method will allow you to scale (zoom) a 'Bitmap' object, both solid and transparent bitmaps, in x-axis (width) only. You are able to scale the width of the bitmap into a size less than, or greater than its original width. The parameter dstBmp is used for storing the result from the scaling operation since you probably do not want to destroy the original bitmap sent as parameter srcBmp. Note, this scaling method do not use anti-aliasing.

Warnings:

Don't scale the width of the bitmap to a size of zero. Don't scale the bitmap larger than the width of the screen since it will not fit inside when you try to draw it.

Parameters:

srcBmp

is a reference to the 'Bitmap' object that you want to scale.

dstBmp

is a reference to the 'Bitmap' object where you want the scaled result to be stored.

newXSize

is the number of pixels in x-axis (width) your destination 'Bitmap' object will be scaled into.

Returns:

1 if status OK.

-1 if the 'Bitmap object' is empty (there is no picture attached to the object).

-2 if internal memory allocation failed.

Example:

Bitmap mySrc, myDst; //Create two empty 'Bitmap' objects Palette myPal; //Create a stateless palette object. //Load a PCX-file into the 'Bitmap' object 'mySrc' and make it transparent. //Let us assume that the picture 'picture.pcx' has a size of 30x20 pixels. myGfx.LoadPCX("picture.pcx", mySrc, myPal, 1, 0); myGfx.ScaleBitmapX(mySrc, myDst, 60); //Make it twice as big in x-axis. myGfx.DrawBitmap(0, 0, myDst); //Draw the new scaled transparent bitmap.

short int ScaleBitmapY(Bitmap& srcBmp, Bitmap& dstBmp, short int newYSize)

Description:

Same as the method '

ScaleBitmap()', but this method will allow you to scale (zoom) a 'Bitmap' object, both solid and transparent bitmaps, in y-axis (height) only. You are able to scale the height of the bitmap into a size less than, or greater than its original height. The parameter dstBmp is used for storing the result from the scaling operation since you probably do not want to destroy the original bitmap sent as parameter srcBmp. Note, this scaling method do not use anti-aliasing.

Warnings:

Don't scale the height of the bitmap to a size of zero. Don't scale the bitmap larger than the height of the screen, inclusive the current size of your view port, since it will not fit inside when you try to draw it.

Parameters:

srcBmp

is a reference to the 'Bitmap' object that you want to scale.

dstBmp

is a reference to the 'Bitmap' object where you want the scaled result to be stored.

newYSize

is the number of pixels in y-axis (height) your destination 'Bitmap' object will be scaled into.

Returns:

1 if status OK.

-1 if the 'Bitmap object' is empty (there is no picture attached to the object).

-2 if internal memory allocation failed.

Example:

Bitmap mySrc, myDst; //Create two empty 'Bitmap' objects Palette myPal; //Create a stateless palette object. //Load a PCX-file into the 'Bitmap' object 'mySrc' and make it transparent. //Let us assume that the picture 'picture.pcx' has a size of 30x20 pixels. myGfx.LoadPCX("picture.pcx", mySrc, myPal, 1, 0); myGfx.ScaleBitmapX(mySrc, myDst, 40); //Make it twice as big in y-axis. myGfx.DrawBitmap(0, 0, myDst); //Draw the new scaled transparent bitmap.

void Print(short int x, short int y, char text[])

Description:

This method will give you the opportunity of printing text strings on the screen. The length of the text string sent as parameter

text can be of any size (number of characters). This method uses the system default font (8x8 pixels) stored in ROM. The default color of the font will be the brightest color found in the current color table. You can also set/get the color of the font with the methods 'SetFontColor()' and 'GetFontColor()', but the font can only consist of one color at each time. You can unfortunately not resize this font. The next version of this library will include the support of 'True Type Font' were you will be able to resize your all your different fonts.

Warnings:

Make sure that your text string will fit inside your screen's borders. This method can only detect and print plain ASCII characters i.e. it can not interpret special character codes such as '\n' for new line and so on.

Parameters:

x

is the start position on the screen in x-axis where you want your string to be placed.

y

is the start position on the screen in y-axis where you want your string to be placed (from the upper left corner of the first character in the string).

text

is the string to be printed on the screen (can consist of zero and more characters).

Returns:

Nothing

Example:

//Print the world's most famous string at the upper left corner on the screen myGfx.Print(0, 0, "Hello world!"); //Length of this string is 12 * 8 pixels.

short int SetFontColor(unsigned char color)

Description:

Here you can change the color of the system font.

Warnings:

Don't try to color cycle (changing the color of the font) your text in run-time e.g. scrolling text with cycling color, using this method since all characters are stored as transparent bitmaps they all have to be regenerated, which is a slow process. But of course, if you want to change the color of the text in a non-critical time state, this method will do fine.

Parameters:

color

is the new color value of your font

Returns:

1 if everything went fine.

-1 if internal memory allocation failed.

Example:

if(myGfx.SetFontColor(33) != 1) //Set font color value to 33. myGfx.Print(0, 0, "Couldn't change the color"); else myGfx.Print(0, 0, "This string has color value 33");

unsigned char GetFontColor(void)

Description:

This method will simply return the current color value (0 - 255) of the system font.

Warnings:

None

Parameters:

None

Returns:

The current color value of the system font (range between 0 - 255).

Example:

unsigned char value = myGfx.GetFontColor(); //Variable 'value' now contain the font's color value

## Methods of class Bitmap

unsigned short int GetWidth(void)

Description:

This method will give you the width (x-size) of the image contained in the object.

Warnings:

None

Parameters:

None

Returns:

The width of the bitmap in number of pixels

Example:

Bitmap myBmp; int xSize = myBmp.GetWidth(); //Here 'xSize' will, of course, be zero.

unsigned short int GetHeight(void)

Description:

This method will give you the height (y-size) of the image contained in the object.

Warnings:

None

Parameters:

None

Returns:

The height of the bitmap in number of pixels

Example:

Bitmap myBmp; int ySize = myBmp.GetHeight(); //Here 'ySize' will, of course, be zero.

unsigned short int GetXposition(void)

Description:

Each 'Bitmap' object contains two internal variables that can be used for different purposes, but mainly for holding the bitmaps current position on the screen. This method returns the value contained in one of the variables, the one mainly used for setting the current position in x-axis. Note: you must set the variable to a specific value yourself by using the method '

SetXposition()', or else value zero will always be returned.

Warnings:

You must set the variable to a specific value yourself by using the method '

SetXposition()', or else value zero will always be returned.

Parameters:

None

Returns:

The value contained in the temporary internal variable (zero if nothing else stated).

Example:

Bitmap myBmp; unsigned short int xScreenPos = myBmp.GetXposition(); //Here 'xScreenPos' will, of course, be zero. myBmp.SetXposition(100); xScreenPos = myBmp.GetXposition(); //xScreenPos now contain value 100.

unsigned short int GetYposition(void)

Description:

Each 'Bitmap' object contains two internal variables that can be used for different purposes, but mainly for holding the bitmaps current position on the screen. This method returns the value contained in one of the variables, the one mainly used for setting the current position in y-axis. Note: you must set the variable to a specific value yourself by using the method '

SetYposition()', or else value zero will always be returned.

Warnings:

You must set the variable to a specific value yourself by using the method '

SetYposition()', or else value zero will always be returned.

Parameters:

None

Returns:

The value contained in the temporary internal variable (zero if nothing else stated).

Example:

Bitmap myBmp; unsigned short int yScreenPos = myBmp.GetYposition(); //Here 'yScreenPos' will, of course, be zero. myBmp.SetYposition(100); yScreenPos = myBmp.GetYposition(); //yScreenPos now contain value 100.

void SetXposition(unsigned short int xPosition)

Description:

Each 'Bitmap' object contains two internal variables that can be used for different purposes, but mainly for holding the bitmaps current position on the screen. This method will let you set one of the temporary internal variables, the one mainly used for holding the current position in x-axis.

Warnings:

None

Parameters:

xPosition

is the position in x-axis on screen in which the bitmap is located (origin of the bitmap is at the upper left corner of the bitmap).

Returns:

Nothing

Example:

Bitmap myBmp; unsigned short int xScreenPos = myBmp.GetXposition(); //Here 'xScreenPos' will, of course, be zero. myBmp.SetXposition(100); xScreenPos = myBmp.GetXposition(); //xScreenPos now contain value 100.

void SetYposition(unsigned short int yPosition)

Description:

Each 'Bitmap' object contains two internal variables that can be used for different purposes, but mainly for holding the bitmaps current position on the screen. This method will let you set one of the temporary internal variables, the one mainly used for holding the current position in y-axis.

Warnings:

None

Parameters:

yPosition

is the position in y-axis on screen in which the bitmap is located (origin of the bitmap is at the upper left corner of the bitmap).

Returns:

Nothing

Example:

Bitmap myBmp; unsigned short int yScreenPos = myBmp.GetYposition(); //Here 'yScreenPos' will, of course, be zero. myBmp.SetYposition(100); yScreenPos = myBmp.GetYposition(); //yScreenPos now contain value 100.

void SetCollisionSensitivity(short int theValue)

Description:

Here you can set the collision sensitivity on the individual bitmap object. This is needed since an object (perhaps a sprite) has a specific size but the sprite itself does not cover all area i.e. it is not shaped as a square. This will produce detection errors such as signaling for a collision between two transparent bitmaps when their transparent borders overlap each other but not their non-transparent pixels. The parameter

theValue must contain a percentage value (range between 0 - 100) to set the total sensitivity of the object. A value of 100 will set maximum sensitivity and detect a collision as soon as one border of the bitmap collides with the border of another bitmap. A value of 50 will let another bitmap cross one border half way through the bitmap before a collision is detected and signaled (using the methods 'DetectBitmapCollision()' and 'DetectAreaCollision()') upon. When you lower the degree of the object's sensitivity, try to see it as a shrinking box inside the bitmap, which will act as the reacting collision borders.

The default value is 100 on each created 'Bitmap' object.

Warnings:

If the parameter

theValue is less than zero it will be set to zero. If the value is greater than 100 it will be set to 100.

Parameters:

theValue

is the percentage value of the object's total collision sensitivity.

Returns:

Nothing

Example:

Bitmap myBmp; Palette myPal; myGfx.LoadPCX("picture.pcx", myBmp, myPal, 1, 0); //Load a PCX-picture myBmp.SetCollisionSensitivity(70); //70 is a common value for game objects

short int DetectBitmapCollision(short int x1, short int y1, Bitmap& theObject, short int x2, short int y2)

Description:

This method will let you know if your 'Bitmap' object has collided with another 'Bitmap' object (the object sent as parameter

theObject). Both objects can be of any size and you don't have to know in advance, the actual sizes of the bitmaps since this method automatically handles all that.

Warnings:

Don't send a negative value as a parameter since this can produce very strange effects.

Remember that the correctness of the collision is dependent on both the 'Bitmap' objects internal sensitivity states (can be changed with the method '

SetCollisionSensitivity' on each object).

Parameters:

x1

is the position, in x-axis, on the screen were the upper left corner of your bitmap is located.

y1

is the position, in y-axis, on the screen were the upper left corner of your bitmap is located.

theObject

is a reference to the target object to be examined for collision with the object were this method was called from.

x2

is the position, in x-axis, on the screen were the upper left corner of the target bitmap is located.

y2

is the position, in x-axis, on the screen were the upper left corner of the target bitmap is located.

Returns:

1 if a collision has occurred.

0 if no collision has occurred.

Example:

Bitmap myBmp; //Player object Bitmap anotherBmp; Palette myPal; //The ordinary palette object //Assume that the picture 'picture.pcx' has a size of 80 * 70 pixels. myGfx.LoadPCX("picture.pcx", myBmp, myPal, 1, 0); //Load a PCX-picture anotherBmp = myBmp; //Assign it. if(myBmp.DetectBitmapCollision(0, 0, anotherBmp, 0, 0)) myGfx.Print(0, 0, "A collision occurred!"); //Print out the fact!

short int DetectAreaCollision(short int x1, short int y1, short int width, short int height, short int x2, short int y2)

Description:

Same as the above method '

DetectBitmapCollision()' but this method will let you know if your 'Bitmap' object has collided with a background area whose size is sent as parameters width and height, and the start position x2 and y2.

Warnings:

Don't send a negative value as a parameter since this can produce very strange effects.

Remember that the correctness of the collision is dependent on the 'Bitmap' object's internal sensitivity state (can be changed with the method '

SetCollisionSensitivity()').

Parameters:

x1

is the position, in x-axis, on the screen were the upper left corner of your bitmap is located.

y1

is the position, in y-axis, on the screen were the upper left corner of your bitmap is located.

width

is the width of the background area to be examined for collision with the object were this method was called from.

height

is the height of the background area to be examined for collision with the object were this method was called from.

x2

is the start position, in x-axis, on the screen were the upper left corner of the background area is located.

y2

is the start position, in x-axis, on the screen were the upper left corner of the background area is located.

Returns:

1 if a collision has occurred.

0 if no collision has occurred.

Example:

Bitmap myBmp; //Player object Palette myPal; //The ordinary palette object //Assume that the picture 'picture.pcx' has a size of 80 * 70 pixels. myGfx.LoadPCX("picture.pcx", myBmp, myPal, 1, 0); //Load a PCX-picture //This 'if' statement will of course always return true. if(myBmp.DetectAreaCollision(0, 0, 100 ,100 , 50, 60)) myGfx.Print(0, 0, "A collision occurred!"); //Print out the fact!

## Methods of class Palette

void ConvertToNegativePalette(void)

Description:

This method will reverse your color table to a negative one, just like a negative photo.

Warnings:

None

Parameters:

None

Returns:

Nothing

Example:

Palette myPal; //Instantiate myGfx.GetPalette(myPal); //Get current system palette. myPal.ConvertToNegativePalette(); //Convert it. myGfx.SetPalette(myPal); //Use the negative colors.

void ConvertToGreyScalePalette(void)

Description:

As you probably know, this method will convert your color table into a grey one.

Warnings:

The name of this method is rather long

J

Parameters:

None

Returns:

Nothing

Example:

Palette myPal; //Instantiate myGfx.GetPalette(myPal); //Get current system palette. myPal.ConvertToGreyScalePalette(); //Convert it. myGfx.SetPalette(myPal); //Every color(!) will now be grey scaled.

void RotatePalette(unsigned char dist)

Description:

This method will rotate the color table with a specified number of steps. For instance: if color black is found in index zero of your color table and you then want to rotate the table 3 steps, then color black will be found in index 3 instead (and of course, all the other colors in the table have also been moved 3 steps forward).

Warnings:

None

Parameters:

None

Returns:

Nothing

Example:

Palette myPal; //Instantiate myGfx.GetPalette(myPal); //Get current system palette. myPal.RotatePalette(3); //Rotate the table 3 steps.

void SetRed(unsigned char index, unsigned char value)

Description:

All 256 different available colors can be made out from the three different base palettes, the red, green and blue. This method will let you set a specific value to an individual index position in the red base palette. All three base palettes consist of 256 indexes each.

Warnings:

None

Parameters:

index

is the index position (0 - 255) in the red base palette in which you want to set the new value.

value

is the specific value (0 - 255) to be inserted into the specified index in the red base palette.

Returns:

Nothing

Example:

Palette myPal; //Instantiate for(int I = 0; I < 256 ; I++) //Set maximum value in all indexes in red pal. myPal.SetRed(I, 255); //Make it all red. myGfx.SetPalette(myPal); //Set the new palette to be the active one.

void SetGreen(unsigned char index, unsigned char value)

Description:

All 256 different available colors can be made out from the three different base palettes, the red, green and blue. This method will let you set a specific value to an individual index position in the green base palette. All three base palettes consist of 256 indexes each.

Warnings:

None

Parameters:

index

is the index position (0 - 255) in the green base palette in which you want to set the new value.

value

is the specific value (0 - 255) to be inserted into the specified index in the green base palette.

Returns:

Nothing

Example:

Palette myPal; //Instantiate for(int I = 0; I < 256 ; I++) //Set max value in all indexes in green pal. myPal.SetGreen(I, 255); //Make it all green. myGfx.SetPalette(myPal); //Set the new palette to be the active one.

void SetBlue(unsigned char index, unsigned char value)

Description:

All 256 different available colors can be made out from the three different base palettes, the red, green and blue. This method will let you set a specific value to an individual index position in the blue base palette. All three base palettes consist of 256 indexes each.

Warnings:

None

Parameters:

index

is the index position (0 - 255) in the blue base palette in which you want to set the new value.

value

is the specific value (0 - 255) to be inserted into the specified index in the blue base palette.

Returns:

Nothing

Example:

Palette myPal; //Instantiate for(int I = 0; I < 256 ; I++) //Set max value in all indexes in blue pal. myPal.SetBlue(I, 255); //Make it all blue. myGfx.SetPalette(myPal); //Set the new palette to be the active one.

unsigned char GetRed(unsigned char index)

Description:

This method will return the value stored in index position (0 - 255)

index in the red base palette.

Warnings:

None

Parameters:

index

is the index position (0 - 255) in the red base palette from which you want to get the value.

Returns:

The value (0 - 255) found at the specified index position.

Example:

Palette myPal; //Instantiate myGfx.GetPalette(myPal); //Get current system palette. cout<<"Value in index 0 in palette red is "<<(int)myPal.GetRed(0)<<endl;

unsigned char GetGreen(unsigned char index)

Description:

This method will return the value stored in index position (0 - 255)

index in the green base palette.

Warnings:

None

Parameters:

index

is the index position (0 - 255) in the green base palette from which you want to get the value.

Returns:

The value (0 - 255) found at the specified index position.

Example:

Palette myPal; //Instantiate myGfx.GetPalette(myPal); //Get current system palette. cout<<"Value in index 0 in palette green is "<<(int)myPal.GetGreen(0)<<endl;

unsigned char GetBlue(unsigned char index)

Description:

This method will return the value stored in index position (0 - 255)

index in the blue base palette.

Warnings:

None

Parameters:

index

is the index position (0 - 255) in the blue base palette from which you want to get the value.

Returns:

The value (0 - 255) found at the specified index position.

Example:

Palette myPal; //Instantiate myGfx.GetPalette(myPal); //Get current system palette. cout<<"Value in index 0 in palette blue is "<<(int)myPal.GetBlue(0)<<endl;

void SetRGB(unsigned char index, unsigned char red, unsigned char green, unsigned char blue)

Description:

This method will let you set both the red, green and blue palette in a specific index (range between 0 - 255).

Warnings:

None

Parameters:

index

is the index position (0 - 255) in the palette table in which you want to set the red, green and blue values.

red

is the specific value (0 - 255) to be inserted into the specified index in the red base palette.

green

is the specific value (0 - 255) to be inserted into the specified index in the green base palette.

blue

is the specific value (0 - 255) to be inserted into the specified index in the blue base palette.

Returns:

Nothing (see the section 'Parameters' above)

Example:

Palette myPal; //Instantiate for(int I = 0; I < 256 ; I++) //Set max value in all indexes in palette. myPal.SetRGB(I, 255, 255, 255); myGfx.SetPalette(myPal); //Set the new palette to be the active one.

void GetRGB(unsigned char index, unsigned char& red, unsigned char& green, unsigned char& blue)

Description:

This method will let you get both the red, green and blue palette in a specific index (range between 0 - 255).

Warnings:

None

Parameters:

index

is the index position (0 - 255) in the palette table from were you want to get the red, green and blue values.

red

is the current value (0 - 255) stored in the specified index in the red base palette. Since this parameter is a reference, you will retrieve the data after the call of this method.

green

is the current value (0 - 255) stored in the specified index in the green base palette. Since this parameter is a reference, you will retrieve the data after the call of this method.

blue

is the current value (0 - 255) stored in the specified index in the blue base palette. Since this parameter is a reference, you will retrieve the data after the call of this method.

Returns:

Nothing (see the section 'Parameters' above)

Example:

Palette myPal; myGfx.GetPalette(myPal); //Get current system palette. unsigned char red, green ,blue; myPal.GetRGB(0, red, green, blue); //Get RGB from index zero. cout<<"Value in index 0 in palette red is "<<(int)red<<endl; cout<<"Value in index 0 in palette green is "<<(int)green<<endl; cout<<"Value in index 0 in palette blue is "<<(int)blue<<endl;

## Methods of class Keyboard

volatile int* InstallKeyboard(void)

Description:

This method will install the interrupt and returns a pointer to the new keyboard vector.

Since we are dealing with interrupts here, we have to declare the returned pointer as volatile so the compiler won't misinterpret its state (value) and make bad assumptions from it.

The new keyboard handler is able to track the following keys (these defined keys can be found in the file 'keydefs.hh'):

PRESS_UP | The 'up' arrow key is pressed
PRESS_DOWN | The 'down' arrow key is pressed
PRESS_LEFT | The 'left' arrow key is pressed
PRESS_RIGHT | The 'right' arrow key is pressed
PRESS_PGUP | The 'PageUp' key is pressed
PRESS_PGDOWN | The 'PageDown' key is pressed
PRESS_ALT | The 'Alt' key is pressed
PRESS_SPACE | The 'Space' key is pressed
PRESS_HOME | The 'Home' key is pressed
PRESS_END | The 'End' key is pressed
PRESS_INS | The 'Insert' key is pressed
PRESS_DEL | The 'Delete' key is pressed
RELEASE_UP | The 'up' arrow key is released
RELEASE_DOWN | The 'down' arrow key is released
RELEASE_LEFT | The 'left' arrow key is released
RELEASE_RIGHT | The 'right' arrow key is released
RELEASE_PGUP | The 'PageUp' key is released
RELEASE_PGDOWN | The 'PageDown' key is released
RELEASE_ALT | The 'Alt' key is released
RELEASE_SPACE | The 'Space' key is released
RELEASE_HOME | The 'Home' key is released
RELEASE_END | The 'End' key is released
RELEASE_INS | The 'Insert' key is released
RELEASE_DEL | The 'Delete' key is released
PRESS_ESC | The 'Esc' key is pressed

Warnings:

When executing this method, you are no longer able to use the old keyboard handler (i.e. functions such as getch(), won't work). To be able to use the old handler you have to restore the old handler using the method: '

UnInstallKeyboard()'.

Parameters:

None

Returns:

A pointer to keyboard vector whose indexes represents the keyboard key codes.

Example:

Keyboard myKbd; //Keyboard object //Get the pointer to the new vector. volatile int *kbdPtr = myKbd.InstallKeyboard(); //Is the left arrow key pressed? if(*(kbdPtr + PRESS_LEFT)) cout << "Left arrow key is pressed" << endl; //Or has it been released? if(*(kbdPtr + RELEASE_LEFT)) cout << "Left arrow key is not pressed" << endl;

void UnInstallKeyboard(void)

Description:

This method re-installs the old keyboard interrupt.

Warnings:

None

Parameters:

None

Returns:

Nothing

Example:

Keyboard myKbd; //Keyboard object //Get the pointer to the new vector. volatile int *kbdPtr = myKbd.InstallKeyboard(); //Get the old vector again. myKbd.UnInstallKeyboard();

## Methods of class Joystick

Note: When you create an object of this class, you have to (via the constructor) specify which joystick you want to apply these methods on.

For example

:

Joystick myFirstStick(1); //I want to use joystick 1.

Joystick mySecondStick(2); //I want to use joystick 2.

IMPORTANT:

Always check if a joystick is present (with method '

IsJoystickAvailable()') before reading its values, else the program may be locked in an infinite loop if no joystick exists.

unsigned char IsJoystickAvailable(void)

Description:

This is the most important method of this class. Here you will be able to detect if a joystick is available in the joystick port attached to your joystick card/sound card or what ever. If no joystick, or joystick card, can be found, a zero will be returned.

Warnings:

Just the simple fact that DO NOT forget to use this method before using the other methods in this class

Parameters:

None

Returns:

1 if joystick can be found.

0 if joystick can't be found.

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick.

unsigned short int GetXpos(void)

Description:

This method will give you the joystick's current internal x-position. This value has no big meaning for the application of yours since your are able to use other methods to see if the joystick's position has changed (such as method '

MoveLeft()'). But perhaps you can have some use for it that I don't know, so therefore I included it anyway.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

The internal x-position of the joystick

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick. unsigned short int x = myStick.GetXpos(); //x contain the current position

unsigned short int GetYpos(void)

Description:

Same as the above method, but you will get the internal y-position.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

The internal y-position of the joystick

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick. unsigned short int y = myStick.GetYpos(); //y contain the current position

unsigned char IsButtonPressed(unsigned char buttonNr)

Description:

Here you can test to see if a button has been pressed on your joystick. You will be able to test four different buttons.

Warnings:

Make sure that a joystick is available.

Parameters:

buttonNr

is a number between 1 - 4. Representing the buttons on the joystick.

Returns:

0, if the specified button isn't pressed.

1, if the specified button is pressed.

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick. if(myStick.IsButtonPressed(1)) cout<<"Button 1 on joystick 1 is pressed"<<endl;

void CalibrateLeft(void)

Description:

This method is used to calibrate the joystick in the left position. This must be done so the object can calculate the limits of the joystick's movements and in that way decide the correct movements.

This method should be used together with the other calibrating methods.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

Nothing

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick. cout<<"Move joystick to left and then press fire"<<endl; while(!myStick.IsButtonPressed(1)) { myStick.CalibrateLeft(); } while(myStick.IsButtonPressed(1)) {} //Wait until button 1 is pressed.

void CalibrateRight(void)

Description:

This method is used to calibrate the joystick in the right position. This must be done so the object can calculate the limits of the joystick's movements and in that way decide the correct movements.

This method should be used together with the other calibrating methods.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

Nothing

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick. cout<<"Move joystick to right and then press fire"<<endl; while(!myStick.IsButtonPressed(1)) { myStick.CalibrateRight(); } while(myStick.IsButtonPressed(1)) {} //Wait until button 1 is pressed.

void CalibrateUp(void)

Description:

This method is used to calibrate the joystick in the upper position. This must be done so the object can calculate the limits of the joystick's movements and in that way decide the correct movements.

This method should be used together with the other calibrating methods.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

Nothing

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick. cout<<"Move joystick up and then press fire"<<endl; while(!myStick.IsButtonPressed(1)) { myStick.CalibrateUp(); } while(myStick.IsButtonPressed(1)) {} //Wait until button 1 is pressed.

void CalibrateDown(void)

Description:

This method is used to calibrate the joystick in the lower position. This must be done so the object can calculate the limits of the joystick's movements and in that way decide the correct movements.

This method should be used together with the other calibrating methods.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

Nothing

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick. cout<<"Move joystick down and then press fire"<<endl; while(!myStick.IsButtonPressed(1)) { myStick.CalibrateDown(); } while(myStick.IsButtonPressed(1)) {} //Wait until button 1 is pressed.

void CalibrateNeutral(void)

Description:

This method is used to calibrate the joystick in the Neutral position. This must be done so the object can calculate the limits of the joystick's movements and in that way decide the correct movements.

This method should be used together with the other calibrating methods.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

Nothing

Example:

Joystick myStick(1); //Use joystick 1. if(!myStick.IsJoystickAvailable()) exit(1); //Couldn't find a joystick. cout<<"Move the joystick to the neutral position and then press fire"<<endl; while(!myStick.IsButtonPressed(1)) { myStick.CalibrateNeutral(); } while(myStick.IsButtonPressed(1)) {} //Wait until button 1 is pressed.

unsigned char MoveLeft(void)

Description:

After you have calibrate the joystick, you will be able to use this method to see (detect) if the user has moved the joystick to the left.

You should also have set the sensitivity of the joystick's movement detector with the method '

SetSensitivity()' before using this method.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

0, if the stick points at any position but left.

1, if the stick's position is to the left.

Example:

if(myStick.MoveLeft()) cout<<"Joystick in left position"<<endl;

unsigned char MoveRight(void)

Description:

After you have calibrate the joystick, you will be able to use this method to see (detect) if the user has moved the joystick to the right.

You should also have set the sensitivity of the joystick's movement detector with the method '

SetSensitivity()' before using this method.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

0, if the stick points at any position but right.

1, if the stick's position is to the right.

Example:

if(myStick.MoveRight()) cout<<"Joystick in right position"<<endl;

unsigned char MoveUp(void)

Description:

After you have calibrate the joystick, you will be able to use this method to see (detect) if the user has moved the joystick to the upper position.

You should also have set the sensitivity of the joystick's movement detector with the method '

SetSensitivity()' before using this method.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

0, if the stick points at any position but up.

1, if the stick's position is down.

Example:

if(myStick.MoveUp()) cout<<"Joystick in upper position"<<endl;

unsigned char MoveDown(void)

Description:

After you have calibrate the joystick, you will be able to use this method to see (detect) if the user has moved the joystick to the lower position.

You should also have set the sensitivity of the joystick's movement detector with the method '

SetSensitivity()' before using this method.

Warnings:

Make sure that a joystick is available.

Parameters:

None

Returns:

0, if the stick points at any position but down.

1, if the stick's position is down.

Example:

if(myStick.MoveDown()) cout<<"Joystick in lower position"<<endl;

void SetSensitivity(unsigned char value)

Description:

This method will let you set the sensitivity of the joystick's movement detector (well, it's in software though). This is very important since the joystick's internal x and y values are changing very frequently because of its analog behavior. So, to be able to differ between: if the user has moved the stick at any direction or, if it is just some other disturbances causing the internal values to change, you will have to set its sensitivity.

You are able to set a sensitivity between 0 - 100 %. A hundred percent sensitivity means that your joystick will react on everything (even to your heartbeats

J ). Setting zero sensitivity will turn your joystick into a corpse.

Warnings:

Make sure that a joystick is available.

Parameters:

value

is a percentage value between 0 - 100.

Returns:

Nothing

Example:

//90% out of 100% is a common value to use. myStick.SetSensitivity(90);

## Methods of class Mouse

This class will not provide you with a default mouse screen cursor to associate with the mouse. This however is very simple to do by creating a simple transparent 'Bitmap' object and then draw it with the method '

DrawBitmap()' together with the mouse current screen position extracted by using the method 'GetMousePositionAndButtons()'.

short int IsMouseAvailable(void)

Description:

Before using any other method of this class you must first use this one to see if there is a mouse available in the serial port.

Warnings:

None

Parameters:

None

Returns:

0 if no mouse were found.

1 if a mouse were found

Example:

Mouse myMouse; //Create a mouse object. if( myStick.IsMouseAvailable() ) //Check if there is a mouse connected cout<<"Mouse found!"<<endl; //Yes there is! else cout<<"No mouse found!"<<endl; //Sorry!

short int NoOfMouseButtonsAvailable(void)

Description:

This method will give you the number of buttons available on your mouse.

Warnings:

Make sure that a mouse is available (using method '

IsMouseAvailable()').

Parameters:

None

Returns:

The number of buttons found on your mouse.

Example:

Mouse myMouse; //Create a mouse object. if( myStick.IsMouseAvailable() ) //Check if there is a mouse connected cout << "Mouse found and it has " << myMouse.NoOfMouseButtonsAvailable() << " buttons" << endl; //Print out the number of buttons detected. else cout << "No mouse found!" << endl; //Sorry!

void SetSensitivity(short int xAxis, short int yAxis, short int doubleSpeed)

Description:

This method will allow you to set the sensitivity of the mouse movements i.e. how much you have to move the mouse in a certain direction compared to the movements of the screen cursor.

Warnings:

Make sure that a mouse is available (using method '

IsMouseAvailable()').

Parameters:

xAxis

is the sensitivity of the mouse movement in x-axis (range between 0 - 100).

yAxis

is the sensitivity of the mouse movement in y-axis (range between 0 - 100).

doubleSpeed

is the sensitivity of double speed (range between 0 - 100).

Returns:

Nothing

Example:

Mouse myMouse; //Create a mouse object. if(!myStick.IsMouseAvailable() ) //Check if there is a mouse connected exit(1); //No, exit! myMouse.SetSensitivity(50, 50 ,50);

void GetMousePositionAndButtons(short int& x, short int& y, short int& leftButton, short int& middleButton, short int& rightButton)

Description:

This method will give you the absolute mouse position of your mouse (in number of pixels) and the state of all mouse buttons. Absolute value means that if the position is 30 for a certain moment and then decreases by 5, then the new value will be 35 and not 5.

Warnings:

Make sure that a mouse is available (using method '

IsMouseAvailable()').

This method will not let you simulate a third button press by pressing the two others at the same, this you will have to simulate by your self by reading the state of parameters

leftButton and rightButton.

Parameters:

x

is the mouse current absolute position in x-axis given in number of pixels. Since this is a reference, an integer (the position) is returned to you through the parameter after the call of this method.

y

is the mouse current absolute position in y-axis given in number of pixels. Since this is a reference, an integer (the position) is returned to you through the parameter after the call of this method.

leftButton

is used for detecting the state of your mouse left button. If the left button is pressed, the integer 1 is returned else 0.

middleButton

is used for detecting the state of your mouse middle button (if there is one). If the middle button is pressed, the integer 1 is returned else 0. The value zero will always be returned if your mouse doesn't have a middle button.

leftButton

is used for detecting the state of your mouse right button. If the right button is pressed, the integer 1 is returned else 0.

Returns:

Nothing (see section 'Parameters' above)

Example:

Mouse myMouse; //Create a mouse object. if(!myStick.IsMouseAvailable() ) //Check if there is a mouse connected exit(1); //No, exit! short int x, y, tmp, leftButton = 0; while(!leftButton) //Press left mouse button to quit! { myMouse.GetMousePositionAndButtons(x, y, leftButton, tmp, tmp); cout << "x = " << x << ", y = " << y << endl; }

void GetMouseRelMotions(short int& x, short int& y)

Description:

Here you can get the mouse relative position in number of mickeys which is 1/200th of an inch. The values returned will be the relative motion of your mouse since the last call of this method.

Warnings:

Make sure that a mouse is available (using method '

IsMouseAvailable()').

Parameters:

x

is the relative number of mickeys in x-axis made during the last call of this method (range between -32768 to 32767). Since this is a reference, the value is returned to you through the parameter after the call of this method.

y

is the relative number of mickeys in y-axis made during the last call of this method (range between -32768 to 32767). Since this is a reference, the value is returned to you through the parameter after the call of this method.

Returns:

Nothing (see section 'Parameters' above)

Example:

Mouse myMouse; //Create a mouse object. if(!myStick.IsMouseAvailable() ) //Check if there is a mouse connected exit(1); //No, exit! short int x, y, tmp, leftButton = 0; while(!leftButton) //Press left mouse button to quit! { myMouse.GetMousePositionAndButtons(x, y, leftButton, tmp, tmp); myMouse.GetMouseRelMotions(x, y); cout << "x = " << x << ", y = " << y << endl; }