Getting Started : C

Project Setup

The following files need to be included in your project

File(s)	Purpose
.h files from the include directory	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 T5_ERROR_NO_SERVICE and retry appropriately (assuming it's a transient condition).

A trivial example of handling this is shown below:

    bool waiting = false;
    for (;;) {
        char serviceVersion[T5_MAX_STRING_PARAM_LEN];
        size_t bufferSize = T5_MAX_STRING_PARAM_LEN;
        err               = t5GetSystemUtf8Param(
            t5ctx, kT5_ParamSys_UTF8_Service_Version, serviceVersion, &bufferSize);
        if (!err) {
            printf("Service version : %s\n", serviceVersion);
            break;
        }
 
        if (err == T5_ERROR_NO_SERVICE) {
            if (!waiting) {
                printf("Waiting for service...\n");
                waiting = true;
            }
        } else {
            printf("Error getting service version : %s\n", t5GetResultMessage(err));
            exit(EXIT_FAILURE);
        }
    }

Threading

All calls are blocking, and their thread safety is documented on each call. Generally, calls are grouped into a number of groups. From each group only one function should should be called concurrently. Calls may be made to functions in different groups concurrently. Additionally, some calls require specific threads (such as graphics related functions like t5InitGlassesGraphicsContext() and t5SendFrameToGlasses()).

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 Context

    T5_ClientInfo clientInfo = {
        .applicationId      = "com.MyCompany.MyApplication",
        .applicationVersion = "1.0.0",
        .sdkType            = 0,
        .reserved           = 0,
    };
 
    T5_Context t5ctx;
    T5_Result err = t5CreateContext(&t5ctx, &clientInfo, 0);
    if (err) {
        printf("Failed to create context\n");
    }

Release Context

The context should be released after it's finished with

    t5DestroyContext(&t5ctx);

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 (t5GetSystemUtf8Param() and fixed physical parameters (t5GetGameboardSize()).

        T5_GameboardSize gameboardSize;
        err = t5GetGameboardSize(t5ctx, kT5_GameboardType_LE, &gameboardSize);
        if (err) {
            printf("Failed to get gameboard size\n");
        } else {
            printf("LE Gameboard size : %fm x %fm x %fm\n",
                   gameboardSize.viewableExtentPositiveX + gameboardSize.viewableExtentNegativeX,
                   gameboardSize.viewableExtentPositiveY + gameboardSize.viewableExtentNegativeY,
                   gameboardSize.viewableExtentPositiveZ);
        }

Enumerate Glasses

    for (;;) {
        size_t bufferSize = GLASSES_BUFFER_SIZE;
        char glassesListBuffer[GLASSES_BUFFER_SIZE];
        err = t5ListGlasses(t5ctx, glassesListBuffer, &bufferSize);
        if (!err) {
            size_t glassesCount = 0;
 
            const char* buffPtr  = glassesListBuffer;
            size_t remainingSize = bufferSize;
            for (;;) {
                // Get the length of the string and exit if we've read the
                // terminal string (Zero length)
                size_t stringLength = strnlen(buffPtr, remainingSize);
                if (stringLength == 0) {
                    break;
                } else if (stringLength == remainingSize) {
                    // no null terminator encountered in the provided buffer!
                    printf("Warning: list may be missing null terminator");
                    break;
                }
 
                fprintf(stderr, "Glasses : %s\n", buffPtr);
                glassesCount++;
 

At this point buffPtr contains a glasses identifier suitable for Create Glasses 'creating/selecting glasses'.

 
                // Advance through the returned values
                buffPtr += stringLength + 1;
                remainingSize -= stringLength + 1;
                assert(buffPtr <= (glassesListBuffer + bufferSize));
            }
 
            printf("Listed glasses [%zu found]\n", glassesCount);
            break;
        }
 
        if (err == T5_ERROR_NO_SERVICE) {
            if (!waiting) {
                printf("Waiting for service...\n");
                waiting = true;
            }
        } else {
            printf("Error listing glasses : %s\n", t5GetResultMessage(err));
            exit(EXIT_FAILURE);
        }
    }

Create Glasses

Creating glasses handles requires a hardware identifier (id below) for the glasses as well as some information about the client.

 
    // CREATE GLASSES
    T5_Glasses glassesHandle;
    T5_Result err = t5CreateGlasses(t5ctx, id, &glassesHandle);
    if (err) {
        printf("Error creating glasses '%s' : %s\n", id, t5GetResultMessage(err));
        return;
    } else {
        printf("Created glasses   : '%s'\n", id);
    }

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 (t5GetGlassesFloatParam()) and user specified friendly name (t5GetGlassesUtf8Param()). Additionally, accessing the Wand Stream 'wand stream' does not require an exclusive connection.

T5_Result endlesslyWatchSettings(T5_Glasses glassesHandle, const char* id) {
    T5_Result err;
 
    printf("Watching for changes to settings... (forever)\n");
    for (;;) {
        uint16_t count = PARAM_BUFFER_SIZE;
        T5_ParamGlasses paramBuffer[PARAM_BUFFER_SIZE];
        err = t5GetChangedGlassesParams(glassesHandle, paramBuffer, &count);
        if (err) {
            printf("Error getting changed params for '%s' : %s\n", id, t5GetResultMessage(err));
            return err;
        }
 
        // Get the values of the changed params
        for (int i = 0; i < count; i++) {
            switch (paramBuffer[i]) {
                case kT5_ParamGlasses_Float_IPD: {
                    double value = 0.0;
                    err          = t5GetGlassesFloatParam(glassesHandle, 0, paramBuffer[i], &value);
                    if (err) {
                        printf("Error getting changed IPD for '%s' : %s\n",
                               id,
                               t5GetResultMessage(err));
                        return err;
                    }
 
                    printf("IPD changed for '%s' : %f\n", id, value);
                } break;
 
                case kT5_ParamGlasses_UTF8_FriendlyName: {
                    char buffer[T5_MAX_STRING_PARAM_LEN];
                    size_t bufferSize = T5_MAX_STRING_PARAM_LEN;
                    err               = t5GetGlassesUtf8Param(
                        glassesHandle, paramBuffer[i], 0, buffer, &bufferSize);
                    if (err) {
                        printf("Error getting changed friendly name for '%s' : %s\n",
                               id,
                               t5GetResultMessage(err));
                        return err;
                    }
 
                    printf("Friendly name changed for '%s' : '%s'\n", id, buffer);
                } break;
 
                default:
                    // Ignore other parameters
                    break;
            }
        }
    }
}

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 (t5GetGlassesPose()) and sending frames for rendering (t5SendFrameToGlasses()) require exclusive access.

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

    err = t5ReserveGlasses(glassesHandle, "My Awesome Application");
    if (err) {
        printf("Error acquiring glasses '%s': %s\n", id, t5GetResultMessage(err));
        return;
    }

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 t5EnsureGlassesReady(). 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.

    // ENSURE GLASSES ARE READY
    for (;;) {
        err = t5EnsureGlassesReady(glassesHandle);
        if (err) {
            if (err == T5_ERROR_TRY_AGAIN) {
                // A non-sample program would probably sleep here or retry on another frame pass.
                continue;
            }
            printf("Error ensure glasses ready '%s': %s\n", id, t5GetResultMessage(err));
            return;
        }
 
        printf("Glasses ready     : '%s'\n", id);
        break;
    }

Exclusive Operations

Once an exclusive connection has been established, you may perform exclusive operations such as t5GetGlassesPose() and t5SendFrameToGlasses().

void getPoses(T5_Glasses glassesHandle) {
    T5_Result err;
    T5_GlassesPose pose;
    T5_GameboardPose gameboardPoses[3];
 
    printf("Getting some poses");
 
    bool waiting = false;
    for (int i = 0; i < 1000; i++) {
        err = t5GetGlassesPose(glassesHandle, kT5_GlassesPoseUsage_GlassesPresentation, &pose);
        if (err) {
            if (err == T5_ERROR_TRY_AGAIN) {
                if (!waiting) {
                    printf("\nWaiting...");
                    fflush(stdout);
                } else {
                    printf(".");
                    fflush(stdout);
                }
                SLEEP(100);
                i--;
                waiting = true;
                continue;
            } else {
                printf("Failed to get pose : %s\n", t5GetResultMessage(err));
                return;
            }
        }
 
        uint16_t count = 3;
        err            = t5GetGameboardPoses(glassesHandle, gameboardPoses, &count);
        if (err) {
            if (err == T5_ERROR_TRY_AGAIN) {
                if (!waiting) {
                    printf("\nWaiting for gameboard poses...");
                    fflush(stdout);
                } else {
                    printf(".");
                    fflush(stdout);
                }
                SLEEP(100);
                i--;
                waiting = true;
                continue;
            } else {
                printf("Failed to get gameboard poses : %s\n", t5GetResultMessage(err));
                return;
            }
        }
 
        waiting = false;
 
        printf("\nGLASSES POSE : [%lu] (Board:%s) "
               "[%6.4f, %6.4f, %6.4f] [%6.4f, %6.4f, %6.4f, %6.4f]",
               pose.timestampNanos,
               gameboardTypeString(pose.gameboardType),
               pose.posGLS_STAGE.x,
               pose.posGLS_STAGE.y,
               pose.posGLS_STAGE.z,
               pose.rotToGLS_STAGE.w,
               pose.rotToGLS_STAGE.x,
               pose.rotToGLS_STAGE.y,
               pose.rotToGLS_STAGE.z);
 
        printf("\nPRIMARY GAMEBOARD POSE : [%lu] (Board:%s) "
               "[%6.4f, %6.4f, %6.4f] [%6.4f, %6.4f, %6.4f, %6.4f]",
               gameboardPoses[0].timestampNanos,
               gameboardTypeString(gameboardPoses[0].gameboardType),
               gameboardPoses[0].posBOARD_STAGE.x,
               gameboardPoses[0].posBOARD_STAGE.y,
               gameboardPoses[0].posBOARD_STAGE.z,
               gameboardPoses[0].rotToBOARD_STAGE.w,
               gameboardPoses[0].rotToBOARD_STAGE.x,
               gameboardPoses[0].rotToBOARD_STAGE.y,
               gameboardPoses[0].rotToBOARD_STAGE.z);
 
        SLEEP(16);
    }
 
    printf("\n");
}

Release Exclusive Access

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

    // RELEASE THE GLASSES
    t5ReleaseGlasses(glassesHandle);

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 (t5ConfigureWandStreamForGlasses()) and then repeatedly polling the stream (t5ReadWandStreamForGlasses()).

    if (count > 0) {
        // Enable wand stream
        T5_WandStreamConfig config;
        config.enabled = true;
        err            = t5ConfigureWandStreamForGlasses(glassesHandle, &config);
        if (err) {
            printf("Failed to enable stream : %s\n", t5GetResultMessage(err));
            return;
        }
 
        T5_WandStreamEvent event;
        for (int i = 0; i < 100; i++) {
            err = t5ReadWandStreamForGlasses(glassesHandle, &event, 100);
            if (err) {
                if (err == T5_TIMEOUT) {
                    continue;
                }
 
                printf("Failed to read stream : %s\n", t5GetResultMessage(err));
                return;
            }
 
            switch (event.type) {
                case kT5_WandStreamEventType_Connect:
                    printf("WAND EVENT : CONNECT [%u]\n", event.wandId);
                    break;
 
                case kT5_WandStreamEventType_Disconnect:
                    printf("WAND EVENT : DISCONNECT [%u]\n", event.wandId);
                    break;
 
                case kT5_WandStreamEventType_Desync:
                    printf("WAND EVENT : DESYNC [%u]\n", event.wandId);
                    break;
 
                case kT5_WandStreamEventType_Report:
                    printf("WAND EVENT : REPORT [%u] %fx%f\n",
                           event.wandId,
                           event.report.stick.x,
                           event.report.stick.y);
                    break;
            }
        }
 
        // Disable wand stream
        config.enabled = false;
        err            = t5ConfigureWandStreamForGlasses(glassesHandle, &config);
        if (err) {
            printf("Failed to disable stream : %s\n", t5GetResultMessage(err));
            return;
        }
    }