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_PLUGINKIT_EXPORT OSVR_DeviceInitOptions	osvrDeviceCreateInitOptions (OSVR_IN_PTR OSVR_PluginRegContext ctx) OSVR_FUNC_NONNULL((1))
	Create a OSVR_DeviceInitOptions object. More...

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode	osvrDeviceRegisterMessageType (OSVR_IN_PTR OSVR_PluginRegContext ctx, OSVR_IN_STRZ const char name, OSVR_OUT_PTR OSVR_MessageType msgtype) OSVR_FUNC_NONNULL((1
	Register (or recall) a message type by name. More...

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode	osvrDeviceSendData (OSVR_IN_PTR OSVR_DeviceToken dev, OSVR_IN_PTR OSVR_MessageType msg, OSVR_IN_READS(len) const char *bytestream, OSVR_IN size_t len) OSVR_FUNC_NONNULL((1
	Send a raw bytestream from your device. More...

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

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

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode	osvrDeviceRegisterUpdateCallback (OSVR_IN_PTR OSVR_DeviceToken dev, OSVR_IN OSVR_DeviceUpdateCallback updateCallback, OSVR_IN_OPT void *userData OSVR_CPP_ONLY(=NULL)) OSVR_FUNC_NONNULL((1))
	Register the update callback of a device. More...

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode	osvrDeviceMicrosleep (OSVR_IN uint64_t microseconds)
	Request a thread sleep for at least the given number of microseconds. 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_PLUGINKIT_EXPORT OSVR_ReturnCode	osvrDeviceSyncInit (OSVR_IN_PTR OSVR_PluginRegContext ctx, OSVR_IN_STRZ const char name, OSVR_OUT_PTR OSVR_DeviceToken device) OSVR_FUNC_NONNULL((1
	Initialize a synchronous device token. More...

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode	osvrDeviceSyncInitWithOptions (OSVR_IN_PTR OSVR_PluginRegContext ctx, OSVR_IN_STRZ const char name, OSVR_IN_PTR OSVR_DeviceInitOptions options, OSVR_OUT_PTR OSVR_DeviceToken device) OSVR_FUNC_NONNULL((1
	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_PLUGINKIT_EXPORT OSVR_ReturnCode	osvrDeviceAsyncInit (OSVR_IN_PTR OSVR_PluginRegContext ctx, OSVR_IN_STRZ const char name, OSVR_OUT_PTR OSVR_DeviceToken device) OSVR_FUNC_NONNULL((1
	Initialize an asynchronous device token. More...

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode	osvrDeviceAsyncInitWithOptions (OSVR_IN_PTR OSVR_PluginRegContext ctx, OSVR_IN_STRZ const char name, OSVR_IN_PTR OSVR_DeviceInitOptions options, OSVR_OUT_PTR OSVR_DeviceToken device) OSVR_FUNC_NONNULL((1
	Initialize an asynchronous device token. More...

Detailed Description

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

Typedef Documentation

§ OSVR_DeviceInitOptions

typedef struct OSVR_DeviceInitObject* OSVR_DeviceInitOptions

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.

§ OSVR_DeviceToken

typedef struct OSVR_DeviceTokenObject* OSVR_DeviceToken

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.

§ OSVR_MessageType

typedef struct OSVR_MessageTypeObject* OSVR_MessageType

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.

Function Documentation

§ osvrDeviceAsyncInit()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceAsyncInit	(	OSVR_IN_PTR OSVR_PluginRegContext	ctx,
		OSVR_IN_STRZ const char *	name,
		OSVR_OUT_PTR OSVR_DeviceToken *	device
	)

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.

§ osvrDeviceAsyncInitWithOptions()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceAsyncInitWithOptions	(	OSVR_IN_PTR OSVR_PluginRegContext	ctx,
		OSVR_IN_STRZ const char *	name,
		OSVR_IN_PTR OSVR_DeviceInitOptions	options,
		OSVR_OUT_PTR OSVR_DeviceToken *	device
	)

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.

§ osvrDeviceCreateInitOptions()

OSVR_PLUGINKIT_EXPORT OSVR_DeviceInitOptions osvrDeviceCreateInitOptions ( OSVR_IN_PTR OSVR_PluginRegContext ctx )

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.

§ osvrDeviceMicrosleep()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceMicrosleep ( OSVR_IN uint64_t microseconds )

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.

§ osvrDeviceRegisterMessageType()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceRegisterMessageType	(	OSVR_IN_PTR OSVR_PluginRegContext	ctx,
		OSVR_IN_STRZ const char *	name,
		OSVR_OUT_PTR OSVR_MessageType *	msgtype
	)

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.

§ osvrDeviceRegisterUpdateCallback()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceRegisterUpdateCallback	(	OSVR_IN_PTR OSVR_DeviceToken	dev,
		OSVR_IN OSVR_DeviceUpdateCallback	updateCallback,
		OSVR_IN_OPT void *userData	OSVR_CPP_ONLY=NULL
	)

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.

§ osvrDeviceSendData()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceSendData	(	OSVR_IN_PTR OSVR_DeviceToken	dev,
		OSVR_IN_PTR OSVR_MessageType	msg,
		OSVR_IN_READS(len) const char *	bytestream,
		OSVR_IN size_t	len
	)

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.

§ osvrDeviceSendJsonDescriptor()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceSendJsonDescriptor	(	OSVR_IN_PTR OSVR_DeviceToken	dev,
		OSVR_IN_READS(len) const char *	json,
		OSVR_IN size_t	len
	)

Submit a JSON self-descriptor string for the device.

Length does not include null terminator.

§ osvrDeviceSendTimestampedData()

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

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.

§ osvrDeviceSyncInit()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceSyncInit	(	OSVR_IN_PTR OSVR_PluginRegContext	ctx,
		OSVR_IN_STRZ const char *	name,
		OSVR_OUT_PTR OSVR_DeviceToken *	device
	)

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.

§ osvrDeviceSyncInitWithOptions()

OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode OSVR_PLUGINKIT_EXPORT OSVR_ReturnCode osvrDeviceSyncInitWithOptions	(	OSVR_IN_PTR OSVR_PluginRegContext	ctx,
		OSVR_IN_STRZ const char *	name,
		OSVR_IN_PTR OSVR_DeviceInitOptions	options,
		OSVR_OUT_PTR OSVR_DeviceToken *	device
	)

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.

Typedefs

Functions

Synchronous Devices

Asynchronous Devices

Detailed Description

Typedef Documentation

§ OSVR_DeviceInitOptions

§ OSVR_DeviceToken

§ OSVR_MessageType

Function Documentation

§ osvrDeviceAsyncInit()

§ osvrDeviceAsyncInitWithOptions()

§ osvrDeviceCreateInitOptions()

§ osvrDeviceMicrosleep()

§ osvrDeviceRegisterMessageType()

§ osvrDeviceRegisterUpdateCallback()

§ osvrDeviceSendData()

§ osvrDeviceSendJsonDescriptor()

§ osvrDeviceSendTimestampedData()

§ osvrDeviceSyncInit()

§ osvrDeviceSyncInitWithOptions()