README

   1 QDGDF README
   2 ============
   3
   4  QDGDF - Quick and Dirty Game Development Framework
   5  Copyright (C) 1997-2011 Angel Ortega <angel@triptico.com>
   6  Home Page: http://triptico.com/software/qdgdf.html
   7
   8 This software is GPL. NO WARRANTY. See file 'COPYING' for details.
   9
  10 Intro
  11 -----
  12
  13 QDGDF stands for Quick and Dirty Game Development Framework, and it's a
  14 set of libraries designed to allow fast development of games under a
  15 variety of systems. Its main goal is to show a platform-independent,
  16 simple, consistent game programming interface to several platforms, but
  17 keeping it small enough to be included (embedded) with each gaming project
  18 (and not as a separately installable package).
  19
  20 QDGDF has two libraries: qdgdfv (Video) and qdgdfa (Audio) that can be used
  21 independently from each other. They are built as static libraries only.
  22
  23 qdgdfv
  24 ------
  25
  26 qdgdfv (Video library) implements a virtual screen (framebuffer). Though
  27 this virtual screen uses 8 bit depth (256 color) mode, the real screen can
  28 use any depth. The supported systems as of the current version are:
  29
  30  * X11 Window System in 8, 15, 16, 24 and 32 pixel depths.
  31  * MS Windows DirectX.
  32  * DJGPP.
  33  * Linux SVGALIB.
  34
  35 As it is an internal 256 color mode, a palette must be provided. A
  36 highly optimized one is included if you don't supply it. Also, the
  37 necessary functions to load 256-color PCX files (they must all use the
  38 same palette) are also provided. Later qdgdfv versions won't be so
  39 palette-dependent and will provide three virtual screens for real 24
  40 bit RGB operation.
  41
  42 This library also implements basic keyboard input (sorry, no joystick nor
  43 mouse in this version), filling a short set of variables with current
  44 cursor key (and some modifiers) status.
  45
  46 In X11, windowed mode is always used, and both horizontal and vertical
  47 sizes can be set to any reasonable value. A special double-mode flag can
  48 also be activated, in case of a huge screen resolution with tiny pixels is
  49 active.
  50
  51 Full screen mode is always used under win32. As it uses DirectX, the screen
  52 dimensions are limited to usual resolutions (640x480, 800x600, etc.). Not
  53 all of them are available in all hardware, just experiment. If the resolution
  54 you ask for isn't available but the double one does, double-mode is
  55 automaticly activated (say, if you ask for an unavailable 320x200, 640x400
  56 double-mode can be used). So, remember to check the contents of screen's x
  57 and y size after initialization, as they could have changed from what you
  58 had set.
  59
  60 DJGPP and SVGALIB versions use only fullscreen 320x200 resolutions modes.
  61
  62 qdgdfa
  63 ------
  64
  65 qdgdfa (Audio library) lets you launch previously loaded sounds
  66 simultaneously. It can use 8 and/or 16 bit mono sounds in 8 and/or 16
  67 bit mono/stereo soundcards at a 11025 sampling rate, providing the necessary
  68 conversions. Though sounds must be mono (i.e., they only have one channel),
  69 they are played in stereo, so it's possible to set the pan in play time to
  70 whatever you want.
  71
  72 Wav files (.wav) are supported (remember, sampled at 11025 Hz). 16 bit mode
  73 will be used unless explicitly requested or hardware limited. You don't have
  74 to take the endianess of the CPU into account as sounds are byte-swapped if
  75 needed.
  76
  77 In Linux systems, qdgdfa uses the OSS Free interface (no ALSA by now,
  78 sorry). A new process is forked to attend the sound mixing; it
  79 communicates with the main one via a pipe. It can also use the esd
  80 (enlightened sound daemon); see below on how to compile support for it.
  81
  82 In MS Windows, DirectSound is used.
  83
  84 Compilation, installation and usage
  85 -----------------------------------
  86
  87 To include QDGDF in your project, just uncompress the QDGDF sources in
  88 a subdirectory below it, and call it qdgdf. System specific instructions
  89 follow.
  90
  91 UNIX/Linux
  92 ~~~~~~~~~~
  93
  94 Under UNIX systems, cd to qdgdf/ and type
  95
  96  ./config.sh
  97  make
  98
  99 If you have a usable build system for X11 and / or SVGALIB, support for them
 100 will be automatically included. If both are, the X11 driver will be tried
 101 first on startup; if no connection to an X server is possible, the SVGALIB
 102 will be tried instead.
 103
 104 Once built, you'll have two libraries, libqdgdfv.a and libqdgdfa.a. Include
 105 the qdgdf_video.h and qdgdf_audio.h headers in your C code and link against
 106 that libraries. Two files, called 'config.cflags' and 'config.ldflags' will
 107 contain the necessary compiler and linker directives for your program to
 108 be built, respectively.
 109
 110 So, for example, if your game is in game.c, build it as:
 111
 112   $CC game.c -Iqdgdf -Lqdgdf `cat qdgdf/config.cflags` \
 113         `cat qdgdf/config.ldflags` -o game
 114
 115 See README.mingw32 to know how to build the libraries using the mingw32
 116 cross-compiler.
 117
 118 MS Windows DirectX
 119 ~~~~~~~~~~~~~~~~~~
 120
 121 To build the libraries under MS Windows, you'll need Borland C. You can
 122 download Borland C's command line tools for free from their web site.
 123 Once installed, cd to qdgdf/ and run the .BAT file:
 124
 125   buildbcc.bat
 126
 127 And you'll end up with two libraries, qdgdfv.lib and qdgdfa.lib. Include
 128 the qdgdf_video.h and qdgdf_audio.h headers in your C code and link against
 129 that libraries. You'll also need the DirectX libraries, of course. They are
 130 called ddraw.lib and dsound.lib and are included with Borland C. So, compile
 131 your program as follow:
 132
 133   bcc32 -tW -Iqdgdf -Lqdgdf game.c ddraw.lib dsound.lib qdgdfv.lib qdgdfa.lib
 134
 135 DJGPP
 136 ~~~~~
 137
 138 To build the libraries with the DJGPP compiler, just cd to qdgdf/ and run
 139 the .BAT file:
 140
 141   builddjg.bat
 142
 143 And you'll end up with two libraries, libqdgdfv.a and libqdgdfa.a. See the
 144 UNIX/Linux section for details.
 145
 146 Building a cross-platform game in one evening
 147 ---------------------------------------------
 148
 149 Think a plot for your game. All game plots suck, so don't treat
 150 yourself too badly here.
 151
 152 In your favorite bitmap editor tool, draw the characters / enemies /
 153 objects / decorations. Set all of them to the provided palette, and
 154 save them as 256 color PCX files.
 155
 156 Drag the Internet looking for appropriate sounds for jumping / dying /
 157 shooting / whatever. Convert all of them to 11025 Hz using your
 158 favorite sound conversion tool.
 159
 160 Open your text editor and start to type C code:
 161
 162         #ifdef __WIN32__
 163         #include <windows.h>
 164         #endif
 165
 166         #include <stdio.h>
 167         #include "qdgdf_video.h"
 168         #include "qdgdf_audio.h"
 169
 170 You won't be too much surprised here; the usual mumbo-jumbo, and the
 171 qdgdf header files. The #ifdef __WIN32__ is necessary for WinMain.
 172
 173         #ifdef __WIN32__
 174         int __stdcall WinMain(HINSTANCE hi, HINSTANCE hpi, LPSTR cmd, int cm)
 175         {
 176                 _qdgdfv_additional_int_info=(int)hi;
 177         #else
 178         int main(void)
 179         {
 180         #endif
 181
 182 will work. You'll notice a strange thing: that (int)hi assignment.
 183 As you'll suppose, that WinMain parameter is necessary for DirectDraw
 184 objects. Blame Microsoft.
 185
 186 Before QDGDF startup, you need to set up some values. Here there
 187 you have some of them:
 188
 189         /* use 16 bit sound whenever possible */
 190         _qdgdfa_16_bit=1;
 191         /* use 320 x 200 resolution */
 192         _qdgdfv_screen_x_size=320;
 193         _qdgdfv_screen_y_size=200;
 194         /* the clear color */
 195         _qdgdfv_clear_color=0;
 196         /* window title(s) */
 197         strcpy(_qdgdfv_window_title, "awesome qdgdf based game");
 198         strcpy(_qdgdfa_window_title,_qdgdfv_window_title);
 199
 200 And then, the real startup:
 201
 202         qdgdfa_startup();
 203         qdgdfv_startup();
 204
 205 Wow. You'll ready for doing game things; let's start another step.
 206
 207 Of course, you need to load the bitmaps and sounds you have ready for
 208 that game. Load the pictures with:
 209
 210         unsigned char good_guy[16*16];
 211         unsigned char bad_guy[16*16];
 212         unsigned char background[512*300];
 213
 214         qdgdfv_load_pcx(good_guy,"good_guy.pcx",16*16);
 215         qdgdfv_load_pcx(bad_guy,"bad_guy.pcx",16*16);
 216         qdgdfv_load_pcx(background,"the_deep_space_background.pcx",512*300);
 217
 218 Loading sounds isn't harder:
 219
 220         int shoot_sound, player_die_sound, evil_laugh_sound;
 221
 222         shoot_sound=qdgdfa_load_sound("gun_shot.wav");
 223         player_die_sound=qdgdfa_load_sound("aaaarrrgh.wav");
 224         evil_laugh_sound=qdgdfa_load_sound("muaaahahaha.wav");
 225
 226 Let's start to loop:
 227
 228         /* while player is alive (this variables are yours) */
 229         while(_player_alive && !_aborted)
 230         {
 231                 /* clear the virtual screen */
 232                 qdgdfv_clear_virtual_screen();
 233
 234                 /* poll the input system */
 235                 qdgdfv_input_poll();
 236
 237                 /* test the keys that were hit */
 238                 if(_qdgdfv_key_escape)
 239                         _aborted=1;
 240
 241                 /* do whatever you must;
 242                    _some_variable and _do_fire() are yours */
 243                 if(_qdgdfv_key_left)
 244                         _some_variable--;
 245                 if(_qdgdfv_key_right)
 246                         _some_variable++;
 247                 if(_qdgdfv_key_control_l)
 248                         _do_fire();
 249
 250                 /* fill the virtual screen with whatever you want
 251                    (preferably the good_guy, the bad_guy, etc.) */
 252                 /* ... */
 253
 254                 /* finally, dump it out over the real screen */
 255                 qdgdfv_dump_virtual_screen();
 256         }
 257
 258         /* game over, man!; exit cleanly */
 259
 260         qdgdfv_shutdown();
 261         qdgdfa_shutdown();
 262
 263         return(0);
 264
 265 The rest of steps are for you to write your game. Filling the gaps and
 266 writing a non-stinking AI and plot are left as an exercise to the reader (you).
 267
 268 Misc Notes
 269 ----------
 270
 271  * You can pick the QDGDF palette from the bitmap in bola.pcx ('bola' is
 272    the main character from a very old, never finished game, now
 273    the official logo for the Minimum Profit text editor).
 274  * This is a quick and dirty work, but you can bet that it works.
 275
 276 ----
 277 Angel Ortega - http://www.triptico.com