How to create and report from a device in your plugin. More...

Typedefs
typedef struct OSVR_DeviceTokenObject *	OSVR_DeviceToken
	Opaque type of a registered device token within the core library. More...

typedef struct OSVR_MessageTypeObject *	OSVR_MessageType
	Opaque type of a registered message type within the core library. More...

typedef struct OSVR_DeviceInitObject *	OSVR_DeviceInitOptions
	Opaque type of a device initialization object. More...

Functions
OSVR_DeviceInitOptions	osvrDeviceCreateInitOptions (OSVR_PluginRegContext ctx)
	Create a OSVR_DeviceInitOptions object. More...

OSVR_ReturnCode	osvrDeviceRegisterMessageType (OSVR_PluginRegContext ctx, const char name, OSVR_MessageType msgtype)
	Register (or recall) a message type by name. More...

OSVR_ReturnCode	osvrDeviceSendData (OSVR_DeviceToken dev, OSVR_MessageType msg, const char *bytestream, size_t len)
	Send a raw bytestream from your device. More...

OSVR_ReturnCode	osvrDeviceSendTimestampedData (OSVR_DeviceToken dev, const OSVR_TimeValue timestamp, OSVR_MessageType msg, const char bytestream, size_t len)
	Send a raw bytestream from your device, with a known timestamp. More...

OSVR_ReturnCode	osvrDeviceSendJsonDescriptor (OSVR_DeviceToken dev, const char *json, size_t len)
	Submit a JSON self-descriptor string for the device. More...

OSVR_ReturnCode	osvrDeviceRegisterUpdateCallback (OSVR_DeviceToken dev, OSVR_DeviceUpdateCallback updateCallback, void *userData=NULL)
	Register the update callback of a device. More...

OSVR_ReturnCode	osvrDeviceMicrosleep (uint64_t microseconds)
	Request a thread sleep for at least the given number of microseconds. DO NOT use within a Sync plugin! More...

Synchronous Devices
Devices declaring themselves to be synchronous must abide by strict rules. Their update method is run regularly in the main thread of the device system, without the overhead of locking. In exchange, however, the following restrictions apply: The update method must complete as quickly as reasonably possible, since it adds to overall latency. No data may be sent through the library outside of the update method, and the update method should only be called by the core library (not by the plugin)
OSVR_ReturnCode	osvrDeviceSyncInit (OSVR_PluginRegContext ctx, const char name, OSVR_DeviceToken device)
	Initialize a synchronous device token. More...

OSVR_ReturnCode	osvrDeviceSyncInitWithOptions (OSVR_PluginRegContext ctx, const char name, OSVR_DeviceInitOptions options, OSVR_DeviceToken device)
	Initialize a synchronous device token. More...

Asynchronous Devices
These devices are more event-based: either it's convenient for your driver to block until full data arrives, or you can't be sure your driver can get in and out of an update function very rapidly. As a result, devices registered as async have their update method run in a thread of its own, repeatedly as long as the device exists. Calls sending data from an async device are automatically made thread-safe.
OSVR_ReturnCode	osvrDeviceAsyncInit (OSVR_PluginRegContext ctx, const char name, OSVR_DeviceToken device)
	Initialize an asynchronous device token. More...

OSVR_ReturnCode	osvrDeviceAsyncInitWithOptions (OSVR_PluginRegContext ctx, const char name, OSVR_DeviceInitOptions options, OSVR_DeviceToken device)
	Initialize an asynchronous device token. More...

Detailed Description

How to create and report from a device in your plugin.

Typedef Documentation

typedef struct OSVR_DeviceTokenObject* OSVR_DeviceToken

#include <osvr/PluginKit/DeviceInterfaceC.h>

Opaque type of a registered device token within the core library.

Each device you register will be given one of these. You must hold on to it in association with that device until the device is no longer active, as each call from the device into this C device API will require it.

Definition at line 60 of file DeviceInterfaceC.h.

typedef struct OSVR_MessageTypeObject* OSVR_MessageType

#include <osvr/PluginKit/DeviceInterfaceC.h>

Opaque type of a registered message type within the core library.

Common device types will have pre-defined message types, while more specific or unique devices may need to define their own.

Definition at line 67 of file DeviceInterfaceC.h.

typedef struct OSVR_DeviceInitObject* OSVR_DeviceInitOptions

#include <osvr/PluginKit/DeviceInterfaceC.h>

Opaque type of a device initialization object.

When creating a device token that implements one or more existing interface types, you'll construct one of these, specify which interfaces you are implementing, then pass it to the device token creation.

Definition at line 75 of file DeviceInterfaceC.h.

Function Documentation

OSVR_DeviceInitOptions osvrDeviceCreateInitOptions ( OSVR_PluginRegContext ctx )

#include <osvr/PluginKit/DeviceInterfaceC.h>

Create a OSVR_DeviceInitOptions object.

There is no corresponding destroy method because it is handed over to a device token constructor that takes ownership of it.

Parameters

ctx	The plugin registration context received by your entry point function.

OSVR_ReturnCode osvrDeviceRegisterMessageType	(	OSVR_PluginRegContext	ctx,
		const char *	name,
		OSVR_MessageType *	msgtype
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Register (or recall) a message type by name.

Parameters

	ctx	The plugin registration context received by your entry point function.
	name	A unique name for the message type. The library makes a copy of this string.
[out]	msgtype	Will contain the message type identifier you've registered.

OSVR_ReturnCode osvrDeviceSendData	(	OSVR_DeviceToken	dev,
		OSVR_MessageType	msg,
		const char *	bytestream,
		size_t	len
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Send a raw bytestream from your device.

Note: The same function is used for synchronous and asynchronous devices: the device token is sufficient to determine whether locking is needed.

OSVR_ReturnCode osvrDeviceSendTimestampedData	(	OSVR_DeviceToken	dev,
		const OSVR_TimeValue *	timestamp,
		OSVR_MessageType	msg,
		const char *	bytestream,
		size_t	len
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Send a raw bytestream from your device, with a known timestamp.

Note: The same function is used for synchronous and asynchronous devices: the device token is sufficient to determine whether locking is needed.

OSVR_ReturnCode osvrDeviceSendJsonDescriptor	(	OSVR_DeviceToken	dev,
		const char *	json,
		size_t	len
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Submit a JSON self-descriptor string for the device.

Length does not include null terminator.

OSVR_ReturnCode osvrDeviceRegisterUpdateCallback	(	OSVR_DeviceToken	dev,
		OSVR_DeviceUpdateCallback	updateCallback,
		void *	userData = `NULL`
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Register the update callback of a device.

The callback you provide will be called potentially as soon as this call completes. If you created a Sync device token, it will be run in the main update loop. If you created an Async device token, it will be run repeatedly in its own thread.

When your callback, a function of type OSVR_DeviceUpdateCallback, is invoked, it will receive the same userdata you provide here (if any).

Parameters

device	The device token.
updateCallback	The address of your callback function.
userData	An opaque pointer that will be returned to you when the callback you register here is called. Technically optional, but hard to support multiple instances without it.

OSVR_ReturnCode osvrDeviceSyncInit	(	OSVR_PluginRegContext	ctx,
		const char *	name,
		OSVR_DeviceToken *	device
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Initialize a synchronous device token.

This primarily allocates the device token, and does not start reporting.

Parameters

	ctx	The plugin registration context received by your entry point function.
	name	A unique name for the device, abiding by the rules for an element (directory) in a URL. The library makes a copy of this string.
[out]	device	Will contain the unique device token assigned to your synchronous device.

OSVR_ReturnCode osvrDeviceSyncInitWithOptions	(	OSVR_PluginRegContext	ctx,
		const char *	name,
		OSVR_DeviceInitOptions	options,
		OSVR_DeviceToken *	device
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Initialize a synchronous device token.

This primarily allocates the device token, and does not start reporting.

Parameters

	ctx	The plugin registration context received by your entry point function.
	name	A unique name for the device, abiding by the rules for an element (directory) in a URL. The library makes a copy of this string.
[out]	device	Will contain the unique device token assigned to your synchronous device. Initialize a synchronous device token with the options specified.
	options	The DeviceInitOptions for your device.

This transfers ownership of the DeviceInitOptions, and all created objects associated with it, to the returned device token.

OSVR_ReturnCode osvrDeviceAsyncInit	(	OSVR_PluginRegContext	ctx,
		const char *	name,
		OSVR_DeviceToken *	device
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Initialize an asynchronous device token.

This primarily allocates the device token, and does not start reporting.

Parameters

	ctx	The plugin registration context received by your entry point function.
	name	A unique name for the device, abiding by the rules for an element (directory) in a URL. The library makes a copy of this string.
[out]	device	Will contain the unique device token assigned to your asynchronous device.

OSVR_ReturnCode osvrDeviceAsyncInitWithOptions	(	OSVR_PluginRegContext	ctx,
		const char *	name,
		OSVR_DeviceInitOptions	options,
		OSVR_DeviceToken *	device
	)

#include <osvr/PluginKit/DeviceInterfaceC.h>

Initialize an asynchronous device token.

This primarily allocates the device token, and does not start reporting.

Parameters

	ctx	The plugin registration context received by your entry point function.
	name	A unique name for the device, abiding by the rules for an element (directory) in a URL. The library makes a copy of this string.
[out]	device	Will contain the unique device token assigned to your asynchronous device. Initialize an asynchronous device token with the options specified.
	options	The DeviceInitOptions for your device.

This transfers ownership of the DeviceInitOptions, and all created objects associated with it, to the returned device token.

OSVR_ReturnCode osvrDeviceMicrosleep ( uint64_t microseconds )

#include <osvr/PluginKit/DeviceInterfaceC.h>

Request a thread sleep for at least the given number of microseconds. DO NOT use within a Sync plugin!

This is just a request for a minimum sleep time - operating system scheduling and sleep granularity means that you may end up sleeping for longer.

Typedefs

Functions

Synchronous Devices

Asynchronous Devices

Detailed Description

Typedef Documentation

Function Documentation