OMSI Plugin Framework III - Versionsgeschichte

Holmexx: einen einzigen Satz verbessert

2012-11-24T17:55:32Z

einen einzigen Satz verbessert

Holmexx am 23. November 2012 um 21:47 Uhr

2012-11-23T21:47:23Z

Holmexx am 23. November 2012 um 21:37 Uhr

2012-11-23T21:37:49Z

Holmexx: Die Seite wurde neu angelegt: „== Die Plugin-Schnittstelle == === Allgemeines === In diesem Kapitel werde ich die Arbeitsweise der Plugin-Schnittstelle des OMSI noch etwas tiefer beleuchten, …“

2012-11-23T15:47:24Z

Die Seite wurde neu angelegt: „== Die Plugin-Schnittstelle == === Allgemeines === In diesem Kapitel werde ich die Arbeitsweise der Plugin-Schnittstelle des OMSI noch etwas tiefer beleuchten, …“

Neue Seite

== Die Plugin-Schnittstelle ==

=== Allgemeines ===

In diesem Kapitel werde ich die Arbeitsweise der Plugin-Schnittstelle des OMSI noch etwas tiefer beleuchten, vor allem mehr im Zusammenhang mit
der Programmiersprache C++.

Das allgemeine Prinzip wird ja bereits in [[Plug-in-Schnittstelle|diesem Artikel]] erklärt. Auch wenn das Plugin in C++ programmiert wird, ändert
sich an den grundlegenden Dingen nichts. Lediglich der im Artikel beschriebene Weg, ein Formular zu öffnen, ist absolut Delphi-typisch und in C++
so nicht möglich. Der Parameter, der beim Aufruf der Funktion '''''Start''''' mitgegeben wird, ist nicht nur einfach ein 'Delphi'-Parameter, er ist
auch noch von der verwendeten Delphi-Version abhängig. Deshalb wird dieser Parameter im '''''OMSI Plugin Framework''''' nicht benutzt, auch wenn
darüber ein Zugriff auf das Hauptfenster-Handle in C++ möglich wäre.

=== Lebenszyklus eines Plugins ===

Es gibt zwei Möglichkeiten, DLLs in ein Programm einzubinden. Die erste Möglichkeit ist, die DLL schon während der Programmierung sozusagen fest mit
dem Programm zu verbinden. Diese DLLs müssen beim Programmstart vorhanden sein, sonst schlägt das Starten des Programmes fehl. Diese Möglichkeit benutzt
man im z.B. für die System-DLLs (und davon hat Windows eine reichliche Anzahl). In der Natur eines Plugins liegt es aber, dass es ganz einfach gar nicht
da sein kann. Also scheidet die eben erwähnte Möglichkeit zum Einbinden einer DLL aus. Deshalb macht der OMSI von der zweiten Möglichkeit Gebrauch. Ein
Programm kann über den Aufruf einer Systemfunktion '''''LoadLibrary''''' zu jeder beliebigen Zeit DLLs nachladen. '''''LoadLibrary''''' sucht aber nur
(im Wesentlichen) an drei Stellen automatisch nach einer DLL: in dem Ordner, in dem sich auch das Programm selbst befindet, im '''''Windows'''''-Ordner
und im '''''Windows\system(32)'''''-Ordner. Wenn sie dort nicht fündig wird, liefert die Funktion einen Fehler zurück. Also muss der OMSI ''wissen'', wo
sich die DLL befindet. Dafür wurde der Ordner <i><OMSI_Installationsordner></i>\'''''plugins''''' festgelegt.

Plugin-DLLs werden bereits kurz nach dem Start des OMSI geladen und ihre '''''Start'''''-Funktion aufgerufen. Wenn nach dem Start des OMSI das erste mal
der Auswahldialog für die Karte, gespeichertes Spiel usw. erscheint, ist das Plugin schon aktiviert, aber im Ruhezustand. Zu diesem Zeitpunkt existiert
noch keine Karte und kein Bus, da der Spieler ja die Karte erst noch auswählen muss. Auch nachdem der Spieler eine Karte ausgwählt und der OMSI Diese
geladen hat, schläft das Plugin immer noch weiter. Es erwacht erst, sobald der OMSI den Bus des Spielers geladen hat. Solange ein Spieler-Bus existiert
werden nun die '''''AccessVariable'''''- und '''''AccessTrigger'''''-Funktionen durch den OMSI aufgerufen.

Kurz vor Beendigung des OMSI ruft Dieser noch die Funktion '''''Finalize''''' auf. Damit endet der Lebenszyklus des Plugins.

=== Die Funktion '''Start''' ===

Die Funktion '''''Start''''' wird (wie im vorherigen Abschnitt beschrieben) einmalig vor Beginn des eigentlichen Spiels durch den OMSI aufgerufen und ist
daher nicht zeitkritisch. In die Funktion '''''Start''''' gehören alle grundlegenden Initialisierungen, die Dein Plugin benötigt. Wenn man mal davon absieht,
dass sich die Ladezeit des OMSI verlängert, hast Du hier Zeit, die Dinge zu tun, die Du als Vorbereitung für die eigentliche Arbeit im Plugin benötigst.

Wie im Abschnitt [[#Allgemeines]] bereits erläutert, solltest Du es vermeiden, den Parameter dieser Funktion zu verwenden. Falls Du sehr daran interessiert
bist, an das Handle des Hauptfensters zu gelangen, sei hier ganz grob der Weg beschrieben, wie das möglich wäre: Du müsstest Dir zunächst die technische
Dokumentation der Komponente '''''TComponent''''' (bzw. '''''TForm''''', denn eine '''''TForm''''' ist dieser Parameter tatsächlich) passend zu der
Delphi-Version besorgen, mit der der OMSI programmiert wurde. Anhand der Dokumentation kannst du dann die Klasse in C++ ''nachbauen''. Wenn Du das geschafft
hast, kannst Du nun den Parameter verwenden. Das Ganze ist - wie gesagt - durchaus möglich, aber mehr ein Hack als vernünftige Programmierung.

=== Die Funktion '''AccessVariable''' ===

Solange der Spieler über einen Bus verfügt, werden in jedem Frame alle in der .opl-Datei deklarierten Variablen nacheinander genau in der Reihenfolge der
Deklaration über diese Funktion an Dein Plugin zur Bearbeitung übergeben.

Der erste Parameter ist dabei der Index der Variablen in der .opl-Datei. Die Zuordnung, welche Variable was ist, musst Du in Deinem Plugin selbst wieder
herstellen. Der zweite Parameter ist ein Zeiger auf einen '''''float'''''-Wert. Das ist der aktuelle Wert der Variablen. Der Wert wird deshalb als Zeigertyp
übergeben, damit Du den Wert im Plugin auch ändern kannst. Der dritte Parameter schließlich ist ein Zeiger auf einen '''''bool'''''-Wert. Darüber gibst Du dem
OMSI Rückmeldung, ob Du den Inhalt der Variablen verändert hast. Wenn Du die Variable nur lesend benutzt, brauchst Du nichts weiter tun. Der Wert, auf den
dieser Zeiger zeigt, ist immer mit '''''false''''' vorbelegt.

Dadurch, das diese Funktion für '''''jede''''' Variable in '''''jedem''''' Frame aufgerufen wird, ergibt sich, das diese Funktion äußerst zeitkritisch ist. Über
die Ausführungsdauer der Funktion in Deinem Plugin beeinflusst Du direkt die Framerate des OMSI (siehe [[OMSI_Plugin_Framework_II#Die_Regel_Nummer_1|Regel Nummer 1]]).

=== Die Funktion '''AccessTrigger''' ===

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla lacus metus, lacinia at tempus vitae, ultrices eget diam. Phasellus eu interdum nisi. Etiam
viverra dui sed lectus tristique at semper risus faucibus. Sed vitae neque vel libero vulputate tempus vel non est. Suspendisse viverra justo vitae enim
iaculis consectetur. Aenean vulputate neque a metus semper vel sollicitudin erat lacinia. Integer volutpat mi vitae lectus tempus faucibus. Aenean rhoncus,
eros eu pulvinar eleifend, ante leo placerat est, quis blandit ante risus non nisl. Praesent bibendum lorem ut felis pretium bibendum. Vestibulum a velit quam.
Donec semper tellus in nisi gravida iaculis. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Vivamus nibh nibh, sodales
non commodo pellentesque, pharetra et lacus. Nam leo urna, tempus vel mattis id, pretium vitae turpis. Vestibulum ante ipsum primis in faucibus orci luctus et
ultrices posuere cubilia Curae; Donec nulla ipsum, tristique vitae vehicula in, sodales sit amet turpis.

=== Die Funktion '''Finalize''' ===

Die Funktion '''''Finalize''''' wird einmalig beim Beenden des OMSI aufgerufen und ist nicht zeitkritisch. In diese Funktion gehören alle Aufräumarbeiten, die in
Deinem Plugin nötig sind.

----
{|style="width:100%"
|-
|style="width:33%" |[[OMSI Plugin Framework II|[zum Kapitel 2]]]
|align="center" |[[OMSI Plugin Framework|[zum Inhaltsverzeichnis]]]
|style="width:33%" align="right" |[[OMSI Plugin Framework IV|[zum Kapitel 4]]]
|-
|}

@@ Zeile 69: / Zeile 69: @@
 Ähnlich wie bei der Funktion '''''AccessVariable''''' wird auch '''''AccessTrigger''''' in jedem Frame für jeden in der .opl-Datei deklarierten Trigger genau in der Reihenfolge der Deklaration aufgerufen.
-Der erste Parameter ist dabei der Index des Triggers in der .opl-Datei. Die Zuordnung, welcher Trigger wer ist, musst Du in Deinem Plugin selbst wieder herstellen. Der zweite Parameter ist ein Zeiger auf einen '''''bool'''''-Wert. Darüber gibst Du dem OMSI Rückmeldung, ob er den Trigger auslösen soll oder nicht. Wenn Du den Trigger nicht auslösen möchtest, brauchst Du nichts weiter tun. Der Wert, auf den dieser Zeiger zeigt, ist immer mit '''''false''''' vorbelegt.
+Der erste Parameter ist dabei der Index des Triggers in der .opl-Datei. Die Zuordnung, welcher Trigger wer ist, musst Du in Deinem Plugin selbst wieder herstellen. Der zweite Parameter ist ein Zeiger auf einen '''''bool'''''-Wert. Darüber gibst Du dem OMSI Rückmeldung, ob er den Trigger auslösen soll oder nicht. Wenn der Trigger nicht ausgelöst werden soll, brauchst Du nichts weiter tun. Der Wert, auf den dieser Zeiger zeigt, ist immer mit '''''false''''' vorbelegt.
 Genau wie '''''AccessVariable''''' ist auch diese Funktion zeitkritisch, da sie für '''''jeden''''' Trigger in '''''jedem''''' Frame aufgerufen.

@@ Zeile 3: / Zeile 3: @@
 === Allgemeines ===
-In diesem Kapitel werde ich die Arbeitsweise der Plugin-Schnittstelle des OMSI noch etwas tiefer beleuchten, vor allem mehr im Zusammenhang mit
+In diesem Kapitel werde ich die Arbeitsweise der Plugin-Schnittstelle des OMSI noch etwas tiefer beleuchten, vor allem mehr im Zusammenhang mit der Programmiersprache C++.
-Das allgemeine Prinzip wird ja bereits in [[Plug-in-Schnittstelle|diesem Artikel]] erklärt. Auch wenn das Plugin in C++ programmiert wird, ändert
+Das allgemeine Prinzip wird ja bereits in [[Plug-in-Schnittstelle|diesem Artikel]] erklärt. Auch wenn das Plugin in C++ programmiert wird, ändert sich an den grundlegenden Dingen nichts. Lediglich der im Artikel beschriebene Weg, ein Formular zu öffnen, ist absolut Delphi-typisch und in C++ so nicht möglich. Der Parameter, der beim Aufruf der Funktion '''''Start''''' mitgegeben wird, ist nicht nur einfach ein 'Delphi'-Parameter, er ist auch noch von der verwendeten Delphi-Version abhängig. Deshalb wird dieser Parameter im '''''OMSI Plugin Framework''''' nicht benutzt, auch wenn darüber ein Zugriff auf das Hauptfenster-Handle in C++ möglich wäre.
-=== Lebenszyklus eines Plugins ===
+[[Datei:Lifecycle.jpg|200px|thumb|right|Lebenszyklus eines Plugins]]
-[[Datei:Lifecycle.jpg|200px|thumb|right|Lebenszyklus eines Plugins]]
+Es gibt zwei Möglichkeiten, DLLs in ein Programm einzubinden. Die erste Möglichkeit ist, die DLL schon während der Programmierung sozusagen fest mit dem Programm zu verbinden. Diese DLLs müssen beim Programmstart vorhanden sein, sonst schlägt das Starten des Programmes fehl. Diese Möglichkeit benutzt man im z.B. für die System-DLLs. In der Natur eines Plugins liegt es aber, dass es ganz einfach gar nicht da sein kann. Also scheidet die eben erwähnte Möglichkeit zum Einbinden einer DLL aus. Deshalb macht der OMSI von der zweiten Möglichkeit Gebrauch. Ein Programm kann über den Aufruf einer Systemfunktion '''''LoadLibrary''''' zu jeder beliebigen Zeit DLLs nachladen. '''''LoadLibrary''''' sucht aber nur (im Wesentlichen) an drei Stellen automatisch nach einer DLL: in dem Ordner, in dem sich auch das Programm selbst befindet, im '''''Windows'''''-Ordner und im '''''Windows\system(32)'''''-Ordner. Wenn sie dort nicht fündig wird, liefert die Funktion einen Fehler zurück. Also muss der OMSI ''wissen'', wo sich die DLL befindet. Dafür wurde der Ordner <i>&lt;OMSI_Installationsordner&gt;</i>\'''''plugins''''' festgelegt.
-Es gibt zwei Möglichkeiten, DLLs in ein Programm einzubinden. Die erste Möglichkeit ist, die DLL schon während der Programmierung sozusagen fest mit
+=== Lebenszyklus eines Plugins ===
-Plugin-DLLs werden bereits kurz nach dem Start des OMSI geladen und ihre '''''Start'''''-Funktion aufgerufen. Wenn nach dem Start des OMSI das erste mal
+Plugin-DLLs werden bereits kurz nach dem Start des OMSI geladen und ihre '''''Start'''''-Funktion aufgerufen. Wenn nach dem Start des OMSI das erste mal der Auswahldialog für die Karte, gespeichertes Spiel usw. erscheint, ist das Plugin schon aktiviert, aber im Ruhezustand. Zu diesem Zeitpunkt existiert noch keine Karte und kein Bus, da der Spieler ja die Karte erst noch auswählen muss. Auch nachdem der Spieler eine Karte ausgwählt und der OMSI Diese geladen hat, schläft das Plugin immer noch weiter. Es erwacht erst, sobald der OMSI den Bus des Spielers geladen hat. Solange ein Spieler-Bus existiert werden nun die '''''AccessVariable'''''- und '''''AccessTrigger'''''-Funktionen durch den OMSI aufgerufen.
 Kurz vor Beendigung des OMSI ruft Dieser noch die Funktion '''''Finalize''''' auf. Damit endet der Lebenszyklus des Plugins.
@@ Zeile 45: / Zeile 29: @@
 </code>
-Die Funktion '''''Start''''' wird (wie im vorherigen Abschnitt beschrieben) einmalig vor Beginn des eigentlichen Spiels durch den OMSI aufgerufen und ist
+Die Funktion '''''Start''''' wird (wie im vorherigen Abschnitt beschrieben) einmalig vor Beginn des eigentlichen Spiels durch den OMSI aufgerufen und ist daher nicht zeitkritisch. In die Funktion '''''Start''''' gehören alle grundlegenden Initialisierungen, die Dein Plugin benötigt. Wenn man mal davon absieht, dass sich die Ladezeit des OMSI verlängert, hast Du hier Zeit, die Dinge zu tun, die Du als Vorbereitung für die eigentliche Arbeit im Plugin benötigst.
-Wie im Abschnitt [[#Allgemeines|Allgemeines]] bereits erläutert, solltest Du es vermeiden, den Parameter dieser Funktion zu verwenden. Falls Du sehr daran
+Wie im Abschnitt [[#Allgemeines|Allgemeines]] bereits erläutert, solltest Du es vermeiden, den Parameter dieser Funktion zu verwenden. Falls Du sehr daran interessiert bist, an das Handle des Hauptfensters zu gelangen, sei hier ganz grob der Weg beschrieben, wie das möglich wäre: Du müsstest Dir zunächst die technische Dokumentation der Komponente '''''TComponent''''' (bzw. '''''TForm''''', denn eine '''''TForm''''' ist dieser Parameter tatsächlich) passend zu der Delphi-Version besorgen, mit der der OMSI programmiert wurde. Anhand der Dokumentation kannst du dann die Klasse in C++ ''nachbauen''. Wenn Du das geschafft hast, kannst Du nun den Parameter verwenden. Das Ganze ist - wie gesagt - durchaus möglich, aber mehr ein Hack als vernünftige Programmierung.
 === Die Funktion AccessVariable ===
@@ Zeile 67: / Zeile 45: @@
 </code>
-Solange der Spieler über einen Bus verfügt, werden in jedem Frame alle in der .opl-Datei deklarierten Variablen nacheinander genau in der Reihenfolge der
+Solange der Spieler über einen Bus verfügt, werden in jedem Frame alle in der .opl-Datei deklarierten Variablen nacheinander genau in der Reihenfolge der Deklaration über diese Funktion an Dein Plugin zur Bearbeitung übergeben.
-Der erste Parameter ist dabei der Index der Variablen in der .opl-Datei. Die Zuordnung, welche Variable was ist, musst Du in Deinem Plugin selbst wieder
+Der erste Parameter ist dabei der Index der Variablen in der .opl-Datei. Die Zuordnung, welche Variable was ist, musst Du in Deinem Plugin selbst wieder herstellen. Der zweite Parameter ist ein Zeiger auf einen '''''float'''''-Wert. Das ist der aktuelle Wert der Variablen. Der Wert wird deshalb als Zeigertyp übergeben, damit Du den Wert im Plugin auch ändern kannst. Der dritte Parameter schließlich ist ein Zeiger auf einen '''''bool'''''-Wert. Darüber gibst Du dem OMSI Rückmeldung, ob Du den Inhalt der Variablen verändert hast. Wenn Du die Variable nur lesend benutzt, brauchst Du nichts weiter tun. Der Wert, auf den dieser Zeiger zeigt, ist immer mit '''''false''''' vorbelegt.
 &lt;unbewiesene_aussage&gt;
@@ Zeile 80: / Zeile 53: @@
 &lt;/unbewiesene_aussage&gt;
-Dadurch, das diese Funktion für '''''jede''''' Variable in '''''jedem''''' Frame aufgerufen wird, ergibt sich, das diese Funktion äußerst zeitkritisch ist. Über
+Dadurch, das diese Funktion für '''''jede''''' Variable in '''''jedem''''' Frame aufgerufen wird, ergibt sich, das diese Funktion äußerst zeitkritisch ist. Über die Ausführungsdauer der Funktion in Deinem Plugin beeinflusst Du direkt die Framerate des OMSI (siehe [[OMSI_Plugin_Framework_II#Die_Regel_Nummer_1|Regel Nummer 1]]).
 === Die Funktion AccessTrigger ===
@@ Zeile 95: / Zeile 67: @@
 </code>
-Ähnlich wie bei der Funktion '''''AccessVariable''''' wird auch '''''AccessTrigger''''' in jedem Frame für jeden in der .opl-Datei deklarierten Trigger genau in der
+Ähnlich wie bei der Funktion '''''AccessVariable''''' wird auch '''''AccessTrigger''''' in jedem Frame für jeden in der .opl-Datei deklarierten Trigger genau in der Reihenfolge der Deklaration aufgerufen.
-Der erste Parameter ist dabei der Index des Triggers in der .opl-Datei. Die Zuordnung, welcher Trigger wer ist, musst Du in Deinem Plugin selbst wieder
+Der erste Parameter ist dabei der Index des Triggers in der .opl-Datei. Die Zuordnung, welcher Trigger wer ist, musst Du in Deinem Plugin selbst wieder herstellen. Der zweite Parameter ist ein Zeiger auf einen '''''bool'''''-Wert. Darüber gibst Du dem OMSI Rückmeldung, ob er den Trigger auslösen soll oder nicht. Wenn Du den Trigger nicht auslösen möchtest, brauchst Du nichts weiter tun. Der Wert, auf den dieser Zeiger zeigt, ist immer mit '''''false''''' vorbelegt.
 Genau wie '''''AccessVariable''''' ist auch diese Funktion zeitkritisch, da sie für '''''jeden''''' Trigger in '''''jedem''''' Frame aufgerufen.
@@ Zeile 118: / Zeile 87: @@
 </code>
-Die Funktion '''''Finalize''''' wird einmalig beim Beenden des OMSI aufgerufen und ist nicht zeitkritisch. In diese Funktion gehören alle Aufräumarbeiten, die in
+Die Funktion '''''Finalize''''' wird einmalig beim Beenden des OMSI aufgerufen und ist nicht zeitkritisch. In diese Funktion gehören alle Aufräumarbeiten, die in Deinem Plugin nötig sind.
 ----