Now that I have played around with hooks on VESSEL2 virtual functions, I think I can share my developments with other Orbiter hackers.
Ok, here is it: an API to hijack class VESSEL2 virtual functions and process events, such as HUD drawing.
Please not that this is a 'tech preview' version, not a complete product. Any feedback would be much appreciated. Especially, I'd like to hear from agentgonzo and Face who showed some interest in a centralized hijacking API in previous discussions. So now that we have a working base, I'd like to discuss additional features and, perhaps, further co-development, if you're interested, as I'm planning to upload the sources to some public SVN repo. (Btw, Sourcforge or Google code -- what would you suggest?)
View attachment VHL-bin-0.4.13A.zip
View attachment VHL-SDK-0.4.13A.zip
-------------
Now a few words on what to do with this.
If you, as a developer, are interested in what's going on between Orbiter core and some vessel, here's your chance to take a peek. With this DLL you will be able to place hooks on vessel's events it receives from Orbiter.
To install, simply unpack the VHL-bin-0.4.13A.zip into Orbiter root, (so that VHL_core.dll goes to orbiter root and VHL_plug.dll goes to mudules/plugin/).
Unpack the VHL-sdk-0.4.13A.zip into a folder of you choice, #include "vhl/vhl.h" and link against lib/vhl_core.lib. That should do. Be sure to read comments in vhl/vhl.h, as this is the only documentation at the moment.
Basically, you'll need to create an event sink, eg to derive a class from VHL_interface and override any of the functions you're interested in. You should call VHL_register() to obtain a userid (you may do this even in InitModule() ) and you install hooks by calling VHL_subscribe(). Your event sink should start receiving vessel's event notifications automatically. Please note, however, that care must be taken to
I also include complete sources so you can try compiling everything for yourself (a debug version, perhaps).
View attachment VHL-src-0.4.13A.zip
And also I include a modified version of my Axial Velocity HUD (no sources yet, sorry) to test compatibility:
View attachment vel_hud-1.0RC2mod0.zip
-------------
And now some notes on the code structure.
There is a single 'Mastermind' that manages all vessel hooks. Each vessel is assigned a single master hook on request, i.e. not right away, but when a subscription is requested by the user. Each subscription is owned some user, and every user has to be registered in order to subscribe to events.
Master hook is the one who does the actual hijacking, and the hijack is per-vessel, i.e. it makes a fake VMT filled with hijacker's impostors and patches the VMT pointer in the vessel instance. When an original method has to be called, the original VMT pointer is briefly restored and then patched again (there were crashes when I tried to do that per function, but the patching is still per-vessel). The master hook reports events directly to the mastermind and the mastermind dispatches these events to subscribers.
The VHL_core.dll is not an Orbiter addon per se, because I encountered some orbiter.cfg addon order-dependent issues, so I made a small project vhl_plug that is intended to report Orbiter events to the mastermind. Right now it tracks vessel deletion so that the mastermind can free resources associated with hooks.
This design is not final of course, many things can be changed, eg:
Ok, here is it: an API to hijack class VESSEL2 virtual functions and process events, such as HUD drawing.
Please not that this is a 'tech preview' version, not a complete product. Any feedback would be much appreciated. Especially, I'd like to hear from agentgonzo and Face who showed some interest in a centralized hijacking API in previous discussions. So now that we have a working base, I'd like to discuss additional features and, perhaps, further co-development, if you're interested, as I'm planning to upload the sources to some public SVN repo. (Btw, Sourcforge or Google code -- what would you suggest?)
View attachment VHL-bin-0.4.13A.zip
View attachment VHL-SDK-0.4.13A.zip
-------------
Now a few words on what to do with this.
If you, as a developer, are interested in what's going on between Orbiter core and some vessel, here's your chance to take a peek. With this DLL you will be able to place hooks on vessel's events it receives from Orbiter.
To install, simply unpack the VHL-bin-0.4.13A.zip into Orbiter root, (so that VHL_core.dll goes to orbiter root and VHL_plug.dll goes to mudules/plugin/).
Unpack the VHL-sdk-0.4.13A.zip into a folder of you choice, #include "vhl/vhl.h" and link against lib/vhl_core.lib. That should do. Be sure to read comments in vhl/vhl.h, as this is the only documentation at the moment.
Basically, you'll need to create an event sink, eg to derive a class from VHL_interface and override any of the functions you're interested in. You should call VHL_register() to obtain a userid (you may do this even in InitModule() ) and you install hooks by calling VHL_subscribe(). Your event sink should start receiving vessel's event notifications automatically. Please note, however, that care must be taken to
I also include complete sources so you can try compiling everything for yourself (a debug version, perhaps).
View attachment VHL-src-0.4.13A.zip
And also I include a modified version of my Axial Velocity HUD (no sources yet, sorry) to test compatibility:
View attachment vel_hud-1.0RC2mod0.zip
-------------
And now some notes on the code structure.
There is a single 'Mastermind' that manages all vessel hooks. Each vessel is assigned a single master hook on request, i.e. not right away, but when a subscription is requested by the user. Each subscription is owned some user, and every user has to be registered in order to subscribe to events.
Master hook is the one who does the actual hijacking, and the hijack is per-vessel, i.e. it makes a fake VMT filled with hijacker's impostors and patches the VMT pointer in the vessel instance. When an original method has to be called, the original VMT pointer is briefly restored and then patched again (there were crashes when I tried to do that per function, but the patching is still per-vessel). The master hook reports events directly to the mastermind and the mastermind dispatches these events to subscribers.
The VHL_core.dll is not an Orbiter addon per se, because I encountered some orbiter.cfg addon order-dependent issues, so I made a small project vhl_plug that is intended to report Orbiter events to the mastermind. Right now it tracks vessel deletion so that the mastermind can free resources associated with hooks.
This design is not final of course, many things can be changed, eg:
- If the userid model proves unnecessary, we can drop it and make mastermind accept 'anonymous subscriptions'.
- Hijacking model can be changed so that hook lists are per-method, rather than per-VHL_interface instance. This'll yield slightly better performance when there are many hooks at the expense of more tedious book-keeping.
- Right now there's a lack of any core checking if a vessel being hijacked is VESSEL2-derived, so it leads to crashes. Some checks are required, but right now I can't think of any except for a whitelist, i.e. a list of classes that are known to work, much like in vel_hud
