Annex Solutions Foundation Classes Documentation Vs. 1.01 (10/27/2002)
Written By: Andy Stone
ASFC By: Andy Stone (astone42@attbi.com), Eoin Coffey (eoin@angrystickman.com)
Visit: http://loreandlutes.sourceforge.net for more information.
See copying.txt or copying for licensing information.
sound better.
Header For ------ --- animation.h ASFC_Animation console.h ASFC_Console font.h ASFC_Font fontpalette.h ASFC_FontPalette input.h ASFC_Input linkedlist.h ASFC_LinkedList matrix.h ASFC_Matrix mousepointer.h ASFC_MousePointer multiimage.h ASFC_MultiImage screen.h ASFC_Screen surface.h ASFC_Surface timer.h ASFC_Timer utils.h ASFC_Utils
In this documentation I'll assume that all ASFC headers are in a subfolder called ASFC in your include path. So, for example, to include the header animation.h you'd do this:
#include <asfc/animation.h>
If you're programming in Windows whenever including headers please be careful to not capitalize any letters! Although it may compile and work under windows it might now compile and work fine in other operating systems. This is because most posix OSs have case sensitive files and windows does not.
ASFC_Animation: Used for creating raster (non vector) animations.
ASFC_Console Used for displaying graphical text in a console like
interface. It works simliarish to cout.
ASFC_Font A graphical font object.
ASFC_FontPalette Aggregates (holds) several font objects. Console objects
realize (point to) font palette objects.
ASFC_Input Handles keyboard and mouse input.
ASFC_LinkedList A templated linked list container class.
ASFC_Matrix A 2d Linked List.
ASFC_MousePointer Loads a mouse pointer from a text (.cursor) document.
ASFC_MultiImage An image object that parses itself into periodic smaller
images. A multiimage file (.png, .bmp, etc.). Looks like
a strip of images.
ASFC_Screen An ASFC_Surface that will draw its contents to the screen
whenever the Update() member is called.
ASFC_Surface Holds graphical data.
ASFC_Timer Handles timing, counts milliseconds.
ASFC_Utils Not a class, but includes several handy macros and
functions.
//Create a new ASFC screen object that's 640x480x32
ASFC_Screen screen(640, 480, 32);
If you want your game to appear in full screen then add the parameter 'true' after the bits per pixel (bpp) parameter in the constructor. For example:
//Create a new ASFC screen object that's 640x480x32 and in full screen mode.
ASFC_Screen screen(640, 480, 32, true);
//Primitives
int DrawPixel(int x, int y, int r, int g, int b, int a);
int DrawLine (int x1, int y1, int x2, int y2, int r, int g, int b, int a);
int DrawRectangle(int x, int y, int width, int height, int r, int g, int b, int a);
int DrawFillRectangle(int x, int y, int width, int height, int r, int g, int b, int a);
int DrawCircle(int x, int y, int radius, int r, int g, int b, int a);
int DrawFillCircle(int x, int y, int radius, int r, int g, int b, int a);
int main(int argc, char *argv[])
{
//First we have to initialize ASFC screen, we'll set it to be 640x480x32 ASFC_Screen screen(640, 480, 32);
//Loop 6000 times
for(int i = 0; i < 6000; i++)
{
screen.DrawFillRectangle
(
rand() % 640, rand() % 480,
rand() % 150, rand() % 150, rand() % 255, rand() % 255,
rand() % 255, rand() % 255
);
if(i % 50 == 0)
screen.Update();
}
//You haven't learned ASFC_Input yet but it will just pause until space is depressed
ASFC_Input input;
while(input.KeyUp(SDLK_SPACE)) input.Update();
}
LoadImage(string file, int transred = -1, int transgrn = -1, int transblu = -1);
Example (load image "test.png" into a surface called surface and make all blue pixels transparent)
ASFC_Surface surface;
surface.LoadImage("test.png", COLOR_BLUE);
If you don't want your image to have any transparent pixels pass -1 to the transparency parameters.
Example: (Take surface and blit it to the screen at 50, 50): surface.BlitTo(screen, 50, 50);
int GetWidth() Gets the width of this surface int GetHeight() Gets the height of this surface int GetBpp() Gets the BPP of this surface
MEMVAR_SET: Creates a member that sets a variable. MEMVAR_GET: Returns a member that returns a variable MEMVAR_SETGET: Combines both of the above macros into one creating two members. MEMVAR_LINK: Creates two members that overload eachother one for setting
another for getting.
MEMVAR_GETREF: Creates a function that returns a variable by reference.
Example:
#include <asfc/utils.h>
class ASFC_TestClass
{
private:
int iValue;
public:
MEMVAR_SETGET(SetVal, Val, int, iValue);
}
int main()
{
ASFC_TestClass test;
for(int i = 0; i < 10; i++)
{
test.SetVal(i);
cout << test.Val() << " ";
}
return 0;
}
Output:
0 1 2 3 4 5 6 7 8 9
COLOR_RED 0xff, 0x00, 0x00 COLOR_GREEN 0x00, 0xff, 0x00 define COLOR_BLUE 0x00, 0x00, 0xff COLOR_YELLOW 0xff, 0xff, 0x00 COLOR_PURPLE 0xff, 0x00, 0xff COLOR_CYAN 0x00, 0xff, 0xff COLOR_GRAY 0x7f, 0x7f, 0x7f #define COLOR_LIGHT_RED 0xff, 0x7f, 0x7f #define COLOR_LIGHT_GREEN 0x7f, 0xff, 0x7f #define COLOR_LIGHT_BLUE 0x7f, 0x7f, 0xff #define COLOR_LIGHT_YELLOW 0xff, 0xff, 0x7f #define COLOR_LIGHT_PURPLE 0xff, 0x7f, 0xff #define COLOR_LIGHT_CYAN 0x7f, 0xff, 0xff #define COLOR_LIGHT_GRAY 0xbf, 0xbf, 0xbf #define COLOR_DARK_RED 0x7f, 0x00, 0x00 #define COLOR_DARK_GREEN 0x00, 0x7f, 0x00 #define COLOR_DARK_BLUE 0x00, 0x00, 0x7f #define COLOR_DARK_YELLOW 0x7f, 0x7f, 0x00 #define COLOR_DARK_PURPLE 0x7f, 0x00, 0x7f #define COLOR_DARK_CYAN 0x00, 0x7f, 0x7f #define COLOR_DARK_GRAY 0x3f, 0x3f, 0x3f #define COLOR_GRAY_0 0x00, 0x00, 0x00 #define COLOR_GRAY_1 0x10, 0x10, 0x10 #define COLOR_GRAY_2 0x20, 0x20, 0x20 #define COLOR_GRAY_3 0x30, 0x30, 0x30 #define COLOR_GRAY_4 0x40, 0x40, 0x40 #define COLOR_GRAY_5 0x50, 0x50, 0x50 #define COLOR_GRAY_6 0x60, 0x60, 0x60 #define COLOR_GRAY_7 0x70, 0x70, 0x70 #define COLOR_GRAY_8 0x80, 0x80, 0x80 #define COLOR_GRAY_9 0x90, 0x90, 0x90 #define COLOR_GRAY_A 0xa0, 0xa0, 0xa0 #define COLOR_GRAY_B 0xb0, 0xb0, 0xb0 #define COLOR_GRAY_C 0xc0, 0xc0, 0xc0 #define COLOR_GRAY_D 0xd0, 0xd0, 0xd0 #define COLOR_GRAY_E 0xe0, 0xe0, 0xe0 #define COLOR_GRAY_F 0xf0, 0xf0, 0xf0 #define COLOR_BLACK 0x00, 0x00, 0x00 #define COLOR_WHITE 0xff, 0xff, 0xff
//Oranges & Browns
#define COLOR_ORANGE 0xff, 0x80, 0x00 #define COLOR_LIGHT_ORANGE 0xff, 0xbf, 0x80 #define COLOR_DARK_ORANGE 0xbf, 0x5f, 0x00 #define COLOR_BROWN 0xa5, 0x7b, 0x48 #define COLOR_LIGHT_BROWN 0xa5, 0x93, 0x7c #define COLOR_DARK_BROWN 0x59, 0x45, 0x2c
Example (Create a red rectangle)
screen.DrawFillRectangle(0, 0, 50, 50, COLOR_RED, 0xFF)
string UpperString(string s) Returns s in all caps.
string Val(double d); Converts a value to a string.
double Val(string s); Converts a string to a value.
string Rot(int iChars, string s); Rotates all the chars iChars down in a
string. The most basic encryption
algorithm that can be done.
void SToStr(string s, char* str); Converts a C++ string to an C string
string Qoute(string s); Returns string s surrounded with qoutes.
string ReadString(ifstream &oFile); Reads in a string surrounded by double.
qoutes, a la from the Qoute() member,
from an ifstream.
bool FileExist(string sFile); Returns true if sFile exists.
The utils.h header also includes several more constants and macros. I suggest you take a look at it it's really scary ;-).
void Reset() Reset the # of milliseconds ellapsed.
void Delay(long lMilliseconds); Pauses until lMilliseconds of time have
ellapsed since the last reset.
bool Ellapsed(long lMilliseconds); True if lMilliseconds of time have
ellapsed.
long Ellapsed(); Returns the # of mills ellapsed since
Reset() was last called.
Example (Wait 100 milliseconds):
ASFC_Timer oTime;
oTime.Reset();
oTime.Delay(100);
Make sure you use the reset member before calling Delay or else you may hang your system.
void Resize(int iNewLength); Resize the list to iNewLength elements void Resize(int iNewLength, T &zDefault); Resize the list to iNewLength elements, fill them with zDefault
void Push(T zWhat); Push zWhat on to the end of the list void PushFront(T zWhat); Push zWhat on to the front of the list void AddElement(int iElement, T zWhat); Add element zWhat after element # iElement T ReadLast(); Read the last element T Pop(); Read and remove the last element T& operator[](int iElement); Return element iElement int Length(); Return the # of elements void Delete(int iElement); Remove element # iElement
An ASFC_Matrix class works simliarly except when resizing you pass it a length and height and you use two [][]s to access data. For example:
ASFC_Matrix<string> matrix;
matrix.Resize(3, 3);
matrix[1][1] = "1, 1";
Example: (Load font normal_console_font and write hello world on the screen:
ASFC_Font font;
font.Load("fonts/normal_console_font.png", 8, 14, COLOR_BLUE)
font.WriteTo(screen, 50, 50, "Hello, World!");
Example: (Create a font palette with the fonts normal_console_font.png and runic_console_font.png)
ASFC_FontPalette palette;
palette.AddFont("./fonts/normal_console_font.png", 8, 14, COLOR_BLUE);
palette.AddFont("./fonts/runic_console_font.png", 8, 14, COLOR_BLUE);
Example:
ASFC_FontPalette palette;
palette.AddFont("./fonts/normal_console_font.png", 8, 14, COLOR_BLUE);
palette.AddFont("./fonts/runic_console_font.png", 8, 14, COLOR_BLUE);
ASFC_Console con;
con.SetFontPalette(&palette);
con.SetSurface(&screen);
con << "Testing Console\n";
con.Draw();
screen.Update();
You can also grab input for the string, double, and int data types by using the >> operator.
Example:
string s;
con >> s;
con << "\nYou just typed: " << s << "\n";
The KeyUp and KeyDown members are probably the most useful in games. The return true if the passed SDLKey is up or depressed. Before polling for keyboard input its generally a good idea to call the Update() member which rechecks the keyabord for its state. If you forget to do this you may get some errors. The GetMouseX(), GetMouseY(), and GetMouseButton() members handle mouse input.
Exampple (Draw info about mouse input while escape isn't depressed)
ASFC_Input input;
int loops = 0;
while(input.KeyUp(SDLK_ESCAPE))
{
//Display curret key info
cout << loops << ": " << input.GetMouseX() << " "
<< input.GetMouseY() << endl;
input.Update();
}
The GetKey() members will poll the keyabord for any depressed key and will return the first depressed key found. There are two versions:
SDLKey GetKey();
int GetKey(bool fRefreshData, int iKeyDelay, int iRepeatRate);
The second version will return the SDLKey (as an int) based on certain timing information. For example:
GetKey(false, 200, 200);
will only return a key if 200 milliseconds have passed. This member is nice when you want to handle keyboard input like a text editor.
Example cursor file (cursor.cursor):
0 0
X............................... XX.............................. X#X............................. X##X............................ X###X........................... X####X.......................... X#####X......................... X######X........................ X#######X....................... X########X...................... X#####XXXXX..................... X##X##X......................... X#X.X##X........................ XX..X##X........................ X....X##X....................... .....X##X....................... ......X##X...................... ......X##X...................... .......XX....................... ................................ ................................ ................................ ................................ ................................ ................................ ................................ ................................ ................................ ................................ ................................ ................................ ................................
Example Code:
ASFC_Cursor cursor;
cursor.Load("cursor.cursor");
cursor.Set();
Errors, Bugs, Questions, Comments?
SDLK_LSUPER= 311 Left windows or penguin key SDLK_RSUPER= 312 Right windows or penguin key SDLK_MODE= 313 Alt Gr key on some international keyboards
SDLK_COMPOSE= 314
SDLK_POWER Mac power key SDLK_EURO= 321 On some european keyboards SDLK_UNDO= 322 On Atari keyboards