Getting Started : C++

Files

The following files need to be included in your project

File(s)	Purpose
.hpp & .h files from the include directory	C and C++ header files for the API
One of the libraries from lib directory	The Tilt Five NDK support library

Using the Glasses

Service Connection

Most of the operations performed with the glasses are not done directly by the client, but are performed by the Tilt Five™ service on behalf of the client.

The connection to the service is not guaranteed to always be available. Scenarios where the service is unavailable include:

• During client startup there can be a small delay before the connection is established.
• The service is not installed (e.g. User hasn't installed the Tilt Five™ drivers).
• The service may have crashed or been stopped by a user. As such, all queries should anticipate a response of tiltfive::Error::kNoService and retry appropriately (assuming it's a transient condition).

A trivial example of handling this is shown below:

// Convenience function to repeatedly call another function if it returns 'service unavailable'
template <typename T>
auto waitForService(Client& client, const std::function<tiltfive::Result<T>(Client& client)>& func)
    -> tiltfive::Result<T> {
 
    bool waitingForService = false;
    for (;;) {
        auto result = func(client);
        if (result) {
            return result;
        } else if (result.error() != tiltfive::Error::kNoService) {
            return result.error();
        }
 
        std::cout << (waitingForService ? "." : "Waiting for service...") << std::flush;
        waitingForService = true;
        std::this_thread::sleep_for(100_ms);
    }
}

    result = waitForService<void>(*client, printServiceVersion);
    if (!result) {
        std::cerr << "Failed to get service version : " << result << std::endl;
        std::exit(EXIT_FAILURE);
    }

auto printServiceVersion(Client& client) -> tiltfive::Result<void> {
    auto result = client->getServiceVersion();
    if (!result) {
        return result.error();
    }
 
    std::cout << "Service version : " << result << std::endl;
    return tiltfive::kSuccess;
}

Result Wrapper

To avoid using exceptions, most C++ functions return the tiltfive::Result type.

This class wraps the 'real' return type and adds additional error conditions. tiltfive::Result is truthy, so you should first check if the result is valid before using it, after that you dereference the tiltfive::Result to get the 'real' value.

An example of this is shown below:

auto result = fooCall();
if (!result) {
  doSomethingWithTheError(result.error());
} else {
  doSomethingWithTheResult(*result);
}

Operations

Depending on the level of access required to the API, there are one or more setup steps. Details are shown below with example code. Further details of the API are here documented in the Tilt Five™ Native Interface (C++).

Create Client

    // Create the client
    auto client = tiltfive::obtainClient("com.tiltfive.test", "0.1.0", nullptr);
    if (!client) {
        std::cerr << "Failed to create client : " << client << std::endl;
        std::exit(EXIT_FAILURE);
    }
    std::cout << "Obtained client : " << client << std::endl;

System-wide Queries

System-wide queries require nothing more than a client to perform. Most of these operations are querying the service for common parameters such as the service version (tiltfive::Client::getServiceVersion()) and fixed physical parameters (tiltfive::Client::getGameboardSize()).

auto printGameboardDimensions(Client& client) -> tiltfive::Result<void> {
    auto result = client->getGameboardSize(kT5_GameboardType_LE);
    if (!result) {
        return result.error();
    }
 
    float width  = result->viewableExtentPositiveX + result->viewableExtentNegativeX;
    float length = result->viewableExtentPositiveY + result->viewableExtentNegativeY;
    float height = result->viewableExtentPositiveZ;
 
    std::cout << "LE Gameboard size : " << width << "m x " << length << "m x " << height << "m"
              << std::endl;
 
    return tiltfive::kSuccess;
}
 
auto printServiceVersion(Client& client) -> tiltfive::Result<void> {
    auto result = client->getServiceVersion();
    if (!result) {
        return result.error();
    }
 
    std::cout << "Service version : " << result << std::endl;
    return tiltfive::kSuccess;
}

Enumerate & Select Glasses

auto waitForGlasses(Client& client) -> tiltfive::Result<Glasses> {
    std::cout << "Looking for glasses..." << std::flush;
 
    // Loop until we find glasses
    auto glassesList = client->listGlasses();
    if (!glassesList) {
        return glassesList.error();
    }
    while (glassesList->empty()) {
        std::cout << "." << std::flush;
        std::this_thread::sleep_for(100_ms);
 
        // Request a list of the available glasses
        glassesList = client->listGlasses();
        if (!glassesList) {
            return glassesList.error();
        }
    }
 
    // Print out the found glasses
    for (auto& glassesInstance : *glassesList) {
        std::cout << "Found : " << glassesInstance << std::endl;
    }
 
    // Return the first found glasses
    return tiltfive::obtainGlasses(glassesList->front(), client);
}

Non-exclusive Operations

Some glasses operations are available without acquiring exclusive access. These include operations to query stored parameters about glasses such as the IPD (tiltfive::Glasses::getIpd()) and user specified friendly name (tiltfive::Glasses::getFriendlyName()). Additionally, accessing the Wand Stream 'wand stream' does not require an exclusive connection.

    // Get the friendly name for the glasses
    // This is the name that's user set in the Tilt Five™ control panel.
    auto friendlyName = glasses->getFriendlyName();
    if (friendlyName) {
        std::cout << "Obtained friendly name : " << friendlyName << std::endl;
    } else if (friendlyName.error() == tiltfive::Error::kSettingUnknown) {
        std::cerr << "Couldn't get friendly name : Service reports it's not set" << std::endl;
    } else {
        std::cerr << "Error obtaining friendly name : " << friendlyName << std::endl;
    }
 
    // Get the IPD for the glasses
    // This is user set IPD in the Tilt Five™ control panel.
    auto ipd = glasses->getIpd();
    if (ipd) {
        std::cout << "Obtained IPD : " << ipd << "m" << std::endl;
    } else if (ipd.error() == tiltfive::Error::kSettingUnknown) {
        std::cerr << "Couldn't get IPD : Service reports it's not set" << std::endl;
    } else {
        std::cerr << "Error obtaining IPD : " << ipd << std::endl;
        return ipd.error();
    }

Reserve for Exclusive

Other operations require exclusive access before a client can perform them. Only one client can have exclusive access to glasses at a time. Principally, obtaining the current pose (tiltfive::Glasses::getLatestGlassesPose()) and sending frames for rendering (tiltfive::Glasses::sendFrame()) require exclusive access.

Essentially, this is a process of repeatedly calling tiltfive::Glasses::reserve() until the function returns success. This can succeed even if glasses are not fully available (for example due to rebooting). Once the glasses are reserved, then it is time to ensure the glasses are ready for exclusive operations.

Ensure Ready for Exclusive

After a pair of glasses has been reserved, they need to be made fully ready for exclusive operations (e.g., getting the current glasses pose and sending frames) using tiltfive::Glasses::ensureReady() . This may return an error that retry is needed if the glasses are not yet ready. Upon success, the glasses are ready for exclusive operations.

To automate the "reserve and ensure ready" process, use the GlassesConnectionHelper.

        // Wait for exclusive glasses connection
        auto connectionHelper = glasses->createConnectionHelper("Awesome game - Player 1");
        auto connectionResult = connectionHelper->awaitConnection(10000_ms);
        if (connectionResult) {
            std::cout << "Glasses connected for exclusive use" << std::endl;
        } else {
            std::cerr << "Error connecting glasses for exclusive use : " << connectionResult
                      << std::endl;
            return connectionResult.error();
        }

Exclusive Operations

Once an exclusive connection has been established, you may perform exclusive operations such as tiltfive::Glasses::getLatestGlassesPose() and tiltfive::Glasses::sendFrame().

auto readPoses(Glasses& glasses) -> tiltfive::Result<void> {
    auto start = std::chrono::steady_clock::now();
    do {
        auto pose = glasses->getLatestGlassesPose(kT5_GlassesPoseUsage_GlassesPresentation);
        if (!pose) {
            if (pose.error() == tiltfive::Error::kTryAgain) {
                std::cout << "\rPose unavailable - Is gameboard visible?                         ";
            } else {
                return pose.error();
            }
        } else {
            std::cout << "\r" << pose;
        }
    } while ((std::chrono::steady_clock::now() - start) < 10000_ms);
 
    std::cout << "\n";
 
    start = std::chrono::steady_clock::now();
    do {
        auto poses = glasses->getLatestGameboardPoses();
        if (!poses) {
            if (poses.error() == tiltfive::Error::kTryAgain) {
                std::cout << "\rGameboard poses unavailable - Is gameboard visible?                "
                             "         ";
            } else {
                return poses.error();
            }
        } else {
            for (auto& pose : *poses) {
                std::cout << "\r" << pose;
            }
        }
    } while ((std::chrono::steady_clock::now() - start) < 10000_ms);
 
    return tiltfive::kSuccess;
}

Release Exclusive Access

At any point after glasses have been reserved for exclusive use by a client, they can be released so that another client can reserve them exclusively instead without needing to destroy the whole glasses object or context. Use tiltfive::Glasses::release() to restore availability to other clients.

Destruction

tiltfive::Client objects that fall out of scope automatically clean up their own resources. Likewise, tiltfive::Glasses that fall out of scope have their resources release. No explicit release is required in either case.

Note that objects in the C++ binder maintain internal references as necessary. Therefore, even if you no longer have a reference to a tiltfive::Client for example, but do still have a reference tiltfive::Glasses the client will not be released until the glasses object goes out of scope. For further details see Object References below.

Wand Stream

Information about wand events is not delivered separately for each connected wand, but is instead multiplexed into a glasses global stream. Stream events are one of the following (T5_WandStreamEventType):

Event	Meaning
Connect	Glasses have detected a wand has connected.
Disconnect	Glasses have detected a wand disconnection.
Desync	The wand stream has desynchronized, and the client may have missed one or more connection, disconnection or report packets.
Report	A T5_WandReport is available detailing button, analog and positional data for a wand.

Simplistically, accessing the wand stream is done by configuring the stream (tiltfive::Glasses::configureWandStream()) and then repeatedly polling the stream (tiltfive::Glasses::readWandStream()).

To simplify this process, you can use the WandStreamHelper to automate the process and de-multiplex the stream into abstract tiltfive::Wand objects.

Camera Image Stream

Access to the camera image stream requires both providing empty image buffers (tiltfive::Glasses::submitEmptyCamImageBuffer) and polling for filled image buffers (tiltfive::Glasses::getFilledCamImageBuffer).

The typical pattern should be to provide one or more buffers wrapped in a T5_CamImage wrapper (recommended minimum 3 for consistent framerate) via submitEmptyCamImageBuffer. Once provided, they will be filled automatically as images come in from the camera, and getFilledCamImageBuffer should be continually polled. After getFilledCamImageBuffer returns Success, the provided image buffer is valid to be used for image processing. Once processing is finished, the buffer can be resubmitted to the stream using submitEmptyCamImageBuffer again.

If receiving only the most recent image is desired instead, getFilledCamImageBuffer can be continually polled until an error is returned, and the most recent successful return will be the most recent image place into an empty buffer.

Continual polling of the filled image buffers and resubmission of empty buffers is expected to prevent filled buffers from becoming stale as new images come in from the headset.

When finished with the stream, all previously provided buffers should be cancelled via cancelCamImageBuffer before the buffer memory is freed.

Object References

Objects in the C++ binder maintain internal references std::shared_ptr. The relationships are shown below. The direction of the arrow denotes a held reference. For example, a tiltfive::Wand object holds a reference to a tiltfive::WandStreamHelper, which in turn holds a reference to a tiltfive::Glasses and finally to a tiltfive::Client. Dashed lines represent std::weak_ptr.

Helper Classes

All of the functionality of the glasses can be accessed using only tiltfive::Client and tiltfive::Glasses, however many of the calls are blocking and/or require polling. To simplify access to the functionality, there are several additional helper classes to automate these operations.

Helper	Purpose
tiltfive::WandStreamHelper	Monitor the wand event stream, and abstract access to tiltfive::Wand objects
tiltfive::GlassesConnectionHelper	Automate the exclusive connection process which requires repeated calling of tiltfive::Glasses::reserve()
tiltfive::ParamChangeHelper	Automate polling for changes to T5_ParamGlasses / T5_ParamSys and invoke callbacks on a tiltfive::ParamChangeListener subclasses

Using WandStreamHelper

Simplistically, accessing the wand stream is done by configuring the stream (tiltfive::Glasses::configureWandStream()) and then repeatedly polling the stream (tiltfive::Glasses::readWandStream()).

To simplify this process, you can use a tiltfive::WandStreamHelper to automate the process and de-multiplex the stream into abstract tiltfive::Wand objects.

• Obtain a client
• Find glasses
• Invoke tiltfive::Glasses::getWandStreamHelper()
• Invoke tiltfive::WandStreamHelper::listWands() to obtain a std::vector <tiltfive::Wand>
• Invoke tiltfive::Wand::getLatestReport() to get wand reports

The tiltfive::WandStreamHelper automatically configures the stream to match the lifecycle of tiltfive::Wand objects - when no references are held, the stream is automatically stopped and restarted as needed.

Using GlassesConnectionHelper

Connecting the glasses is essentially a process of repeatedly calling tiltfive::Glasses::reserve() until an exclusive connection is established. If the glasses are not fully available (for example due to rebooting), you may receive a reservation for the glasses instead. To automate this process use a tiltfive::GlassesConnectionHelper.

• Obtain a client
• Find glasses
• Invoke tiltfive::Glasses::createConnectionHelper() with glasses specific parameters
• Invoke tiltfive::GlassesConnectionHelper::awaitConnection() to wait for connection

or

• Poll tiltfive::Glasses::getConnectionState() while the glasses are automatically connected.

(new in 1.2.0) After the GlassesConnectionHelper is destroyed, the Glasses object will remain in its current connection state. (This is a change from NDK 1.1.0, where the Glasses would be released on GlassesConnectionHelper destruction). The Glasses will still be automatically released when the Glasses object itself is destroyed.

Using ParamChangeHelper

Some of the parameters may change during operation (for example, the user want to adjust the IPD while using the glasses). To automatically detect changes and trigger a callback, use a tiltfive::ParamChangeHelper.

• Obtain a client.
• Subclass tiltfive::ParamChangeListener to create your listener.
• Create a std::shared_ptr to your listener.
• Invoke tiltfive::Client::createParamChangedHelper() with your shared listener to obtain a std::shared_ptr to a tiltfive::ParamChangeHelper.

At this point you'll be able to receive callbacks for system-wide changes via tiltfive::ParamChangeListener::onSysParamChanged(). To also receive parameter changes for individual glasses:

• Register each new tiltfive::Glasses instance with tiltfive::ParamChangeHelper::registerGlasses().
• De-register tiltfive::Glasses via tiltfive::ParamChangeHelper::deregisterGlasses() when you no longer wish to be notified about parameter changes for that instance of tiltfive::Glasses. At this point you'll also receive callbacks for glasses specific changes via tiltfive::ParamChangeListener::onGlassesParamChanged().