[Long!] Game Lib specs...
Wed, 27 Aug 1997 14:56:15 -0400
BASE GRAPHICS OBJECT:
Object Methods:
* Init - Check for required drivers, init conditions, etc.
* Done - Dispose of pre-allocated memory, dispose of
off-screen buffer if neccessary
Screen Methods:
* GetRaw - Retrieves a section directly from the screen into a
"Universal" format
* PutRaw - Places a raw bitmap
* SetMode - Handle modes specific to object, initialize look-up
table, allocate off-screen buffer, change conditions
if neccessary
* ShowVirtScr - Shows default off-screen buffer
* ShowUserVirtScr - Shows external off-screen buffers, for
triple buffering
Palette Methods:
* GetPalette - Retrieves screen palette, intended for
256 color modes
* SetPalette - Set palette, intended for 256 color modes
* RotatePalette - Rotate screen palette, intended for
256 color modes
* FadeIn - Fade in palette
* FadeOut - Fade out palette
GUI Primitive Methods:
* HLine - Horizontal Line
* VLine - Veritcal Line
* Line - Line for any direction
* Rect - Hollow rectangle
* FilledRect - Filled rectangle
* Shadedrect - Hollow rectangle, color1 for upper & left,
color2 for lower & right line
* FilledShadedRect - Hollow rectangle, color1 for upper & left,
color2 for lower & right line, color3 for
fill color
Sprite Primitive Methods:
* GetSpr - Retrieves a sprite directly form the screen
* PutSpr - Places a sprite with transparency and clipping
* PutTile - Places sprite/tile having square dimensions with
transparency and clipping
* PutBkgTile - Places sprite/tile having square dimensions with
clipping
Font Methods:
* PutChar - Places a char using a monochrome font
* PutString - Places a string with a monochrome font
* DrawChar - Places a char using a bitmapped font
* DrawString - Places a string with a bitmapped font
Mouse Methods:
* HideMouse - Hide current Mouse cursor
* ShowMouse - Show current Mouse cursor
* ButtonClick - Updates Mouse button press status
* MouseMove - Updates Mouse coordinates according to current
video mode
* SetUserCursor - Sets cursor to either monochrome or bitmap
Variables:
* GraphErr - Graphic "driver" error code
* GraphOk - Init failure/success
* GraphMode - Current internal graphics mode
* MinX, MinY, MaxX, MaxY - Screen resolution
* ClipX, ClipY, ClipX2, ClipY2 - Clip region
* DirectWrite - Write/Don't Write direct to screen
* VirtSel - Selector for off-screen buffer
* VirtOfs - Offset of off-screen buffer
* VirtScr - Full pointer to off-screen buffer
* wScrSel - Screen write selector
* rScrSel - Screen read selector
* LuT - Lookup Table, must be declared by inherited objects
since Pascal doens't allow inherited variables to
change in size
GENERIC GRAPHICS ROUTINES:
Screen Operations:
* InitMode - Checks mode range, allocates appropriate "driver",
sets base object pointer to allocated "driver",
calls Init and SetMode methods
* GetMode - Returns GraphMode variable
* DoneMode - Disposes current "driver" after calling Done method
GUI Primitives/Sprite Primitives/Mouse Primitives:
* Procedural/Function wrappers to methods
* Function methods to certain variables
Mode specific support:
VBE/Quantizing:
* DecodeRGB - Convert from R/G/B to 256 color index
* EncodeRGB - Convert from 256 color index to R/G/B value
according to graphic mode memory model
* SetFntDepth - Set depth of font if bitmapped; reduce colors
if Pixel Bit Depth is less than Font Bit
Depth, increase colors if greater than, nothing
if equal
* SetSprDepth - Set depth of sprite; reduce colors if Pixel Bit
Depth is less than Font Bit Depth, increase
colors if greater than, nothing if equal
* SetRawDepth - Set depth of raw bitmap; reduce colors if Pixel
Bit Depth is less than Font Bit Depth, increase
colors if greater than, nothing if equal
Mode-X:
* Linear2PlanarFnt - Convert linear bitmapped font to Mode-X
planar
* Linear2PlanarSpr - Convert linear sprite to Mode-X planar
* Linear2PlanarRaw - Convert linear bitmap to Mode-X planar
KEYBOARD:
Procedures/Functions:
* KeyPressed - Reports whether or not a key has been pressed
* ReadKey - If key is ready, returns scan code
* PushKey - Simulates key press
Variables:
* CurKey - Scan Code of current key pressed
* Key - Table for each key, status of whether or not key is
pressed, used for multiple keypresses
Cheat Code Support:
* AddCheatCode - Places key combination in cheat code list, set
appropriate handler via procedural pointer
* DelCheatCode - Removes key combination from cheat code list
SPRITES:
Procedures (According to graphics mode memory model):
* ScaleSprite - Resize sprite
* RotateSprite - Rotates sprite
* CreateMask - Used for collision detection
* FlipSprite - Flips a sprite vertically
* MirrorSprite - Flips a sprite horizontally
File Operations:
* LoadSprite - Load sprite file, if key is not blank, loads
from resource file
BASE BITMAP OBJECT:
Object Methods:
* Init - Sets file name, and resource key (if applicable)
* Done - Disposes memory allocated to bitmap
Bitmap Methods:
* LoadBitmap - Loads BMP/PCX/etc file, if key is not blank,
loads from resource file
* LoadBitmapXY - Loads BMP/PCX/etc file, if key is not blank,
loads from resource file. Loads a portion of
the bitmap
* GetMemUsed - Returns amount of memory used by "raw" bitmap
* GetRawPtr - Returns pointer to bitmap buffer
* GetPalettePtr - Returns pointer to bitmap's palette if present
Format Saving Functions:
* SavePCX
* SaveBMP
* SaveGIF
* etc.
SPECIAL EFFECTS:
Sprite Operations:
* GlassLens - Glass Lens effect
* Sinus - Sinus effect
Screen Operations:
* DissolveIn - Dissolve screen from background
* DissolveOut - Dissolve screen to background
* ExitLeft - Slide screen to the left
* ExitRight - Slide screen to the right
* ExitUp - Slide screen upwards
* ExitDown - Slide screen downwards
* MotionBlur - Display sprite with a trail
SOUND & MUSIC:
Device Operations:
* InitDevice - Initialize sound card, if specified to, installs
handler
* SetVolume - Set sound card volume
* PollDevice - Manually checks sound card, used if programmer has
their own timer
MOD/S3M/669/MIDI operations:
* LoadMusic - Loads music file, if key is not blank, loads
from resource file
* PauseMusic - Pause music
* PlayMusic - Play music
* DoneMusic - Unload music from memory
* SetMusicVol - Change volume of music
WAV/Raw operations:
* LoadSound - Loads sound file, if key is not blank, loads
from resource file
* PauseSound - Pause sound
* PlaySound - Play sound
* DoneSound - Unload sound from memory
* SetSoundVol - Change volume of sound
Flags:
* DevPoll - Flag to indicate that sound card is to be
checked manually
* DevDMA - Flag to indicate that DMA ISR handler should be
installed
* DevTimer - Flag to indicate that Timer ISR handler is to be used
MISC ROUTINES:
Procedures:
* MoveFPU - FPU mode from dest to source, Pentium optimization
* MoveSD - DWord moves from dest to source, 386+ optimization
* IncPtr - Increments pointer to next offset
* UIntStr - Converts a number up to DWord size to string,
0 padded if specified
JOYSTICK:
Procedures:
* AddActionEvent - Activates specified procedure according to
Joystick action
Functions:
* ReadAxis - Updates Axis matrix by reading joystick
* ButtonPressed - Updates Button press status, used
like Keypressed
Variables:
* Axis - Array of booleans coresponding to joystick axis
* Button - Array of Booleans about whether or not a specific
button on the specific joystick has been pressed
RESOURCE FILE:
Object Methods:
* Init - Sets resource filename, if filename is blank, resource
file is appended to the end of the application file.
Loads file list into memory
* Done - Unload file list, release allocated memory
Compression Methods:
* EncodeStored - Saves memory buffer to file as is
* EncodeFixed - Saves memory buffer to file using fixed
Huffman codes
* EncodeDynamic - Saves memory buffer to file using dynamic
Huffman codes
* EncodeRes - Compresses and saves memory buffer to the main
resource file, calls EncodeStored, EncodeFixed,
and EncodeDynamic
* EncodeFile - Adds a file to the main resource file
Decompression Methods:
* DecodeStored - Loads resource into memory as is
* DecodeFixed - Loads resource into memory using fixed
Huffman codes
* DecodeDynamic - Loads resource into memory using dynamic
Huffman codes
* DecodeRes - Decompresses and loads into memory a resource from
the main resource file, calls DecodeStored,
DecodeFixed, and DecodeDynamic
* DecodeFile - Decodes a file outside of the main resource file
into memory
Search Methods:
* SearchRes - Searches for key, returns whether or not key has
been found
GUI:
Objects:
* TAppShell - Message/Event based application skeleton
* TWindow - Window object
* TDesktop - Area between TMenuBar and TStatusBar
* TStatusBar - Shows hints, or in games shows game stats
* TMenuBar - Menus at the top of the screen
* TPopupMenu - Submenus for TMenuBar, or free floating
Pop-up menus
* TCheckBox - Check box handler
* TRadioBtn - Radio button handler
* TScrollBars - Scroll bars, horizontal or vertical
* TStaticText - Shows a regular string
* TInputLine - Takes non-modal input
* TStringList - Returns which item has been clicked from a list
* TStatusCounter - Returns percentage
Common Dialog Objects:
* TFileDlg - Multiple purpose file dialog, shows directory
listing, file listing, file input line, returns file
name chosen from list and button result
* TColorDlg - Color picker dialog, shows available colors
depending on memory model of current graphics mode
* TMessageBox - Message box dialog, used for "About", Error
messages, etc
MOUSE:
Procedures:
* SetCustomMouseHandler - Installs custom mouse handler for mouse
click, or mouse movement
* ReadMouse - Updates variables manually
* SimMouseAction - Simulates a mouse action
Functions:
* InitMouse - Initializes mouse, uses flags for Hardware reset,
Software reset, or both. Returns whether or not driver
is present
Variables:
* MouseDblClick - If true, mouse button has been clicked twice
* MousePress - If true, mouse button is down
* MouseRelease - If true, mouse button has been released
* MouseBtn - Array of Booleans corresponding to mouse button
* MouseX, MouseY - Coordinates of mouse cursor
TIMER:
Procedures:
* StartTime - Installs timer, records start time (if slow clock)
* StopTime - Removes timer, records stop time (if slow clock)
* InitTimer - Installs timer handler
* SetRate - Sets rate of timer
Variables:
* UserFastTimer - Hook for user defined fast timer
* UserSlowTimer - Hook for user defined slow timer
BASE ANIMATION OBJECT:
Object Methods:
* Init - Sets file name, and resource key (if applicable)
* Done - Disposes memory allocated to animation
Animation File Methods:
* LoadAnim - Loads AVI/FLI/etc file, if key is not blank,
loads from resource file
Animation Action Methods:
* PlayAnim - Plays animation until done
* RevAnim - Reverses direction of animation
* PauseAnim - Pause animation
* StopAnim - Stop animation
* NextFrame - Returns a pointer to a Raw bitmap frame, used to
manually update frame
* PrevFrame - Returns a pointer to a Raw bitmap frame, used to
manually update frame
* SetPlayRate - Sets playback rate
* FFAnim - Fast forward
* RWAnim - Rewind
Animation Misc Methods:
* GetMemUsed - Returns amount of memory used by "raw" bitmap
* GetRawPtr - Returns pointer to bitmap buffer
* GetPalettePtr - Returns pointer to bitmap's palette if present
Animation Save Functions:
* SaveAVI
* SaveFLI
* etc
Variables:
* DrawProc - Procedural pointer to draw frame
* PlaySound - Procedural pointer to play sound
This is the preliminary draft, I got my ideas form things I liked,
disliked, saw what could be done better, etc. There are a couple of things
that are up in the air, especially the resource file manager, I want to
structure it in a way that the file is opened as needed rather than having
the file pointer opened until closed. Another goal of this lib is to be
able to switch resolutions dynamically and everything will be scaled
proportionately. I'd like for bitmap/font/sprite color depth to be
reduced/incresed. Dynamic mode resolution change is especially useful for
3-D engines such as Quake as everything can merely scale itself and
re-draw.
The problem I face with this is the following example scenario:
320x200x256 color mode set
256 color sprites loaded
640x480x32k color mode set
256 color bitmaps converted from color indices to
RGB encoded word (1:5:5:5)
640x480x256 color mode set
32k color bitmaps converted from RGB encoded
Word to 256 color indices
It's ok if you didn't understand the scenario, the point of it is how I
should handle converting from palette indices to the appropriate RGB
encoded model? I was thinking of loading the file, encoding it to a
temporary buffer, releasing the loaded bitmap, and then setting the pointer
to the buffer. Alternatively, the programmer can put bitmaps for every
memory model, but as you know it would take up too much disk space. My goal
is to be able to use the bitmap at any
screen depth.
Something else I planned about this library is the conversion of bitmaps,
you load a bitmap from a specific format, when loaded it is in a "Raw
universal format" meaning palette indices or (4 byte) RGB, you can then
save it in
a different format with the appropriate function. This isn't meant to be
done in realtime, however the Save/Load functions will be as fast as
possible (like the screen snapshots in games for previews, etc). The
conversion is mainly intended for bitmap editors.
This game lib can be useful for games, but I also intend to make it
versatile enough to create other applications while not creating any
overhead.
The save functions in the ANIMATION: will most likely take a file name,
and will read the filenames sequentially numbered and encode them. I
haven't decided how to incorporate sound into them yet.
On another note, I don't yet have a plan for how Network I/O will be
structured, I want to create a generic "universal" API in which it can open
a connection via serial ports, parallel ports, TCP/IP (using a dial-up PPP
connection if neccessary)
Also not listed is the scripting support, I want to the lib to be able to
use a language engine which compiles codes rather than interpreting plain
english for speed. I would like for the scripting engine to allow the
programmer to code as little as possible. It will include a compiler so
that the end-user can create the script and the engine will compile it into
it's "native" form.
Something that is up in the air as well are the file formats, there
should be a flag to indicate the bit depth of the file. That's as much as I
have planned at the moment for all file formats. Fonts and Mouse Cursors
will be monochrome or bitmapped.
I plan to have efficient pixel precise collision detection, but I wonder
if built-in collision detection is the way to go when drawing the sprites.
An alternative is creating masks of the sprites and doing the collision
detection that way.
Oh yeah, almost forgot, I'm not gonna skip on the 3-D stuff, but since
I'm not even vaguely familiar with it, I can even design the API for now.
Game utilities will be produced with these libs to demonstrate how
versatile it is, and as an example on how to use the API.
In a previous e-mail, I spoke of "emulating" video modes, an example of
what I mean is let's say the game resolution uses Mode-X 360x240, the way
it will be programmed on the Mac is a 360x240 window in the center of a
full screen. Resolutions above 640x480 cannot be emulated unless the Mac
supports them, I don't yet have a plan for this.
Phew! Excuse me while I catch my breath =B)
--
See ya!
Orlando Llanes
Orlando Llanes (a010111t@bc.seflin.org)
HTML conversion by Lluís de Yzaguirre i Maura
Institut de Lingüística Aplicada -
Universitat "Pompeu Fabra"
e-mail: de_yza@upf.es