Plugin Registration (base C API)

How to start writing a plugin and advertise your capabilities to the core library. More...

Macros
#define	OSVR_PLUGIN(PLUGIN_NAME)   LIBFUNC_PLUGIN(PLUGIN_NAME, ctx)
	This macro begins the entry point function of your plugin. More...

Functions
void	osvrPluginLog (OSVR_PluginRegContext ctx, OSVR_LogLevel severity, const char *message)
	Log a message to the plugin's log channel. More...

Hardware Detection and Driver Instantiation
If your plugin contains drivers for devices that you can detect, you'll want to register for hardware detection. Whether or not you can detect, you may wish to register constructors (instantiation callbacks) that accept parameters.
OSVR_ReturnCode	osvrPluginRegisterHardwareDetectCallback (OSVR_PluginRegContext ctx, OSVR_HardwareDetectCallback detectCallback, void *userData=NULL)
	Register a callback in your plugin to be notified when hardware should be detected again. More...
OSVR_ReturnCode	osvrRegisterDriverInstantiationCallback (OSVR_PluginRegContext ctx, const char *name, OSVR_DriverInstantiationCallback cb, void *userData=NULL)
	Register an instantiation callback (constructor) for a driver type. The given constructor may be called with a string containing configuration information, the format of which you should document with your plugin. JSON is recommended. More...

Plugin Instance Data
Plugins "own" the modules instantiated in them. Lifetime must be managed appropriately: destroyed on shutdown. You can store the instances in any way you would like, as long as you register them with appropriate deleter callbacks here.
OSVR_ReturnCode	osvrPluginRegisterDataWithDeleteCallback (OSVR_PluginRegContext ctx, OSVR_PluginDataDeleteCallback deleteCallback, void *pluginData)
	Register plugin data along with an appropriate deleter callback. More...

Detailed Description

How to start writing a plugin and advertise your capabilities to the core library.

Macro Definition Documentation

#define OSVR_PLUGIN

(

PLUGIN_NAME

)

LIBFUNC_PLUGIN(PLUGIN_NAME, ctx)

#include <osvr/PluginKit/PluginRegistrationC.h>

This macro begins the entry point function of your plugin.

Treat it as if it were a function declaration, since that is what it will expand to. The function body you write calls some subset of the plugin registration methods, then returns either success (OSVR_RETURN_SUCCESS) or failure (OSVR_RETURN_FAILURE).

Your function body receives a single argument, of type OSVR_PluginRegContext, named ctx. You will need to pass this to most PluginKit functions that you call.

Definition at line 67 of file PluginRegistrationC.h.

Function Documentation

OSVR_ReturnCode osvrPluginRegisterHardwareDetectCallback	(	OSVR_PluginRegContext	ctx,
		OSVR_HardwareDetectCallback	detectCallback,
		void *	userData = NULL
	)

#include <osvr/PluginKit/PluginRegistrationC.h>

Register a callback in your plugin to be notified when hardware should be detected again.

When your callback, a function of type OSVR_HardwareDetectCallback, is invoked, it will receive the same userdata you provide here (if any). Your plugin should do whatever probing necessary to detect devices you can handle and instantiate the device drivers.

Parameters

ctx	The registration context passed to your entry point.
detectCallback	The address of your callback function
userData	An optional opaque pointer that will be returned to you when the callback you register here is called.

OSVR_ReturnCode osvrRegisterDriverInstantiationCallback	(	OSVR_PluginRegContext	ctx,
		const char *	name,
		OSVR_DriverInstantiationCallback	cb,
		void *	userData = NULL
	)

#include <osvr/PluginKit/PluginRegistrationC.h>

Register an instantiation callback (constructor) for a driver type. The given constructor may be called with a string containing configuration information, the format of which you should document with your plugin. JSON is recommended.

Parameters

ctx	The plugin registration context received by your entry point function.
name	A unique name for the driver type. The library makes a copy of this string.
cb	Your callback
userData	An opaque pointer passed to your callback, if desired.

OSVR_ReturnCode osvrPluginRegisterDataWithDeleteCallback	(	OSVR_PluginRegContext	ctx,
		OSVR_PluginDataDeleteCallback	deleteCallback,
		void *	pluginData
	)

#include <osvr/PluginKit/PluginRegistrationC.h>

Register plugin data along with an appropriate deleter callback.

When your callback, a function of type OSVR_PluginDataDeleteCallback, is invoked, it will receive the plugin data pointer you provide here. Your deleter is responsible for appropriately deleting/freeing/destructing all data associated with that pointer.

This function may be called more than once, to register multiple plugin data objects. Callbacks will be called, sorted first by plugin, in reverse order of registration.

Parameters

ctx	The registration context passed to your entry point.
deleteCallback	The address of your deleter callback function
pluginData	A pointer to your data, treated as opaque by this library, and passed to your deleter.

void osvrPluginLog	(	OSVR_PluginRegContext	ctx,
		OSVR_LogLevel	severity,
		const char *	message
	)

#include <osvr/PluginKit/PluginRegistrationC.h>

Log a message to the plugin's log channel.

Parameters

ctx	The registration context passed to your entry point.
severity	The severity of the log message.
message	The message to be logged.