Technical reference > Plug-ins

Building Plug-ins

The plug-in format used by winvrut is a simple "WIN32 Dynamic Linked Libary" style which can be built using MSVC.  The easiest way to build a plug-in is to start with the skeleton code called sensor_template.c (if you chose to compile as C++ be sure and add the extern "C" before each dllexport line).  In it, you'll notice that there are five functions that must be present with exactly the declaration style and names provided below (these are searched for by winvrut during the initialization process).  The five functions are query, initialize, update, reset, and close.  In addition, there is an optional sixth function that can be defind to receive a command signal in the form of a floating point nuumber.  If this function is provided, then the Python programming interface can send the DLL this value.  Each function is described in the code comments.

Any plug-in found during winvrut's initialization is only placed in a list of available but unverified sensors.  No attempt is actually made to connect to a sensor until the user issues a vrut.addsensor command.  The sensor type field supplied by the query function allow winvrut to maintain a list of all types of trackers (3DOF, 6DOF, JOYSTICK, etc), and allows the user to request a sensor based on its type--winvrut will then figure out which specific one to use for the task.  Alternatively, the user can request a sensor by name, in which case the name used must be the name of the .DLL placed in the plug-in folder (not case sensitive).

/***********************************************************************
************************************************************************

Sensor template

Use this template by filling in the prototype functions provided below.
Compile this project as a WIN32 DLL.  The plug-in will be access through
winvrut either by its type or by it .dll name.

************************************************************************
***********************************************************************/
 

#include <windows.h>

#include <math.h>
#include <stdio.h>
#include <stdlib.h>
#include <conio.h>
#include <string.h>
 

#include "vrut.h"
#include "sensors.h"
 

// DO NOT MODIFY THESE DECLARATIONS----------------
// For C++ add to beginning of each line: extern "C"
__declspec(dllexport) void QuerySensor(void *);
__declspec(dllexport) void InitializeSensor(void *);
__declspec(dllexport) void UpdateSensor(void *);
__declspec(dllexport) void ResetSensor(void *);
__declspec(dllexport) void CloseSensor(void *);
__declspec(dllexport) void CommandSensor(void *);   /* optional function */
 
 

void QuerySensor(void *sensor)
{
 // This function gets called during the winvrut initialization process.
 // Its only purpose is to set the sensor type (see choices in sensor.h),
 // so that it can be automatically made available to the user according
 // to its type.
 // No initialization or communication should be attempted at this point
 // because the device may never be requested by user (and it might not
 // even be connect!).

 strcpy( ((VRUTSensorObj *)sensor)->version, "Sensor XX version 2.2");
 ((VRUTSensorObj *)sensor)->type = SENSOR_HEADORI;
}

void InitializeSensor(void *sensor)
{
 // This function gets called when the user attempts to add this particular
 // sensor. Use this for firing up the sensor and making sure it works.  Only
 // if everything checks should you set the status to TRUE.

 ((VRUTSensorObj *)sensor)->status = TRUE;
}

void UpdateSensor(void *sensor)
{
 // Update the sensor data fields (see sensor.h)
 // Fields 0-2: reserved for x, y, z position data
 // Fields 3-5: reserved for yaw, pitch, roll
 // or
 // Fields 3-6: reserved for quaternion data
 //
 // eg:
 // ((VRUTSensorObj *)sensor)->data[0] = newX;
}

void ResetSensor(void *sensor)
{
 // If the user were to send a reset command, do whatever makes sense to do.
}

void CloseSensor(void *sensor)
{
 // Go ahead, clean up, and close files and COM ports.
}

void CommandSensor(void *sensor)
{
 // ((VRUTSensorObj *)sensor)->command;  <-- can be used as a signal
}