Documentation

edited January 2015 in Help request
Hi guys, first wueation, so lat's make it an idiot one ;-) Is there a document/s that describe the overall architecture of ORX? I'm oarticularly intersted in the plug-in concept, as I'd really love to write once, compile with minimal effort on several platforms.

Thanks

Jim

Comments

  • edited January 2015
    Hi LameDuck,

    Well, beside the doxygen doc which describes the "public" API, most of the documentation can be found in the wiki, but is more written from a user point of view, without many details on the internal architecture.

    The plugin system is one of the oldest part of orx and is a bit dusty, as a consequence. First of all, what would you like to achieve, maybe there's a better way than going through the plugin system?

    Anyway, here's a quick breakdown of the system. Plugins come in two flavours: core and user.
    There are 7 core plugins, all with their interfaces defined in orx: display, render, mouse, joystick, keyboard, physics and soundsystem. 95% of the platform-dependent code found in orx is in those plugins.
    The remaining 5% are the time-related functions and the filesystem ones. There are conditional ifdefs in both those modules to adapt to the different platforms. They both used to be plugins back in the days, but we ended up with a chicken-and-egg problem as both filesystem and time where much lower level than the plugin system and where required by it in some way or the other.

    Now there is at least one implementation of all those 7 plugins for every supported platform. For example, there's only a single physics plugin and a single render plugin as we speak (although anyone is welcome to contribute additional ones, based on different tech) but a gazillion of display ones (for computers, there's even 3 plugins available, though 2 of them are a bit antiquated: SDL & SFML ones).

    Those plugins can either be loaded at runtime, which was the only supported mode at the beginning, or embedded (linked) statically at compile time (driven by the __orxEMBEDDED__ define), which is what everybody is using nowadays, beside the tools (orxCrypt and orxFontGen), that do not load any plugin at all.

    Now, there's also the user plugins. For example, the first 9 tutorials and the "demo" (Bounce, which is my playground for developing features) coming with orx are user plugins that get loaded from a simple launcher. They could register additional functions to the system, but in the facts they mostly use the init function as a hook to register a clock and get executed.

    The advantages of using user plugins was that it only required a single line of code using the orxPLUGIN_INIT() macro to get rolling. That was an advantage when running orx itself in a more traditional way was much more complex than simply calling orx_Execute() in one's main function.

    Nowadays, using user plugins for this is actually more trouble than the contrary. The only real advantage I could see would be if one wanted to create a gaming platform (or an editor) that could load game projects on the fly without needing to restart. For this, someone would code their own launcher and game projects would be compiled as user plugins that could get loaded/unloaded at will.

    As you've probably noticed, I mentioned that one could register additional function to a user plugin. This was meant to work exactly in the same way than plugins in Gimp or Eggdrop. The issue is that the function can be registered but there's no easy way to find them and execute them (like a scripting language, for example). That could be supported in the future, but so far no one expressed their need for this so the system was left untouched for over a decade.

    If you have any questions or need any precision on all this, don't hesitate. :)

    To sum it up: what would you like to achieve as there might be an easier way than going through the plugin system?
  • edited January 2015
    I'm trying to achieve the holy graille, write my code once, and have it run everywhere! I need to do a lot more reading and playing yet. Still very much poking around in the dark, will come back with "sensible" questions, once I have a handle on how ORX will do what I want!

    Thank you for the reply though, very encouraging in promnised support terms :-)

    J
  • edited January 2015
    My pleasure. :)

    As for the write once use everywhere, it's our goal as much as possible. Only very little platform-specific code is needed in some cases, such as when handling multi-touch events that are only sent on mobile and not on computers, though you can still have the code on computes, it'll simply not get called.
Sign In or Register to comment.