DI-Guy SDK Documentation  13.8
6.1 - Writing Plug-Ins

Table of Contents

You can create plug-in DLLs that can work with DI-Guy Scenario at runtime.

A DI-Guy plug-in is a dynamic library that adds additional functionality to DI-Guy Scenario or to an application using the standard DI-Guy SDK libraries. They can be useful for creating interfaces to custom hardware or adding intelligence to scenarios. Plug-ins require a separate license. Plug-ins should be compiled using the same compiler as DI-Guy Scenario. There is a detailed programming example in ./programming_examples/diguy_plugin.

You can load plug-ins in three ways:

  • Specified on DI-Guy Scenario command line using "+plugin xyz" argument.
  • Added to a scenario in DI-Guy Scenario via the Scenario Objects/Specialized Objects/Plugins page.
  • By calling diguyApp::load_plugin().

Once a plug-in has successfully been loaded, functions from the plug-in will be called at specific times during scenario execution.

Plugins can be unloaded in four ways:

  • DI-Guy Scenario is shut down.
  • if part of a scenario, and the plug-in is removed from the scenario by pressing Unload on the Plugins page.
  • if part of a scenario, "Unload on Scenario Close" on the Plugins page is checked, and a new scenario is loaded.
  • By calling diguyApp::unload_plugin().

6.1.1 Supported Plug-in Functions

The following list of functions can be exported from a DLL plug-in and are recognized by DI-Guy Scenario. These functions are prototypes. You must implement the ones you want to use. However, you do not have to implement all the functions, just the ones you need. Only the diguy_version() function must be implemented.

DI-Guy Scenario will automatically call these functions at the appropriate time. Plug-in functions should be declared with __declspec(dllexport) to make sure that the symbols are properly exported from the DLL. Please see the plug-in example in the DI-Guy OpenGL programming examples folder for an example of how to build a plug-in that will work with DI-Guy Scenario.

void diguy_version(int* version_major, int* version_minor, int* version_point)

This function is called once, when the plug-in is being loaded. The function should return, via the passed int pointers, the DI-Guy version number as defined in diguy_constants.h. DI-Guy will compare these numbers against the current version number to make sure the plug-in is compatible with the current version.

C++ Example:

__declspec(dllexport) void
diguy_version(int* version_major, int* version_minor, int* version_point)
{
*version_major = DIGUY_VERSION_MAJOR;
*version_minor = DIGUY_VERSION_MINOR;
*version_point = DIGUY_VERSION_POINT;
}
  • Initialization functions:

    • void initialize_plugin(diguyApp *app). This function is called once, when the plug-in is being loaded. If the plug-in is being loaded because it was specified on the DI-Guy Scenario command line, this function is called as DI-Guy Scenario is initializing, before the first scenario is created.

      If the plugin is part of a scenario (is shown in the DI-Guy Scenario Scenario Objects/Specialized Objects/Plugins page), the call will happen when the scenario is loaded.

      If the plugin is being loaded because of a load_plugin() call, this function is called during the load_plugin() call.

    • void deinitialize_plugin(diguyApp *app). Called once, when the plug-in is being unloaded. The call will happen while DI-Guy Scenario is shutting down, or during the unload_plugin() call if the plug-in is being explicitly unloaded by function call.

    • void initialize(diguyScenario *s). This function is called when the active scenario first becomes aware of the plug-in. This is when the scenario is created if the plug-in has already been loaded, or during the load_plugin() call if the plug-in is loaded after the scenario was created.

    • void deinitialize(diguyScenario *s). Called when the scenario is deleted, or when unload_plugin() is called.

  • Pre and post draw functions:

    • void pre_draw(diguyScenario *s). This code is called once per frame before objects are drawn. Only code related to drawing should be here. Use update() for any other code you want to be called frequently.

    • void post_draw(diguyScenario *s). This code is called once per frame after all other objects have been drawn. It is a good place to draw overlays or transparent objects. 
          \note Both draw functions work because they are called in a thread with a valid OpenGL context. Any OpenGL call should work, and querying and modifying the current OpenGL state should also work. It is your responsibility to make sure the OpenGL state is restored to what it was at the beginning of the function.

  • Pre and post update functions:

    • void pre_update(diguyScenario *s). Called during the diguyScenario::update() call, before anything else is changed due to the update. (That is, characters will not have moved yet, and so on.)

    • void post_update(diguyScenario *s). Called during the diguyScenario::update() call, after everything else is changed due to the update. (That is, characters will have moved, and so on.)

      You can use functions such as scenario->get_replaying_history() and scenario->get_t() to branch whether you are replaying history or you are generating new data at runtime. It is up to you to decide what to do for each case.

      Update is called once per frame update.

    • void reset(diguyScenario *s). Reset is called whenever the scenario is reset, if the plug-in has its own history, this may be an appropriate time to clear it. 

      \note A key feature of DI-Guy is the ability to save and restore the history of a scenario. Plug-ins can supplement this feature using the review_data  functions. The filename argument is the base name of the history review files. It is the programmer’s job to write the serialization and deserialization code.

  • Review data functions:

    • void save_review_data(const char* filename). Called when after-action-review data for the scenario is saved by a call to diguyScenario::save_review_data().

      Example:

      save_review_data(const char* filename)
      {
      char buffer[MAX_PATH];
      sprintf(buffer, "%s.myplugin", filename);
      FILE * file = fopen(buffer,"w+b");
      assert(file);
      .
      .
      .
      fclose(file);
      }

    • void load_review_data(const char* filename). Called when after-action-review data for the scenario is loaded by a call to diguyScenario::load().

  • Mouse control functions:

    • diguyPluginMouseCursor get_mouse_cursor(diguyScenario* s). Returns the type of cursor that should be used when the mouse is in a 3D View. Please see the documentation for diguyPluginMouseCursor for a list of valid values. If this function is not exported from the plug-in, the default cursor DIGUY_PLUGIN_MOUSE_CURSOR_LEFT_ARROW is used.

    • void mouse_func(diguyScenario * s, int x, int y, int down).

    • void mouse_press(diguyScenario* s, diguyPluginMouseEvent* mouse_event). This function is called on an initial press of any mouse button in a 3D View. Use the query functions of the diguyPluginMouseEvent object to retrieve which view the press occurred in and the X and Y screen coordinates of the press.

    • void mouse_drag(diguyScenario* s, diguyPluginMouseEvent* mouse_event). Called when the mouse is moved in a 3D View while one or more buttons are pressed.

    • void mouse_release(diguyScenario* s, diguyPluginMouseEvent* mouse_event). Called when any mouse button is released in a 3D View.

    • void mouse_move(diguyScenario* s, diguyPluginMouseEvent* mouse_event). Called when the mouse is moved in a 3D View while no buttons are pressed.

Please see the diguyApp documentation for more detailed information on plug-in functions.

[Home] [Top of Page]