Dokumentation

I N H A L T

Warum und weshalb? Wozu ist das den gut?

Stolz präsentiere ich euch: DIRECTX - the DLL!

Aber wozu benötigt ihr diese DLL, wenn Microsoft so oder so alle Komponenten liefert? Nun, diese Frage ist relativ einfach zu beantworten. Habt ihr euch schon einmal gefragt, wie DirectX angesprochen wird und wie alle Komponenten zusammenarbeiten? Wenn ja, dann ist euch beim näheren Betrachten des Konzepts bestimmt einiges ziemlich kompliziert erschienen. DirectX nutzt nämlich keine Klassen, um mit dem Programmierer zu "kommunizieren", was auch ziemlich logisch erscheint, da immer eine Kompatibilität nach unten gewährleistet sein sollte.

Aus diesem Grund haben sich die Entwickler auf die einheitliche COM-Schnittstelle von Microsoft geeinigt. Im Grunde stellt ein COM-Objekt eine reine Sammlung von Methoden dar. Membervariablen sind hier generell nie zu erreichen. Durch den ziemlich logischen Aufbau von COM ist ebenfalls die Abwärtskompatibilität gesichert, da jede Änderung einer DirectX-Schnittstelle in eine neue COM-Schnittstelle eingeht, was bedeutet, das beim Anpassen von zum Beispiel DirectX 5.0 auf DirectX 6.0 alle neuen Schnittstellen integriert und dem neuen Standard angepasst werden müssen. Dies hört sich ja noch sehr einfach an, aber ich möchte nicht noch das Anlegen eines solchen COM-Objektes beschreiben, da dies den Rahmen meiner Dokumentation sprengen würde.

Aber gerade dieses Anpassen an neue Versionen ist teilweise eine riesige Umstellung (manchmal sogar kompletter Programmstrukturen). Aus diesem Grund stelle ich euch diese DLL zur Verfügung. Ihr müßt euch sozusagen um nichts mehr kümmern! Sobald eine neue Version von DirectX auf dem Markt erscheint versuche ich meine DLL an den neuesten Stand anzupassen. Darüberhinaus müßt ihr euch um keine COM-Implementierung in eure Programme kümmern, sondern nur meine DLL und die entsprechenden Headerdateien einbinden und los geht's! Ohne viel Hintergrundwissen!

Im Prinzip handelt es sich bei meiner DLL um eine Vereinheitlichung aller DirectX-Komponenten. Und das alles im üblichen Klassenstil, was bedeutet, daß eine C++ Version, die Klassen innerhalb DLL's verarbeiten kann, Pflicht ist (zum Beispiel Visual C++ 6.0, was ich zur Erstellung der DLL nutze).

Was ist anders oder auch neu?

Diese Frage läßt sich nicht ohne weiteres beantworten. Einige Routinen wurden stark vereinfacht, einige komplett weggelassen, da sie den Nutzer nur verwirren und und und.

Am meisten wird euch sicherlich die Klassenstruktur und die neuen Klassen auffallen. Mit den neuen Klassen ist es zum Beispiel möglich, DirectX neu zu installieren, die aktuelle Version von DirectX zu ermitteln, Informationen über alle Treiber sammeln (es existiert quasi ein komplette Klasse zur Verwaltung von Treibern) und vieles mehr.

Was euch vielleicht auch ins Auge fällt, sind die Routinen zur Direct3D-Benutzung. Zum Beispiel das Erzeugen eines Z-Buffers wurde stark vereinfacht, aber auch das Erzeugen von Offscreen- und Primarysurfaces.

Ich habe grundsätzlich versucht die Klassen so einfach wie nur möglich zu gestalten

Ebenfalls neu ist die Klassenstruktur, welche schon desöfteren erwähnt wurde.

Diese genannten Vorteile sind noch lange nicht alle, welche meine DLL für dich interessant machen.

Was fehlt noch?

Zur Zeit sind leider aus zeitlichen Gründen noch nicht alle Komponenten von DirectX in diese DLL integriert. Nachfolgend seht Ihr eine Auflistung aller noch fehlender Komponenten, mit denen DirectX trotzdem ebenfalls arbeiten kann:

DirectDraw-Komponenten:

• IDDVideoPortContainer
• IDirectDrawColorControl
• IDirectDrawGammaControl
• IDirectDrawPalette
• IDirectDrawVideoPort

DirectSound-Komponenten:

• IDirectSound3DBuffer
• IDirectSound3DListener
• IDirectSoundCapture
• IDirectSoundCaptureBuffer
• IDirectSoundNotify

DirectMusic-Komponenten:

• IDirectMusic
• IDirectMusicBand
• IDirectMusicBuffer
• IDirectMusicChordMap
• IDirectMusicCollection
• IDirectMusicComposer
• IDirectMusicDownload
• IDirectMusicGetLoader
• IDirectMusicGraph
• IDirectMusicInstrument
• IDirectMusicLoader
• IDirectMusicObject
• IDirectMusicPerformance
• IDirectMusicPort
• IDirectMusicPortDownload
• IDirectMusicSegment
• IDirectMusicSegmentState
• IDirectMusicStyle
• IDirectMusicThru
• IDirectMusicTool
• IDirectMusicTrack
• IKsControl
• IReferenceClock

Direct3D (Immediate Mode)-Komponenten:

• IDirect3D
• IDirect3DDevice
• IDirect3DExecuteBuffer
• IDirect3DLight
• IDirect3DMaterial
• IDirect3DTexture
• IDirect3DVertexBuffer
• IDirect3DViewport

Direct3D (Retained Mode)-Komponenten:

• IDirect3DRMAnimation
• IDirect3DRMAnimationArray
• IDirect3DRMAnimationSet
• IDirect3DRMArray
• IDirect3DRMClippedVisual
• IDirect3DRMDeviceArray
• IDirect3DRMFaceArray
• IDirect3DRMFrameArray
• IDirect3DRMInterpolator
• IDirect3DRMLightArray
• IDirect3DRMMesh
• IDirect3DRMObject
• IDirect3DRMObjectArray
• IDirect3DRMPickedArray
• IDirect3DRMProgressiveMesh
• IDirect3DRMShadow
• IDirect3DRMUserVisual
• IDirect3DRMVisual
• IDirect3DRMVisualArray
• IDirect3DRMWinDevice

DirectInput-Komponenten:

• IDirectInputEffect

DirectPlay-Komponenten:

• IDirectPlay
• IDirectPlayLobby
• ... und noch einige Routinen mehr

Sonstige Komponenten:

• AutoPlay

Grundsätzliches

In dieser Dokumentation verwende ich zur Kennzeichnung folgende Farben und Formate:

• neues Kapitel
• vordefinierte Variablen aus Visual C++
• simple Beschreibung
• Methode, Routine oder Klasse
• Headerdatei
• Beschreibung von Parametern
• vordefinierte Konstanten oder Werte
• sonstige wichtige Hinweise
• nähere Spezifizierung eines Sachverhaltes

Das wichtigste, was man bei der Programmierung von DirectX wissen sollte ist, daß ALLE Routinen, die aufgerufen werden einen Rückgabewert zurückliefern. Bei herkömmlichen DirectX-Routinen werden HRESULT-Werte zurückgeliefert, was folgendes bedeutet:

• negative Werte: irgendein Fehler trat bei der Ausführung der Routine auf
• 0: alles verlief ohne Probleme
• positive Werte: keine Probleme traten auf (erweiterte Angaben zum "Erfolg")

Bei Routinen innerhalb meiner DLL müssen die Rückgabewerte unterschiedlich betrachtet werden. Entweder liefert eine Methode einen Pointer auf ein Objekt zurück, oder, ähnlich wie bei den normalen DirectX-Routinen, einen int-Wert. Hier sehen Sie die verschiedenen Varianten erklärt:

1. Bei Pointern:
   • NULL: irgendein Fehler trat bei der Ausführung der Routine auf (meist zeigt selbige Routine schon eine Errorbox an)
   • Adresse: alles verlief ohne Probleme, dh. man kann sich auf den zurückgelieferten Zeiger verlassen.
2. Bei int-Werten:
   • negative Werte: irgendein Fehler trat bei der Ausführung der Routine auf (z. Zt. meist DXDLL_INTERNALERROR)
   • 0: alles verlief ohne Probleme
   • positive Werte: keine Probleme traten auf (noch nirgends integriert)

Am besten, man überprüft bei int- bzw. HRESULT-Werten das Rückgabergebnis per FAILED(x)- oder SUCCEEDED(x)-Makro aus DirectX. Vorsicht ist bei DirectX sowieso geboten, was bedeutet, daß generell JEDER Rückgabewert geprüft werden sollte.

DirectDraw und die DLL

Wie ist das mit DirectSound?

Let's play some music: DirectMusic

Wie arbeitet DirectInput?

Ziemlich komplex: Direct3D (Retained Mode)

Auch nicht viel einfacher: Direct3D (Immediate Mode)

Lassen wir PC's miteinander "reden": DirectPlay

neue Komponenten, die DirectX erweitern

Arbeiten mit LOG-Dateien mittels der DLL

Das arbeiten mit LOG-Dateien unter DirectX ist nicht direkt vorgesehen, aber ich habe versucht, Routinen zu entwickeln, welche das Anlegen, das Verändern usw. von LOG-Dateien so einfach, wie nur möglich machen sollen.

Folgende Routinen sind dafür vorgesehen:

CreateLOGFile:

Headerdatei: TOOLS.H

Es existieren zwei verschieden Varianten dieser Routine:

• int CreateLOGFile()
• int CreateLOGFile(LPCSTR lpcFilename)

lpcFilename ... Dateiname der LOG-Datei

Beide Routinen erzeugen jeweils eine LOG-Datei. Falls eine Datei mit demselben Namen schon existiert, so wird diese überschrieben. Bei ersterer Routine wird standardmäßig eine LOG-Datei auf Laufwerk "C:" mit dem Namen "DIRECTX.LOG" angelegt.

CloseLOGFile:

Headerdatei: TOOLS.H

• int CloseLOGFile()

Diese Routine schließt die aktuelle LOG-Datei.

WriteLOGLine:

Headerdatei: TOOLS.H

• int WriteLOGLine(LPCSTR lpcStr)

lpcStr ... String, der in LOG-Datei geschrieben werden soll

Mit dieser Routine ist es möglich, einen beliebigen String in eine Datei zu schreiben.

WriteLOGHResult:

Headerdatei: TOOLS.H

• int WriteLOGHResult(HRESULT hres)

hres ... Rückgabewert einer beliebigen DirectX-Routine, der in LOG-Datei geschrieben werden soll

Hierdurch wird es relativ einfach möglich, den Rückgabewert einer Routine aus DirectX in die LOG-Datei zu schreiben. Dadurch wird das analysieren eines Fehlers in einer Fullscreen-Anwendung sehr viel einfacher.
Zur näheren Analyse des Fehlers ist es möglich das von mir entwickelte Tool "DXError" einzusetzen. Hier ist es möglich, den gelieferten Errorcode einzugeben und die verwendete Komponente einzustellen und daraus wird der richtige Errorcode ermittelt, welcher in den dementsprechenden Headerdateien verwendet wird.

WriteLOGEndSection:

Headerdatei: TOOLS.H

• int WriteLOGEndSection()

Diese Routine ist zur optischen Trennung verschiedener Ausgaben in die LOG-Datei vorgesehen. Sie macht nichts anderes, als eine Begrenzungslinie an der aktuellen Position innerhalb der LOG-Datei zu ziehen. Diese besteht aus mehreren "="-Zeichen.

WriteLOGEndSection:

Headerdatei: TOOLS.H

• int WriteLOGSoftEndSection()

Diese Routine ist ebenfalls zur optischen Trennung verschiedener Ausgaben in die LOG-Datei vorgesehen. Genauso, wie WriteLOGEndSection zieht diese eine Begrenzungslinie an der aktuellen Position innerhalb der LOG-Datei. Diese besteht jedoch nicht aus "="-Zeichen, sondern aus mehreren "-"-Zeichen.

Sonstige wichtige Routinen der DLL

Dieser Teil der Dokumentation beschäftigt sich mit den restlichen vier Routinen, die mit der DLL verwendet werden können. Folgende aufgelistete Routinen stehen zur vollständigen Verfügung:

Fail:

Headerdatei: TOOLS.H

• int Fail(HWND hWindow, char* Msg)

HWND ... Fensterhandle, zu dem Messagebox gehören soll (= NULL, falls Desktop)
Msg ... String, der ausgegeben werden soll

Diese Routine zeigt eine Messagebox mit dem vorgegebenen Text an und liefert DXDLL_INTERNALERROR zurück

FileExists:

Headerdatei: TOOLS.H

• bool FileExists(LPCSTR pFilename)

pFilename ... Dateiname der Datei, deren Vorhandensein überprüft werden soll

Hiermit wird das Vorhandensein einer Datei überprüft. Existiert die Datei, so liefert sie true als Ergebnis, ansonsten false.

Potenz:

Headerdatei: TOOLS.H

• double Potenz(double dZahl, int iExponent)

dZahl ... Zahl, die potenziert werden soll
iExponent ... so oft soll Zahl mit sich selbst multipliziert werden

Multipliziert angegebene Zahl x-mal miteinander und liefert 0, falls Fehler oder das korrekte Ergebnis.

round:

Headerdatei: TOOLS.H

• double round(double dZahl, int iStellen)

dZahl ... Zahl, die gerundet werden soll
iStellen ... auf diese Stelle soll Zahl gerundet werden

Rundet angegebene Zahl auf angegebene Stelle und liefert 0 bei Fehler, ansonsten das korrekte Ergebnis.

Strukturen der DLL

Wer ist für dieses Produkt verantwortlich?

Die aktuelle Version der DLL ist: 0.40b (Stand 30.03.1999)
Die DLL verwendet zur Zeit MS DirectX 6.1.

Programmierer: Patrick Morgenstern  eMail: coder@ariaci.de

Mehr zum Programmierer findet Ihr hier!

This product is (c) by Patrick Morgenstern
DirectX 6.1 SDK(r) is a trademark of Microsoft Corporation.

Achtet bei Softwarekauf auf dieses Zeichen: