Introduction

This is the documentation for the FOVE C++ API.

This API allows client applications to interface with the FOVE runtime system, including headsets, eye tracking, position tracking, and the compositor.

An example of using this API can be found at https://github.com/FoveHMD/FoveCppSample

The C++ API wraps, and includes the FOVE C API. Items within the Fove namespace are part of the wrapper, though many are simply typedefs. Items outside the namespace are part of the C API, though in C++ mode, more features may be added (such as default values for struct members).

The main place to get started is looking at the following classes: Fove::Headset Fove::Compositor

Installation

To use the API, simply drop FoveAPI.h into you project and include it. After that point you will be able to use all capabilities listed here.

To link, simply add the FOVE shared library (or DLL on Windows) to the link libraries for your project.

Requirements

This API requires C++11 or later

Backwards Compatibility

Except where noted in the API, the FOVE system maintains backwards compatibility with old clients. For example, a v0.15.0 client can talk a a v0.16.0 server.

Forwards compatibility is not provided: a client using v1.0.0 wont function on a computer with v0.17.0 installed. The end user will need to update their FOVE version first.

Updates to the patch version (the third number in the version) generally do not affect compatibility. So v1.0.0 and v1.0.1 are considered equivalent as far as compatibility is concerned. Though we may fix bugs that involve regressions in backwards compatbility in a patch version.

ABI compatibility is not kept between different versions of this API. If you update the client library binary, you also need to recompile against the corresponding version of this header. This is something we may consider in the future.

Handling

By policy, every C API function returns an error code, which is from the Fove_ErrorCode.

The common errors for each function are documented, but it's possible for other errors to be returned. In particular, any function may return #Fove_ErrorCode_UnknownError, which indicates an internal bug in the implementation.

The precedence of errors is mostly unspecified, but this is the typical precedence:

API_NotRegistered -> [Connect_NotConnected / Data_NoUpdate] -> All other errors -> None

All getters (functions that start with "get" or "is") return Data_NoUpdate and never Connect_NotConnected. Other functions will never return Data_NoUpdate, but any ones that require a connection can return Connect_NotConnected.

Some getters return a value cached by one of the "fetch" functions. Since the fetch functions also cache an error, these functions return the error as of the last fetch.

Threading

All functions in the C API are thread safe, except where otherwise noted.

Thus, it is safe to call any function(s) from multiple threads simultaneously. However, care should still be taken to avoid race conditions in multi-threaded applications.

For example, if you call a function that needs some registered capability, simultaneously while registering that capability, then you have a race condition. The order of the two operations, and thus the behavior, may change randomly at runtime. You should synchronize the calls or otherwise handle both cases.

The C++ wrapper, for example Object<> and Result<>, do not provide any thread safety themselves. However, insofar as they invoke the C API, they are thread safe. Since the C++ wrapper is made up of brief inline functions, you can easily check any given function.

All getters (functions that start with "get" or "is") return quickly without waiting for network access. It is fine to call them every frame in a frame loop.

Most other functions access the service over a socket, with a small timeout, and thus can block for a small while, especially if the service is not running.

Miscellaneous

Unless otherwise specified, all strings are encoded in UTF-8.