This is example 1. This example demonstrates the following:

  1. Creating an EyeVec object

  2. Setting up communication with the eyevec-control application

  3. Opening the eye-tracker

  4. Retrieving and printing some information from the eye-tracker

  5. Closing the eye-tracker

  6. Terminating communication with the eyevec-control application

  7. Destroying the EyeVec object

You can find the source files and makefiles of this example and all other examples in the share subdirectory of the SDK after installing. See Preparing the build environment.

For this first example we list the entire file and also provide some instructions for building and running the example program. For the other examples we’ll only highlight the important parts and we do not explain how to build and run.

Source code

Source file: example1.c

/*
 * example1.c
 *
 * Example 1. Initialization and cleanup.
 *
 * This source code is provided in the hope that it will be useful. It comes
 * however without warranty of any kind. In no event shall EyeVec be liable
 * for any claim, damages or loss in connection with the provided information.
 *
 * Copyright (C) 2022-2025  Behavioral Experiment Systems / EyeVec
 *                          <support@eyevec.com>
 */

#include <eyevec/c/eyevec.h> (1)
#include <stdio.h>
#include <stdlib.h>


// Error message print function. This is just for convenience. For the other
// examples you'll find this function in ../utils/utils_output.c.
static void printError(const char* fnc, EyeVecResult err) (2)
{
    const char* msg = eyevec_error_message(err);
    if (!err)
        printf("%s: %s\n", fnc, msg);
    else
        printf("%s: %s (error %d)\n", fnc, msg, err);
}


int main(void)
{
    // Create an idle EyeVec object.
    EyeVec* eyevec = eyevec_create(); (3)

    // Setup communication with the eyevec-control/server application.
    EyeVecResult err = eyevec_initialize(eyevec, true); (4)
    printError("eyevec_initialize()", err);
    if (err) return EXIT_FAILURE;

    // Open the eye-tracker.
    err = eyevec_open(eyevec); (5)
    printError("eyevec_open()", err);


    // Let's retrieve and print the eye-tracker model and serial number.
    char buf[30];
    eyevec_get_model(eyevec, buf, sizeof(buf)); (6)
    err = eyevec_get_error(eyevec);
    if (err)
        printError("eyevec_get_model()", err);
    else
        printf("eyevec_get_model() -> \"%s\"\n", buf);

    eyevec_get_serial(eyevec, buf, sizeof(buf)); (6)
    err = eyevec_get_error(eyevec);
    if (err)
        printError("eyevec_get_serial()", err);
    else
        printf("eyevec_get_serial() -> \"%s\"\n", buf);


    // Close the eye-tracker.
    err = eyevec_close(eyevec); (7)
    printError("eyevec_close()", err);

    // Terminate communication with the eyevec-control/server application.
    err = eyevec_cleanup(eyevec); (8)
    printError("eyevec_cleanup()", err);

    // Destroy the EyeVec object.
    eyevec_destroy(eyevec); (9)
}
1 Include directive for eyevec/c/eyevec.h.
2 Helper function for printing error messages; convenient during debugging.
3 Create EyeVec object.
4 Setup communication with eyevec-control application.
5 Open eye-tracker.
6 Retrieve and print some information.
7 Close eye-tracker.
8 Terminate communication with eyevec-control application.
9 Destroy EyeVec object.
The example programs do not contain proper error handling. In your target application you should obviously handle errors appropriately.

Building the example program

You can compile the example program using the accompanying makefile, assuming you have prepared the build environment properly:

$ make

If all goes well the output will look something like this (shown for Linux):

gcc -std=c17 -c -Wall -W -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations -pthread -I/home/joe/external/x86_64/include  example1.c
gcc -std=c17 -oexample1  -L/home/joe/external/x86_64/lib example1.o -leyevec -lrt

If the compilation or the linking phase fails check the sections Header not found or Link library not found below.

Running the example program

Assuming you have installed the EyeVec user application suite you should be able to run the example program.

Under Linux do:

$ ./example1

Under Windows do:

$ ./example1.exe

If the system complains that it cannot find the shared library (libeyevec.so or libeyevec.dll) then please refer to section Shared library not found below.

Provided the dynamic linking succeeds and you have connected the eye-tracker this will output something like:

eyevec_initialize(): OK
eyevec_open(): OK
eyevec_get_model() -> "EyeVec R2-1k"
eyevec_get_serial() -> "R2-25A204034"
eyevec_close(): OK
eyevec_cleanup(): OK

Tidy up

To clean up after a build do:

$ make clean

Or to clean more thoroughly:

$ make tidy

Errors

Header not found

If the compilation phase fails then you have either not correctly installed the EyeVec SDK or, more likely, the makefile symbol that defines where to find the headers are wrong. You’ll need to revisit Preparing the build environment and Installing the SDK.

Check if the expansion of the makefile symbol EYEVEC_INCDIR points to the directory that contains the eyevec directory (which in turn contains subdirectories c and c++ with the header files).

The expansion of the makefile symbol EYEVEC_INCDIR should make the following include directive valid:

#include <eyevec/c/eyevec.h>

Do not change the include directive.

Link library not found

If the linking phase fails then you have either not correctly installed the EyeVec SDK or, more likely, the makefile symbols that define where to find the link library is wrong. You’ll need to revisit Preparing the build environment and Installing the SDK.

Check if the expansion of the makefile symbol EYEVEC_LIBDIR points to the directory that contains the libeyevec.so (Linux) or libeyevec.dll.a (Windows).

Shared library not found

When starting the example program the operating system will dynamically link the program to the EyeVec client library (i.e. libeyevec.so under Linux, libeyevec.dll under Windows) provided it knows where to find it (see relevant paragraphs in Installing the SDK about this). If the system complains it can’t find the library then try to remedy as follows:

Under Linux define/extend environment variable LD_LIBRARY_PATH to include the location of the libeyevec.so library. For example:

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/joe/external/x86_64/lib

Under Windows copy the libeyevec.dll library to the current directory (or copy it to any other directory in your search path). For example:

$ cp /c/Users/Jane/libraries/bin/libeyevec.dll .