|
OSVR-Core
|
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 | |
| OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT void | osvrPluginLog (OSVR_INOUT_PTR OSVR_PluginRegContext ctx, OSVR_IN OSVR_LogLevel severity, OSVR_IN const char *message) OSVR_FUNC_NONNULL((1 |
| 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_PLUGINKIT_EXPORT OSVR_ReturnCode | osvrPluginRegisterHardwareDetectCallback (OSVR_INOUT_PTR OSVR_PluginRegContext ctx, OSVR_IN OSVR_HardwareDetectCallback detectCallback, OSVR_IN_OPT void *userData OSVR_CPP_ONLY(=NULL)) OSVR_FUNC_NONNULL((1)) |
| Register a callback in your plugin to be notified when hardware should be detected again. More... | |
| OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode | osvrRegisterDriverInstantiationCallback (OSVR_INOUT_PTR OSVR_PluginRegContext ctx, OSVR_IN_STRZ const char *name, OSVR_IN_PTR OSVR_DriverInstantiationCallback cb, OSVR_IN_OPT void *userData OSVR_CPP_ONLY(=NULL)) OSVR_FUNC_NONNULL((1 |
| Register an instantiation callback (constructor) for a driver type. 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_PLUGINKIT_EXPORT OSVR_ReturnCode | osvrPluginRegisterDataWithDeleteCallback (OSVR_INOUT_PTR OSVR_PluginRegContext ctx, OSVR_IN OSVR_PluginDataDeleteCallback deleteCallback, OSVR_INOUT_PTR void *pluginData) OSVR_FUNC_NONNULL((1 |
| Register plugin data along with an appropriate deleter callback. More... | |
How to start writing a plugin and advertise your capabilities to the core library.
| #define OSVR_PLUGIN | ( | PLUGIN_NAME | ) | LIBFUNC_PLUGIN(PLUGIN_NAME, ctx) |
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.
| OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT void osvrPluginLog | ( | OSVR_INOUT_PTR OSVR_PluginRegContext | ctx, |
| OSVR_IN OSVR_LogLevel | severity, | ||
| OSVR_IN const char * | message | ||
| ) |
Log a message to the plugin's log channel.
| ctx | The registration context passed to your entry point. |
| severity | The severity of the log message. |
| message | The message to be logged. |
| OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrPluginRegisterDataWithDeleteCallback | ( | OSVR_INOUT_PTR OSVR_PluginRegContext | ctx, |
| OSVR_IN OSVR_PluginDataDeleteCallback | deleteCallback, | ||
| OSVR_INOUT_PTR void * | pluginData | ||
| ) |
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.
| 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. |
| OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrPluginRegisterHardwareDetectCallback | ( | OSVR_INOUT_PTR OSVR_PluginRegContext | ctx, |
| OSVR_IN OSVR_HardwareDetectCallback | detectCallback, | ||
| OSVR_IN_OPT void *userData | OSVR_CPP_ONLY=NULL | ||
| ) |
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.
| 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_PLUGINKIT_EXPORT OSVR_ReturnCode osvrRegisterDriverInstantiationCallback | ( | OSVR_INOUT_PTR OSVR_PluginRegContext | ctx, |
| OSVR_IN_STRZ const char * | name, | ||
| OSVR_IN_PTR OSVR_DriverInstantiationCallback | cb, | ||
| OSVR_IN_OPT void *userData | OSVR_CPP_ONLY=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.
| 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. |
1.8.12