Glide-Tutorial - Teil I

Hier ist also Teil I meines "Programmin the 3Dfx"-Kursus. Vorab folgende Infos:
Um mitzucoden ben”tigt man den Watcom C++ Compiler (Ver.10.5a, allerdings hab
ich's auch mit Ver.10.0 �ber den alias-Befehl hingekriegt) f�r DOS oder den
MS-Visual C++ (Ver.5.0) f�r Win9x. Laut root soll es aber auch mit GNU-C unter
Linux gehen. Was man zus„tzlich ben”tigt, ist das Glide-SDK, das es kostenlos
unter www.3dfx.com gibt. Dort stehen verschiedene Pakete zur Auswahl. Zun„chst
w„hlt man zwischen Glide3 und Glide2. Ich habe mich in meinem Kursus f�r Glide2
entschieden, da man mit Glide3 (zur Zeit ?) nur unter Win9x coden kann :(
Im n„chsten Men� braucht man eigentlich nur das eigentliche SDK ziehen, da die
(auch seperat erh„ltlichen) Doku-Files bereits beiliegen. Die auch angebotenen
Utilities beinhalten z.B. ein Konvertierungs-Prog f�r Texturen (f�r mich das
wichtigste Tool), verschiedene Diagnostik-Progs und kompilierte Beispiele.
Bevor wir loslegen noch folgendes: "SST" ist die interne Bezeichnung f�r
3Dfx-Karten. Also, auf gehts mit der Initialisierung...

#include <glide.h>
#include <stdio.h>

void main(void)
{
    GrHwConfiguration  hwconfig;
    unsigned char      Str[80];
    unsigned long      v;

    if (!grSstQueryBoards(&hwconfig))
     { printf("Keine 3Dfx-Karte(n) gefunden"); return; }

    grGlideInit(); // Initialisierung

    grSstQueryHardware(&hwconfig); // Infos einholen
    printf("3Dfx-Karten: %i \n",hwconfig.num_sst);
    for (v=0; v<hwconfig.num_sst; v++)
    {
        printf("Karte %i: ",v+1);
        switch(hwconfig.SSTs[v].type)
        {
            case GR_SSTTYPE_VOODOO:
             printf("Voodoo \n");
             break;
            case GR_SSTTYPE_SST96:
             printf("SST96 (Voodoo Rush) \n");
             break;
            case GR_SSTTYPE_AT3D:
             printf("AT3D \n");
             break;
            case GR_SSTTYPE_Voodoo2:
             printf("Voodoo II \n");
             break;
            default:
             printf("Weiss nich \n");
             break;
        }
    }

    grGlideGetVersion(Str);  // Glide-Version holen
    printf("GlideVer.: %s \n",Str); // und ausgeben

    grSstSelect(0); // Karte Nr.1 waehlen

    if (!grSstWinOpen(
     NULL,                  // ganzen Bildschirm benutzen
     GR_RESOLUTION_640x480,
     GR_REFRESH_60Hz,
     GR_COLORFORMAT_ABGR,
     GR_ORIGIN_UPPER_LEFT,  // Nullpunkt ist links oben
     2,                     // Double(2) oder Triple(3) Buffering
     0))                    // Depth/Alpha-Buffering(1) oder nix(0)
     { printf("Modus nicht moeglich"); return; }

     // ...
     // Hier wuerde eigentliches Proggie stehen
     // ...

     grGlideShutdown(); // Glide beenden
}

Nun zur Erkl„rung: Mittels grSstQueryBoards() kann man sich die Nummer der
installierten 3Dfx-Karten in die Struktur GrHwConfiguration liefern lassen.
Dies ist �brigens die einzige Funktion, die man vor der Initialisierung mit
GrGlideInit() aufrufen darf. grSstQueryHardware() holt dann genauere Infos
zu den einzelnen Karten (KartenTyp, usw.). grSstSelect() kann dann eines der
Boards ausw„hlen, mit dem man arbeiten (spielen ;) will. Normalerweise steckt
nur eine 3Dfx-Karte im Rechner bzw. 2-3 Karten, die mittels SLI-Schnittstelle
miteinander verbunden sind. Beide F„lle werden aber f�r den Programmierer als
nur eine einzige Karte betrachtet, deswegen grSstSelect(0). Jetzt m”chte man
ja mal was konkretes zeichnen k”nnen und dazu muá man sich erstmal ein Fensterlein
”ffnen (grSstwinOpen()). Generell k”nnen Voodoo-Add-Ons nur den ganzen Bildschirm
zur Darstellung benutzen, deswegen wird als Handle NULL �bergeben (Voodoo Rush/Banshee
Boards k”nnen auch in Fenster rendern, allerdings will ich die Sache nich
unn”tig verkomplizieren). Weiterhin gibt man gew�nschte Aufl”sung an, die
Bild-Refresh-Rate, das FarbFormat (in unserem Fall das "Standard"-TrueColor
Format), Nullpunkt des Koordinatensystems (hier linke obere Ecke des Bildschirms),
das Buffering-System (2 f�r Double, 3 f�r Triple-Buffering) und zuguterletzt
den Depth oder Alpha-Buffer (Wenn nicht ben”tigt 0, ansonsten 1). Dieser wird
nur ben”tigt, um Polygone exakt zu "sortieren" und darzustellen bzw. um
exaktes Alpha-Blending (Transparenz) darzustellen. Zum Schluss wird dann
mittels grGlideShutdown() die Glide-API beendet.
Nachdem wir jetzt das Initialisieren abgehakt haben, zeichnen wir erstmal ein
paar einfachere Grafiken.

#include <glide.h>
#include <stdio.h>
#include <conio.h>

void PixelGlide(GrVertex Vektor, unsigned char Rot, unsigned char Gruen, unsigned char Blau, unsigned char Alpha)
{
    grConstantColorValue(Rot | Gruen<<8 | Blau<<16 | Alpha<<24);
    grDrawPoint(&Vektor);
}

void LineGlide(GrVertex Vektor1, GrVertex Vektor2, unsigned char Rot, unsigned char Gruen, unsigned char Blau, unsigned char Alpha)
{
    grConstantColorValue(Rot | Gruen<<8 | Blau<<16 | Alpha<<24);
    grDrawLine(&Vektor1,&Vektor2);
}

void main(void)
{
    GrVertex Vektor[3];

    grGlideInit();
    grSstSelect(0);
    grSstWinOpen(NULL,GR_RESOLUTION_640x480,GR_REFRESH_60Hz,GR_COLORFORMAT_ABGR,GR_ORIGIN_UPPER_LEFT,2,0);

    Vektor[0].y=Vektor[0].x=100;
    Vektor[1].y=Vektor[1].x=400;
    Vektor[2].y=Vektor[2].x=50;

    guColorCombineFunction(GR_COLORCOMBINE_CCRGB); // Farbmodus=ConstantColor

    grBufferClear(0,0,0); // GrafikBuffer loeschen

    PixelGlide(Vektor[2],255,0,0,255);
    LineGlide(Vektor[0],Vektor[1],255,255,255,255);

    grBufferSwap(1); // GrafikBuffer anzeigen

    while (!kbhit()) {}

    grGlideShutdown();
}

Das Proggie zeichnet eine weisse Linie und einen roten Punkt. Die Punkte
werden dabei durch folgende Strukturen wiedergegeben:

typedef struct {
  float  sow; // Textur-X-Koordinate
  float  tow; // Textur-Y-Koordinate
  float  oow; // f�r MipMapping
}  GrTmuVertex;

typedef struct
{
  float x, y, z; // Koordinaten (Z wird ignoriert)
  float r, g, b; // Farbwerte f�r Shading
  float ooz;     // f�r Z-Buffering
  float a;       // Alpha(Transparenz)-Wert
  float oow;     // f�r Texturen
  GrTmuVertex  tmuvtx[GLIDE_NUM_TMU];
} GrVertex;

Zun„chst interessieren uns dabei nur die Koordinaten-Werte, den Rest werde ich
dann nach und nach erl„utern. Zur�ck zu meinem Bsp-Proggie: Nach der Initalisierung
wird mit guColorCombineFunction() (sie benutzt die Low-Level-Funktion grColorCombine())
die Art der Farbberechnung gew„hlt, z.B. Konstante Farbe (Flat Shading)
(GR_COLORCOMBINE_CCRGB), Gouraud Shading (GR_COLORCOMBINE_ITRGB), Normalo-Texture-Mapping
(GR_COLORCOMBINE_DECAL_TEXTURE) usw. In unserem Falle gen�gt uns ein
stinknormaler Farbwert, den man dann mittels grConstantColorValue() setzen kann.
Bei diesem Farbmodell werden �brigens die r,g,b,a Werte in GrVertex einfach
ignoriert. Die Funktionen PixelGlide() & LineGlide() abstrahieren das Ganze,
indem sie die Farbwerte entgegen nehmen und dann selbstst„ndig setzen.
Bevor wir aber munter draufloszeichnen, m�ssen wir erstma den Grafikbuffer
l”schen. Dies geschieht mittels grBufferClear(), dem man zuerst die F�llfarbe
mitteilt (wiederum im Format BGR), dann den Standard-Alpha-Wert und den
Standard-Z-Buffer-Wert. Da wir die beiden letzteren noch nicht ben”tigen,
�bergeben wir einfach 0. Jetzt wird gezeichnet und anschliessen der GrafikBuffer
angezeigt (grBufferSwap() - �bergeben wird hier die Anzahl der Retraces, die
dazu abgewartet werden. 1 erm”glicht eine flackerfreie Darstellung, w„hrend
0 (meist) h”here Frame-Zahlen zur Folge hat).

Carsten aka Toxic Avenger/Ainc.