A limited-purpose library for creating client contexts that operate the server in the same thread. More...

Typedefs
typedef struct OSVR_JointClientContextOptsObject *	OSVR_JointClientOpts
	Opaque typedef for options used when starting up a joint client context. More...

Functions
OSVR_JOINTCLIENTKIT_EXPORT OSVR_JointClientOpts	osvrJointClientCreateOptions ()
	Creates an empty OSVR_JointClientOpts. More...

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ClientContext	osvrJointClientInit (const char applicationIdentifier[], OSVR_JointClientOpts opts)
	Initialize the library, starting up a "joint" context that also contains a server. More...

Server configuration actions
Methods that queue up actions to perform on the server when the joint client/server is later created in osvrJointClientInit(). These methods do not perform the actions directly or immediately, and only perform some basic error checking on their inputs: failure in the actions specified may instead be reported later in a failure to create the context.
OSVR_JOINTCLIENTKIT_EXPORT OSVR_ReturnCode	osvrJointClientOptionsAutoloadPlugins (OSVR_JointClientOpts opts)
	Queues up the autoloading of plugins. More...

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ReturnCode	osvrJointClientOptionsLoadPlugin (OSVR_JointClientOpts opts, const char *pluginName)
	Queues up the manual load of a plugin by name.

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ReturnCode	osvrJointClientOptionsInstantiateDriver (OSVR_JointClientOpts opts, const char pluginName, const char driverName, const char *params)
	Queues up the manual instantiation of a plugin/driver by name with optional parameters (JSON).

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ReturnCode	osvrJointClientOptionsAddAlias (OSVR_JointClientOpts opts, const char path, const char source)
	Queues up the manual addition of an alias to the path tree.

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ReturnCode	osvrJointClientOptionsAddAliases (OSVR_JointClientOpts opts, const char *aliases)
	Queues up the manual addition of aliases specified in JSON to the path tree.

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ReturnCode	osvrJointClientOptionsAddString (OSVR_JointClientOpts opts, const char path, const char s)
	Queues up the manual addition of a string element to the path tree.

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ReturnCode	osvrJointClientOptionsTriggerHardwareDetect (OSVR_JointClientOpts opts)
	Queues up a trigger for hardware detection.

Detailed Description

A limited-purpose library for creating client contexts that operate the server in the same thread.

See cautions.

In rare cases, it may be useful to run the server and client in a single process, with their mainloops sharing a single thread. Examples include automated tests, special-purpose apps, or apps on platforms that do not support interprocess communication or multiple threads (in which case no async plugins can be used either). This library exists to permit those limited use cases.

Use of this library may sound appealing for a number of other use cases, but consider carefully, as there's likely a better way to solve the problem. In particular, this is not a good solution for the following:

avoiding having to start the server before your app: there are platform-specific "launch on demand" service techniques that should be used instead. (If they're not yet used in OSVR on the platform you're interested in, file an issue or contribute!)
other desires for simplification: this actually makes the overall user experience more complex, since you're eliminating some of the advantages of OSVR (centralized configuration of hardware-agnostic interfaces used by applications), and taking the responsibility of properly configuring a user's system when they've likely already configured it externally.
seeking to reduce latency due to communication between threads or processes: using this library will almost certainly increase latency, and will decrease your framerate if you don't put it in its own thread (and handle locking, etc. yourself), as you'd then have all the device servicing code right in the "hot path" of your app's main loop, instead of running asynchronously at a much higher rate in a separate thread and process.

Because it transfers the overhead of having to perform configuration to the client application, reduces modularity, and can reduce performance, this API is not recommended except in very specialized situations. (Probably not your situations, that is - and if it turns out that you do actually need this, you can swap it in easily after writing your application the typical way, since the API only differs in the startup period.)

Now that we've covered the warnings...

General usage

The usage pattern is very similar to ClientKit, and most functions you call are actually in ClientKit. The only differences relate to configuring the server that will run jointly:

On startup, you'll usually create a OSVR_JointClientOpts with osvrJointClientCreateOptions(), instead of directly creating an OSVR_ClientContext.
Call the various JointClientKit methods with the OSVR_JointClientOpts you created to queue up server configuration actions.
To get an OSVR_ClientContext, you'll call osvrJointClientInit() with your application identifier (as in ClientKit), also passing in the OSVR_JointClientOpts. (That method takes ownership of the options object and deletes it when finished.)
osvrJointClientInit() will create a special client context containg both a client and a server, then execute the actions you queued in the OSVR_JointClientOpts. If all those complete without exception, you'll receive a OSVR_ClientContext that you can proceed to use as normal with all ClientKit methods. If any errors occur, you'll receive a null value instead.

Typedef Documentation

§ OSVR_JointClientOpts

typedef struct OSVR_JointClientContextOptsObject* OSVR_JointClientOpts

Opaque typedef for options used when starting up a joint client context.

Serves as a queue for configuration operations to perform on the server.

Function Documentation

§ osvrJointClientCreateOptions()

OSVR_JOINTCLIENTKIT_EXPORT OSVR_JointClientOpts osvrJointClientCreateOptions ( )

Creates an empty OSVR_JointClientOpts.

The only way to deallocate this object is to pass it to osvrJointClientInit().

Returns: the options object - if NULL, an error occurred.

§ osvrJointClientInit()

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ClientContext osvrJointClientInit	(	const char	applicationIdentifier[],
		OSVR_JointClientOpts	opts
	)

Initialize the library, starting up a "joint" context that also contains a server.

Parameters

applicationIdentifier	A null terminated string identifying your application. Reverse DNS format strongly suggested.
opts	The configuration options object for starting the joint server operations. Pass NULL/nullptr for default operation: loading of all autoload-enabled plugins, and a hardware detection. If a valid pointer is passed, the enqueued operations will be performed in-order (the default operations will not be performed). Any exceptions thrown will cause the initialization to fail, returning a null context.

Returns: Client context - will be needed for subsequent calls

§ osvrJointClientOptionsAutoloadPlugins()

OSVR_JOINTCLIENTKIT_EXPORT OSVR_ReturnCode osvrJointClientOptionsAutoloadPlugins ( OSVR_JointClientOpts opts )

Queues up the autoloading of plugins.

May only be called once per options object.

Typedefs

Functions

Server configuration actions