Mit den Draw Funktionen können 3D-Grafiken gezeichnet werden, welche nicht in Display-Listen verwaltet werden. Diese 3D-Grafiken können daher nicht mit Beleuchtung und unsichtbaren verdeckten Flächen gezeichnet werden. Ihr hauptsächlicher Zweck ist das Zeichnen und Beschriften von Achsen, Legenden, Hintergrund-Grafiken usw.
Die Draw Funktionen werden am besten in den Callback-Funktionen BeforeDrawFunc und AfterDrawFunc gerufen.
| OpenPath3D() | Öffnet den Pfad (für das Zeichnen von komplexen Flächen) |
| ClearPath3D() | Schliesst den Pfad und löscht ihn |
| Path3D() | Zeichnet den Pfad (Fläche und/oder Konturen) |
| NewPoly3D() | Löscht das interne Polygon Poly3D |
| CopyPoly3D() | Gibt eine Kopie des internen Polygons zurück |
| AddPointToPoly3D() | Fügt einen neuen 3D-Punkt am Ende des internen Polygons ein |
| DrawPoly3D() | Zeichnet das Poly3D |
| DrawPolyMarker3D() | Zeichnet das Poly3D als Marker |
| MoveTo3D() | Bewegt den Zeichenstift ohne zu zeichnen |
| LineTo3D() | Zeichnet eine Gerade von der letzten Position |
| Line3D() | Zeichnet eine Linie |
| Polygon3D() | Zeichnet oder füllt ein Polygon |
| PolygonList3D() | Zeichnet oder füllt ein Liste von Polygonen |
| VectList3D() | Zeichnet oder füllt eine JsgVect3List |
| VectListToPoly3D() | Speichert eine JsgVect3List im internen Polygon Poly3D |
| Arrow3D() | Zeichnet eine Linie mit Pfeilen oder anderen Symbolen |
| PolygonArrow3D() | Zeichnet ein Polygon mit Pfeilen oder anderen Symbolen an den Endpunkten |
| Text3D() | Zeichnet einen Text |
| GetTextBox3D() | Ermittelt die umschliessende Box für einen Text |
| Marker3D() | Zeichnet Marker |
Für weitere 3D-Draw Funktionen siehe:
Für 2D-Draw Funktionen siehe:
Hinweis: Da JsGraph3D von JsGraph abgeleitet ist, können alle JsGraph Funktionen zum Zeichnen ebenfalls verwendet werden. Dies gilt insbesondere auch für die Pfad Funktionen.
Für das Setzen von Attributen wie Fabe, Strichdicke, Textfonts usw. sowie Viewports siehe:
JsGraph3D.OpenPath3D( applyTrans )
Löscht den aktuellen Pfad und öffnet einen neuen. Alle folgenden Aufrufe von Funktionen zum Erzeugen von 3D-Linien-Elementen speichern ihre Linien im Pfad, statt sie auf den Bildschirm zu zeichnen. Auf diese Weise können beliebig viele verschiedene Linien- oder Kreis-Elemente zu einer oder mehreren Konturen zusammengesetzt werden und mit dem Aufruf von Path3D() gezeichnet und/oder gefüllt werden.
Wenn applyTrans = true ist, wird die aktuelle Objekt-Transformation Trans3D auf die Grafik-Elemente angewandt, bevor diese im Pfad gespeichert werden. Beachte, dass beim Zeichnen des Pfades mit Path3D() diese Transformation erneut angewandt wird, wenn sie vorher nicht mit ResetTrans3D() zurückgesetzt wird.
Um komplexe Flächen oder Kurven zeichnen zu können, die aus einer Kombination von verschiedenen Grafikelementen zusammengesetzt sind, müssen die Pfad-Funktionen angewandt werden. Damit ist es auch möglich, Flächen mit Löchern zu zeichnen.
Das allgemeine Vorgehen beim Zeichnen komplexer Grafikelemente über Pfade ist folgendes:
Die folgenden Funktionen können verwendet werden, um die Geometrie eines Pfades zu definieren:
JsGraph3D.ClearPath3D( )
Schliesst und löscht den Pfad. Alle Aufrufe von Zeichenfunktionen bewirken nun wieder ein direktes Zeichnen des Elementes, anstatt es im Pfad zu speichern.
JsGraph3D.Path3D( Mode, Clear )
| Mode | Beschreibung |
|---|---|
| 1 | Pfad-Kontur zeichnen |
| 2 | Pfad-Kontur füllen |
| 4 | Kontur Anfangs- und Endpunkt verbinden |
Zeichnet alle seit dem Aufruf von OpenPath3D() im Pfad gespeicherten Linienelemente und/oder füllt die so definierte Kontur mit den aktuellen Linien- und Flächen-Attributen.
Die Bits in obiger Tabelle können einfach durch Addition zu der Bitmaske von Mode zusammen gesetzt werden. Wenn also zum Beispiel der Pfad geschlossen und gefüllt werden soll und gleichzeitig auch die Kontur gezeichnet werden soll, so muss Mode = 1 + 2 + 4 gesetzt werden.
Wenn Bit 4 von Mode gesetzt ist, wird der letzte Punkt des Pfades mit dem letzten mit MoveTo3D() erzeugten Punkt verbunden. Achtung: MoveTo3D() wird auch bei Grafik-Elementen wie Polygonen, Kreisen usw. gerufen, wenn dort das Flag für An den Pfad anhängen nicht gesetzt ist!
Das Argument Clear ist nützlich, wenn zum Beispiel erst die Fläche des Pfades transparent gezeichnet werden soll, die Kontur aber undurchsichtig sein soll. In diesem Fall muss der Pfad nicht zweimal definiert werden, sondern es kann derselbe Pfad wiederverwendet werden, indem Clear = false gesetzt wird.
JsGraph3D.NewPoly3D( applyTrans )
Initialisiert Poly3D neu, um ein neues Polygon aufzubauen. Poly3D ist ein internes 3D-JsgPolygon, welches mit AddPointToPoly3D() mit Punkten gefüllt werden kann. Das Polygon kann danach mit DrawPoly3D() oder DrawPolyMarker3D() mit den aktuellen Attributen gezeichnet werden.
Wenn applyTrans = true ist, wird die 3D-Transformation auf Punkte angewandt, die mit AddPointToPoly3D() dem internen Polygon hinzugefügt werden. Beachte, dass beim Zeichnen dieselbe Transformation erneut angewandt wird, wenn sie nicht vorher mit ResetTrans3D() zurückgesetzt wird.
Das Verwenden von Poly3D ist effizienter als eine Kombination von MoveTo3D(), LineTo3D().
g.NewPoly3D();
for (var x = 0; x < x_max; x += x_inc) {
g.AddPointToPoly3D( x, y, f(x,y) );
}
g.DrawPoly3D( mode );
Auf Poly3D kann zugegriffen werden, um es z.B. mit den Funktionen JsgPolygon.Roll() und JsgPolygon.Invert() zu manipulieren.
JsGraph3D.CopyPoly3D( to, reuseArrays )
Kopiert Poly3D in das Objekt to. Wird to nicht angegeben, wir ein neues JsgPolygon Objekt erzeugt und darin eine Kopie von Poly3D zurückgegeben.
Wenn to angegeben wird, kann mit reuseArrays festgelegt werden, ob deren Arrays wiederverwendet (true) oder neu erstellt werden sollen (false). Werden sie wiederverwendet und sind kleiner als die zu kopierenden Arrays, werden sie entsprechend vergrössert. In diesem Fall haben sie am Ende die Grösse to.X.length = to.Size. Werden sie wiederverwendet, sind aber grösser als die zu kopierenden Arrays, so bleibt diese Grösse erhalten. Es muss mit to.Size ermittelt werden, wieviele Elemente effektiv kopiert worden und gültig sind!
Note: der Member JsgPolygon.Size enthält die Anzahl gültiger Punkte der Arrays JsgPolygon.X und JsgPolygon.Y. Die Arrays können grösser als JsgPolygon.Size sein!
JsgPolygon = {
X: Array of number;
Y: Array of number;
Z: Array of number;
Size: integer;
}
JsGraph3D.AddPointToPoly3D( p )
JsGraph3D.AddPointToPoly3D( x, y, z )
Fügt einen 3D-Punkt an das interne Polygon Poly3D an. Dieses kann mit NewPoly3D() initialisiert und mit DrawPoly3D() oder DrawPolyMarker3D() gezeichnet werden.
JsGraph3D.DrawPoly3D( mode, roundedEdges )
Zeichnet das Poly3D mit der Funktion Polygon3D(). Poly3D ist ein internes JsgPolygon, welches mit NewPoly3D() initialisiert und mit AddPointToPoly3D() mit Punkten gefüllt werden kann.
Der Parameter mode wird unverändert an die Funktion Polygon() weiter gereicht.
Wenn das Bit mit dem Wert 16 in mode gesetzt ist, wird das Polygon vor dem Zeichnen invertiert. Dies ist nützlich, wenn in den internen 3D-Pfad gezeichnet wird (siehe OpenPath3D()) und das Polygon ein Loch in eine Flächse stanzen soll, aber in der falschen Orientierung vorliegt.
Wenn roundedEdges = true ist, werden die Ecken und Endpunkte des Polygons gerundet, unabhängig von den aktuellen Einstellungen von LineJoin und LineCap. Letztere werden von dieser Funktion nicht verändert.
Anwendung siehe NewPoly3D().
JsGraph3D.DrawPolyMarker3D( mode, mat )
Zeichnet Poly3D mit der Funktion Marker3D(). Poly3D ist ein internes JsgPolygon, welches mit NewPoly3D() initialisiert und mit AddPointToPoly3D() mit Punkten gefüllt werden kann.
Die Parameter mode und mat werden unverändert an die Funktion Marker3D() weiter gereicht.
Wenn mat undefiniert ist, wird der Marker vor dem Zeichnen nicht zusätzlich transformiert.
JsGraph3D.MoveTo3D( Pos )
JsGraph3D.MoveTo3D( x, y, z )
Positioniert den Zeichenstift (Pen) bei den Koordinaten Pos und setzt den Zeichenstift ab (PenDown → true). Die letzte Position des Pens kann über die Properties LastX, LastY ausgelesen werden.
JsGraph3D.LineTo3D( Pos )
JsGraph3D.LineTo3D( x, y, z )
Zeichnet eine gerade Linie von der letzten Pen-Position zu den Koordinaten Pos und setzt den Pen an dieser Position ab.
Wenn vor dem Aufruf von LineTo3D() die Funktion PenUp() gerufen wurde, wird keine Linie gezeichnet, sondern nur der Pen an die Position Pos bewegt und abgesetzt (entspricht MoveTo3D()). Besser ist jedoch die Verwendung der Funktionen NewPoly(), AddPointToPoly3D() und DrawPoly(), weil effizienter.
Wenn der Pfad offen ist (siehe OpenPath()), so wird nicht gezeichnet, sondern die Linie wird im Pfad gespeichert.
JsGraph3D.Line3D( P1, P2, Append )
JsGraph3D.Line3D( x1, y1, z1, x2, y2, z2, Append )
Zeichnet eine gerade Linie vom Punkt P1 zum Punkt P2 und setzt den Pen bei P2 ab.
Wenn der Pfad offen ist (siehe OpenPath()), so wird nicht gezeichnet, sondern die Linie wird im Pfad gespeichert.
JsGraph3D.Polygon3D( Poly, Mode, RoundedEdges )
| Mode | Beschreibung |
|---|---|
| 1 | Polygonzug zeichnen |
| 2 | Polygon füllen |
| 4 | Polygon Anfangs- und Endpunkt verbinden (Polygon schliessen) |
| 8 | Polygon an bisherigen Pfad anhängen |
Wenn der Pfad offen ist (siehe OpenPath3D()), so wird nicht gezeichnet, sondern das Polygon wird im Pfad gespeichert. Durch setzen des Bit 8 in Mode kann erreicht werden, dass eine Linie vom Ende des bisher gespeicherten Pfades zum Anfang des Polygons im Pfad gespeichert wird, also das Polygon an den bisherigen Pfad angefügt wird, ohne eine neue Kontur zu beginnen.
Wenn der Pfad offen ist (siehe OpenPath3D()), so wird nicht gezeichnet, sondern das Polygon wird im Pfad gespeichert. Durch setzen des Bit 8 in Mode kann erreicht werden, dass eine Linie vom Ende des bisher gespeicherten Pfades zum Anfang des Polygons im Pfad gespeichert wird, also das Polygon an den bisherigen Pfad angefügt wird, ohne eine neue Kontur zu beginnen.
Wenn RoundedEdges = true ist, werden die Ecken und Endpunkte des Polygons gerundet, unabhängig von den aktuellen Einstellungen von LineJoin und LineCap. Letztere werden von dieser Funktion nicht verändert.
Hinweis: Das mit dieser Funktion gezeichnete Polygon ist eine 2D Projektion eines 3D Polygons. In 3D liegt das Polygon nur im Spezialfall auf einer Ebene, welche mit dem Mode Bit 2 gefüllt werden kann. Wird dieses Bit gesetzt, wird das 2D Projektions-Polygon gefüllt. Um ein Polygon auf einer 3D-Fläche zu zeichnen, verwende die Funktion PolygonOnPlane().
JsGraph3D.PolygonList3D( Polys, Mode, RoundedEdges )
Zeichnet alle Polygone von Polys mit der Function Polygon3D(). Für eine Beschreibung der Parameter Mode und RoundedEdges siehe dort.
JsGraph3D.VectList3D( VectList, Mode, RoundedEdges )
Speichert VectList im Poly3D über die Funktion VectListToPoly3D() und zeichnet das Polygon schliesslich mit DrawPoly3D().
JsGraph3D.VectListToPoly3D( VectList, newPoly )
Speichert die Koordinaten von VectList im internen Polygon Poly3D. Wenn newPoly = true ist, wird das interne Polygon zuvor gelöscht.
Das Poly3D kann mit der Funktion DrawPoly3D() oder DrawPolyMarker3D() gezeichnet werden.
JsGraph3D.Arrow3D( P1, P2, Variant, Mode, Sym1, Sym2 )
JsGraph3D.Arrow3D( x1, y1, z1, x2, y2, z2, Variant, Mode, Sym1, Sym2 )
| Variant | Beschreibung |
|---|---|
| 1 | Pfeil oder Markersymbol am Ende der Linie zeichnen |
| 2 | Pfeil oder Markersymbol am Anfang der Linie zeichnen |
| 4 | Linie nicht zeichnen nur die Smybole (falls Bit 1/2 gesetzt) |
| 8 | Linie an Enden mit Symbol um 1/2 Strichdicke verkürzen |
| Mode | Beschreibung |
|---|---|
| 1 | (Pfeil)-Markerkontur zeichnen |
| 2 | (Pfeil)-Marker füllen |
| 8 | Linie an bisherigen Pfad anhängen |
Zeichnet eine Linie mit einem Symbol (z.B. einem Pfeil) an einem oder beiden Enden. Das Symbol, die Farben und Strichdicken können mit SetMarkerAttr() gesetzt werden. Das Marker-Symbol wird in die Richtung der Linie gedreht.
Die Symbole können auch mit den Parametern Sym1 und Sym2 ausgewählt werden. Wenn nur Sym1 angegeben wird, wird Sym1 für beide Enden verwendet, abhängig von Variant.
Wenn die Linie die Länge Null hat, wird nichts gezeichnet.
JsGraph3D.PolygonArrow3D( Poly, Variant, LineMode, ArrowMode, Sym1, Sym2 )
| Variant | Beschreibung |
|---|---|
| 1 | Pfeil oder Markersymbol am Ende der Linie zeichnen |
| 2 | Pfeil oder Markersymbol am Anfang der Linie zeichnen |
| 4 | Linie nicht zeichnen nur die Smybole (falls Bit 1/2 gesetzt) |
| 8 | Linie an Enden mit Symbol um 1/2 Strichdicke verkürzen |
| LineMode | Beschreibung |
|---|---|
| 1 | Polygonkontur zeichnen |
| 2 | Polygon füllen |
| 4 | Polygon Anfangs- und Endpunkt verbinden (Polygon schliessen) |
| 8 | Linie an bisherigen Pfad anhängen |
| ArrowMode | Beschreibung |
| 1 | (Pfeil)-Markerkontur zeichnen |
| 2 | (Pfeil)-Marker füllen |
Zeichnet ein Polygon mit einem Symbol (z.B. einem Pfeil) an einem oder beiden Enden. Das Symbol, die Farben und Strichdicken können mit SetMarkerAttr() gesetzt werden. Das Marker-Symbol wird in die Richtung der Linie gedreht.
Die Symbole können auch mit den Parametern Sym1 und Sym2 ausgewählt werden. Wenn nur Sym1 angegeben wird, wird Sym1 für beide Enden verwendet, abhängig von Variant.
Wenn das Polygon aus weniger als 2 Punkten besteht, wird nichts gezeichnet. Wenn die ersten beiden Punkte identisch sind, kann kein Pfeil am Start des Polygons gezeichnet werden. Wenn die letzten beiden Punkte identisch sind, kann kein Pfeil am Ende des Polygons gezeichnet werden.
Hinweis: Das mit dieser Funktion erzeugte Polygon ist eine 2D Projektion eines 3D Polygons. In 3D liegt das Polygon nur im Spezialfall auf einer Ebene, welche mit dem Mode Bit 2 gefüllt werden kann. Wird dieses Bit gesetzt, wird das 2D Projektions-Polygon gefüllt. Um ein Polygon auf einer 3D-Fläche zu zeichnen, verwende die Funktion PolygonArrowOnPlane().
JsGraph3D.Text3D( Text, Pos, Width )
JsGraph3D.Text3D( Text, Pos, Mode )
Zeichnet einen Text in den aktuellen Text-Attributen. Die erste Aufrufvariante muss gewählt werden für TextRendering = 'html', die zweite für TextRendering = 'canvas'.
Die 3D-Text-Position wird in das 2D-Window transformiert. Die Text-Grafik selbst wird nicht 3-dimensional gezeichnet, sondern immer 2-dimensional. Über eine Objekt-Transformation kann Canvas-Text jedoch verzerrt werden. Die Text-Grösse wird in Pixel angegeben, kann jedoch durch AutoScalePix oder eine Objekt-Transformation skaliert werden.
Wenn Pos ausserhalb eines Clippinge-Bereiches liegt, wird der Text nicht gezeichnet (für TextRendering = 'canvas').
Der Text kann HTML Auszeichnungen enthalten, wenn TextRendering = 'html' ist. Der Text wird dann am Rand des Canvas umbrochen, auch wenn kein Width vorgegeben wird. Die Textbreite kann aber über Width auf eine selber vorgegebene Breite limitiert werden.
Pos wird über die Viewing-Transformation in 2D-Koordinaten (x,y) des Windows umgerechnet. (x,y) ist die horizontale bzw. vertikale Position des Text-Referenzpunktes. Die Position des Referenzpunktes relativ zur Textbox kann durch das Alignment festgelegt werden, siehe SetTextHAlign(), SetTextVAlign() und SetTextAttr(). Der Abstand des Box-Rahmens zum Text und damit des Referenzpunktes vom Text kann mit dem Text-Padding festgelegt werden (siehe SetTextPadding()), welches sich auch auf die Grösse der Textbox auswirkt (siehe GetTextBox3D()).
Die folgenden Mode Einstellungen gelten nur für TextRendering = 'canvas':
| Mode | Beschreibung |
|---|---|
| 0 | Text mit TextColor gefüllt zeichnen, keine Text-Kontur zeichnen |
| 1 | Nur Text-Kontur in der Farbe Color und der Strichdicke LineWidth zeichnen |
| 2 | Nur Text-Füllung in der BgColor zeichnen (auch Farbverläufe möglich) |
| 3 | Kombination von Mode 1 und 2 |
Wenn Mode = 3 gewählt ist, wird zuerst der Text gefüllt und danach die Kontur gezeichnet. Die Kontur liegt somit vor der Füllung. Wenn LineWidth zu dick gewählt wird, kann die Füllung von der Kontur vollständig verdeckt werden.
Hinweis: Wenn eine Objekt-Transformation definiert ist, wird die Kontur-Dicke mit dem Text transformiert. Die Strichdicke LineWidth gibt somit die Kontur-Dicke des untransformierten Textes wieder. Für ein Beispiel siehe JSG Test: AddTrans.
Über die Funktion GetTextBox3D() kann die Position und Grösse der den Text gerade umschliessenden Textbox abgefragt werden.
JsGraph3D.GetTextBox3D( Text, Pos, Width )
Berechnet die Textbox eines Textes, der mit den aktuellen Text-Attributen gezeichnet würde.
Beim TextRendering = 'html' kann der Text HTML Auszeichnungen enthalten! Die Grösse des Textes wird berechnet, nachdem der Text intern gerendert worden ist, d.h. nachdem alle HTML Auszeichnungen interpretiert worden sind.
Die berechnete Textbox kann der Funktion RectWH() zum Zeichnen der umschliessenden Textbox übergeben werden, siehe JSG Test: Html Text und JSG Test: Canvas Text.
Pos wird über die Viewing-Transformation in 2D-Koordinaten (x,y) des Windows umgerechnet. (x,y) ist die horizontale bzw. vertikale Position des Text-Referenzpunktes. Die Position des Referenzpunktes relativ zur Textbox kann durch das Alignment festgelegt werden, siehe SetTextHAlign(), SetTextVAlign() und SetTextAttr(). Der Abstand des Box-Rahmens zum Text und damit des Referenzpunktes vom Text kann mit dem Text-Padding festgelegt werden (siehe SetTextPadding()).
Die Text-Grösse wird in den Properties w und h des WorkRect zurückgegeben. WorkRect ist ein internes Objekt zum Speichern von Rechteck-Daten.
Der Text wird bei TextRendering = 'html' am Rande des Canvas umgebrochen, auch wenn keine Width vorgegeben wird. Die Textbreite kann aber über Width auf eine selber vorgegebene Breite limitiert werden.
Bei TextRendering = 'canvas' wird Text nie umgebrochen, sondern geclippt. Width hat also keine Funktion und wird ignoriert.
Hinweis: Text, der im Mode TextRendering = 'canvas' gezeichnet wird, kann über eine Objekt-Transformation verzerrt werden. Diese Funktion gibt nur die Textbox des unverzerrten Textes zurück. Wird diese Box allerdings mit derselben Transformation gezeichnet, wird sie gleich verzerrt wie der Text.
JsGraph3D.Marker3D( x, y, z, Mode, Mat )
JsGraph3D.Marker3D( Vect, Mode, Mat )
JsGraph3D.Marker3D( Poly, Mode, Mat )
| Mode | Beschreibung |
|---|---|
| 1 | Markerkontur zeichnen |
| 2 | Marker füllen |
| 4 | Marker-Kontur invertieren, um Marker-Löcher in Flächen zu erhalten |