API reference
tobii_g2om.h
The tobii_g2om.h header file collects the core API functions of the Tobii G2OM library. It contains functions to initialize the API and process data to get a most likely candidate result.
The API documentation includes example code snippets that show the use of each function, they don’t necessarily describe the best practice in which to use the api. For more in-depth example of the best practices, see the examples that are supplied together with the G2OM library.
G2OM has no processes running in background, zero runtime allocations and enables full control over the amount of threads used internally.
Types
g2om_result
Definition
typedef enum {
G2OM_RESULT_OK = 0,
G2OM_RESULT_NULL_POINTER_PASSED = -1,
G2OM_RESULT_INTERNAL_ERROR = -2,
G2OM_RESULT_THREAD_POOL_ERROR = -3,
G2OM_RESULT_INDEX_OUT_OF_BOUNDS = -4,
G2OM_RESULT_INTERNAL_CONVERSION_ERROR = -5,
G2OM_RESULT_LOG_FILE_ERROR = -6,
G2OM_RESULT_NOT_PERMITTED_BY_LICENSE = -7,
G2OM_RESULT_LICENSE_INVALID = -8,
G2OM_RESULT_NOT_IMPLEMENTED = -9,
G2OM_RESULT_CAPACITY_EXCEEDED = -10,
G2OM_RESULT_CUSTOM_ALLOCATOR_NOT_SET_FIRST = -11
} g2om_result;
Remarks
The g2om_result
type is returned by every g2om_
call. It is used to signal success, or the
cause of an error. The following variants can be observed:
G2OM_RESULT_OK
- The call was generally successful.G2OM_RESULT_NULL_POINTER_PASSED
- A null pointer was passed at any position.G2OM_RESULT_INTERNAL_ERROR
- This should never happen. If you observe this result please contact support.G2OM_RESULT_THREAD_POOL_ERROR
- There was a problem creating the requested number of threads.G2OM_RESULT_INDEX_OUT_OF_BOUNDS
- The library tried to access an element past its length. Make sure the passed pointers and lengths match.G2OM_RESULT_INTERNAL_CONVERSION_ERROR
- This should never happen. If you observe this result please contact support.G2OM_RESULT_LOG_FILE_ERROR
- When debug mode was enabled and the log file could not be written.G2OM_RESULT_NOT_PERMITTED_BY_LICENSE
- When the current license does not allow the requested operation.G2OM_RESULT_LICENSE_INVALID
- If an invalid or corrupted license is passed.G2OM_RESULT_NOT_IMPLEMENTED
- This should never happen for public versions. If you observe this result please contact support.G2OM_RESULT_CAPACITY_EXCEEDED
- If attempting to classify more objects at once than the provisioned capacity.G2OM_RESULT_CUSTOM_ALLOCATOR_NOT_SET_FIRST
- If trying to set the custom allocator too late.
g2om_version
Definition
typedef struct {
uint32_t major;
uint32_t minor;
uint32_t build_version;
} g2om_version;
Remarks
When invoking g2om_get_version()
, this struct will be filled.
g2om_context
Definition
typedef struct g2om_context g2om_context;
Remarks
An opaque struct for internal use. This will be created by g2om_context_create()
or g2om_context_create_ex()
and must be passed via pointer to most function calls.
g2om_context_create_options
Definition
typedef struct {
uint32_t capacity;
uint32_t thread_count;
uint8_t *license_ptr;
uint32_t license_length;
} g2om_context_create_options;
Remarks
When invoking g2om_context_create_ex()
this specifies how G2OM should behave. The fields used
are:
capacity
- How many concurrently existing objects G2OM should be able to handle.thread_count
- When processing, how many parallel threads should be used. Setting this to1
will not spawn any threads and will always execute on the calling thread ofg2om_process()
.license_ptr
- A pointer to the raw bytes of a license (if any).license_length
- Length of the license array.
g2om_vector
Definition
typedef struct {
float x;
float y;
float z;
} g2om_vector;
Remarks
Our vector definition.
g2om_matrix
Definition
typedef struct {
float data[16];
} g2om_matrix;
Remarks
Our matrix definition is identical to what Unity have, see Unity Matrix4x4.
Memory layout (column major):
c0 | c1 | c2 | c3 | |
---|---|---|---|---|
r0 | m00 | m10 | m20 | m30 |
r1 | m01 | m11 | m21 | m31 |
r2 | m02 | m12 | m22 | m32 |
r3 | m03 | m13 | m23 | m33 |
Data is stored in memory: m00, m01, m02, m03 .. m33
g2om_candidate
Definition
typedef struct {
uint64_t id;
g2om_vector max_local_space;
g2om_vector min_local_space;
g2om_matrix world_to_local_matrix;
g2om_matrix local_to_world_matrix;
} g2om_candidate;
Remarks
One object in the current scene that might or might not be gazed upon. This is input to
g2om_process()
. The fields used are:
id
- A user-defined ID of the object to track.max_local_space
- A point describing the max point of the object’s extent in local spacemin_local_space
- A point describing the min point of the object’s extent in local spaceworld_to_local_matrix
- A matrix that transforms a point from world space into object’s local spacelocal_to_world_matrix
- A matrix that transforms a point from object’s local space into world space
g2om_ray
Definition
typedef struct {
g2om_vector origin;
g2om_vector direction;
} g2om_ray;
Remarks
This is a ray that has an origin
from the ray was shot, and a direction
towards which it
was shot.
origin
- The origin of the ray.direction
- The direction of the ray.
g2om_gaze_ray
Definition
typedef struct {
g2om_ray ray;
uint8_t is_valid;
} g2om_gaze_ray;
Remarks
This is gaze ray as returned by an eye tracker. In addition to the ray data, it also contains a validity flag. The validity indicates whether the eye tracker thinks this ray was valid.
The ray must be set in world space coordinates.
ray
- The ray as returned by the eye tracker, converted to world space.is_valid
- The validity flag as reported by the eye tracker.
g2om_gaze_data
Definition
typedef struct {
float timestamp_in_s;
g2om_gaze_ray gaze_ray_world_space;
g2om_vector camera_up_direction_world_space;
g2om_vector camera_right_direction_world_space;
} g2om_gaze_data;
Remarks
Represents all the gaze data as returned from the eye tracker. The gaze data must be converted to world space coordinates.
timestamp_in_s
- Time stamp as reported by the eye tracker converted to seconds. Note that the absolute time is irrelevant, but the relative time passed in two consecutive invocations is important.gaze_ray_world_space
- The eye data as reported by the eye tracker.camera_up_direction_world_space
- The cameras upwards direction in world space coordinates.camera_right_direction_world_space
- The cameras rightwards direction in world space coordinates.
g2om_raycast
Definition
typedef struct {
uint8_t is_valid;
uint64_t id;
} g2om_raycast;
Remarks
The result of a single ray cast.
is_valid
- If the ray cast data is actually valid. Afalse
value means for example that the eye tracker did not produce a gaze ray this frame, or that the gaze ray did not hit any object.id
- The ID of the object that was hit by the ray cast.
g2om_raycast_result
Definition
typedef struct {
g2om_raycast raycast;
} g2om_raycast_result;
Remarks
The result of ray cast by the current gaze data.
raycast
- Result of raycasting the world gaze ray in game engine.
g2om_candidate_result
Definition
typedef struct {
uint64_t id;
float score;
g2om_gaze_ray adjusted_gaze_ray_world_space;
} g2om_candidate_result;
Remarks
For each object returned by g2om_process()
the following fields will be set.
id
- The user defined ID of the object this struct describes.score
- The score of this object. As of today this is almost a probability value, in that it ranges from0
to1
, with a higher value indicating a higher likelihood of being selected. A value of 0 means the object has not been selected.adjusted_gaze_ray_world_space
- The fused left- and right-eye data adjusted to hit the closest point on the object.
Functions
g2om_get_version()
Get the current version of the API.
Definition
g2om_result g2om_get_version(g2om_version *version_ptr);
Remarks
g2om_get_version()
can be used to query the version of the tobii_g2om
library currently used.
Arguments
version_ptr
is a pointer to ag2om_version
variable to receive the current version numbers.
Return value
A g2om_result
is returned.
Example
#include <tobii/tobii_g2om.h>
#include <stdio.h>
int main()
{
g2om_version version;
g2om_result result = g2om_get_version( &version );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
return 0;
}
g2om_context_options_init()
When using g2om_context_options_init
, this function initializes the g2om_context_create_options
structure to default values.
Definition
g2om_result g2om_context_options_init(g2om_context_create_options *options);
Arguments
options
is a pointer to ag2om_context_create_options
structure to be initialized.
Return value
A g2om_result
is returned.
Example
#include <tobii/tobii_g2om.h>
#include <stdio.h>
int main()
{
g2om_context_create_options options;
g2om_result result = g2om_context_options_init( &options );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
return 0;
}
g2om_context_create()
Initializes a G2OM instance with default parameters. This is a wrapper function around
g2om_context_create_ex()
.
Definition
g2om_result g2om_context_create(g2om_context **context_ptr);
Remarks
For details, please see g2om_context_create_ex()
.
Arguments
context_ptr
must be a pointer to a variable of the typeg2om_context*
that is, a pointer to ag2om_context
pointer. This variable will be filled in with a pointer to the created instance. It is an opaque type, and only its declaration is available in the API.
Return value
A g2om_result
is returned.
Example
#include <tobii/tobii_g2om.h>
#include <stdio.h>
int main()
{
g2om_context* context;
g2om_result result = g2om_context_create( &context );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
result = g2om_context_destroy( &context );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
return 0;
}
g2om_context_create_ex()
Initializes a G2OM instance in extended mode. It is possible to have multiple G2OM instances at one time.
Definition
g2om_result g2om_context_create_ex(g2om_context **context_ptr, g2om_context_create_options *options);
Remarks
Before any other API function can be invoked that accepts a context
parameter the API needs to be
set up before use. The functions g2om_context_create()
and g2om_context_create_ex()
serve this purpose.
They allocate memory and set up internal data structures.
The resulting g2om_context
instance can then be passed explicitly to most functions.
Arguments
context_ptr
- Must be a pointer to a variable of the typeg2om_context*
that is, a pointer to ag2om_context
pointer. This variable will be filled in with a pointer to the created instance. It is an opaque type, and only its declaration is available in the API.options
- A pointer to theg2om_context_create_options
structure. The structure must be initialized withg2om_context_options_init()
.
Return value
A g2om_result
is returned.
Example
#include <tobii/tobii_g2om.h>
#include <stdio.h>
int main()
{
g2om_context* context;
g2om_context_create_options options;
g2om_result result = g2om_context_options_init(&options);
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
options.capacity = 5;
options.thread_count = 1;
result = g2om_context_create_ex( &context, &options);
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
result = g2om_context_destroy( &context );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
return 0;
}
g2om_context_destroy()
Destroy the G2OM instance.
Definition
g2om_result g2om_context_destroy(g2om_context **context_ptr);
Remarks
When creating an instance with g2om_context_create()
or g2om_context_create_ex()
, some system resources are acquired. When finished
using the API (typically during the shutdown process), g2om_context_destroy()
should be called to destroy
the instance and ensure that those resources are released. The function g2om_context_destroy()
must only be called if the g2om_context_create_*
function completed successfully.
Arguments
context_ptr
must be a pointer to a pointer to a validg2om_context
instance, that is a pointer to ag2om_context*
, as created byg2om_context_create_*()
.
Return value
A g2om_result
is returned.
Example
See g2om_context_create()
.
g2om_process()
Takes gaze data, information about objects hit by raycasts and candidates (gaze aware objects) and sends back a result for each candidate.
Definition
g2om_result g2om_process(
g2om_context *context_ptr,
g2om_gaze_data *gaze_data_ptr,
g2om_raycast_result *raycast_ptr,
uint32_t candidates_count,
g2om_candidate *candidates_ptr,
g2om_candidate_result *candidate_results);
Remarks
G2OM does not do any kind of background processing. This means that in order to receive any results
from the API, the user application needs to manually initiate the process, and this is done by
calling g2om_process()
. The recommended way is to call it directly from
the users update loop before the result is needed and at the same rate as the user application will
use it.
This function is guaranteed not to allocate.
Arguments
context_ptr
must be a pointer to a validg2om_context
instance as created by callingg2om_context_create_*()
.gaze_data_ptr
must be a pointer to a validg2om_gaze_data
instance as created by the user.raycast_ptr
must be a pointer to a validg2om_raycast_result
instance as created by the user.candidates_count
must be a u32 designating the length of thecandidates_ptr
array.candidates_ptr
must be a pointer to a validg2om_candidate
array instance as created by the user.candidate_results
must be a pointer to a validg2om_candidate_result
array instance as created by the user, which will receive it’s values from this function.candidate_results
length MUST matchcandidates_ptr
length.
Return value
A g2om_result
is returned.
Example
#include <tobii/tobii_g2om.h>
#include <stdio.h>
int main()
{
g2om_context* context;
g2om_result result = g2om_context_create( &context );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
// Get this data from your eye tracker:
g2om_gaze_data gaze_data = { 0 };
// Fill with data from ray casting in your game engine with gaze ray
// should only be valid if object hit was gazeaware / g2om_candidate
g2om_raycast_result raycast_result;
// fill with candidates/objects from your game which should be gazeaware.
g2om_candidate candidate = { 0 };
g2om_candidate candidates[1] = {
candidate
};
g2om_candidate *candidates_ptr = candidates;
// this value will be filled by g2om_process
g2om_candidate_result candidate_result = { 0 };
// this array has to be the same size as candidates.
g2om_candidate_result candidate_results[1] = {
candidate_result
};
g2om_candidate_result *candidate_results_ptr = candidate_results;
uint32_t candidate_count = 1;
uint32_t result_count = 1;
if (result_count != candidate_count) {
printf("Mismatch in array lengths %i %i !", result_count, candidate_count);
}
result = g2om_process( context, &gaze_data, &raycast_result, candidate_count, candidates_ptr, candidate_results_ptr );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
// --> use the results/winner here, e.g.: <--
// g2om_candidate_result winner = candidate_results[0]; // the results are sorted, so the first element is the highest scoring.
// printf("%ju has gaze focus.", winner.id);
result = g2om_context_destroy( &context );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
return 0;
}
g2om_get_worldspace_corner_of_candidate()
Transforms the corner points of the provided candidate’s AABB to worldspace, and output the resulting 8 corners.
Definition
g2om_result g2om_get_worldspace_corner_of_candidate(
g2om_candidate *candidate_ptr,
uint32_t corners_length,
g2om_vector *corners_ptr);
Remarks
g2om_get_worldspace_corner_of_candidate()
can be used to debug. It’s use is to make sure that
the matrices used to transform to and from worldspace are correct.
Arguments
candidate_ptr
must be a pointer to a validg2om_candidate
instance as created by the user.corners_ptr
is a pointer to ag2om_vector
array, which must be of size 8, to receive the transformed corners.
Return value
A g2om_result
is returned.
Example
#include <tobii/tobii_g2om.h>
#include <stdio.h>
int main()
{
// Made up information
g2om_candidate candidate = {0};
uint32_t number_of_corners = G2OM_CORNERS_COUNT;
g2om_vector corners[G2OM_CORNERS_COUNT];
g2om_result result = g2om_get_worldspace_corner_of_candidate( &candidate, number_of_corners, corners );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
return 0;
}
g2om_get_candidate_search_pattern()
Gets an optimized search pattern rays to be used to find candidates.
Definition
G2OM_API g2om_result G2OM_CALL g2om_get_candidate_search_pattern(
g2om_context *context_ptr,
g2om_gaze_data *gaze_data_ptr,
uint32_t number_of_rays,
g2om_gaze_ray *mutated_rays_ptr,
);
Remarks
This only gets the rays. Finding the candidates has to be done by the application itself.
Arguments
TODO!
Return value
A g2om_result
is returned.
Example
#include <tobii/tobii_g2om.h>
#include <stdio.h>
#define number_of_rays 9
int main()
{
g2om_context* context;
g2om_result result = g2om_context_create( &context );
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
g2om_gaze_data gaze_data = {0};
g2om_gaze_ray search_pattern[number_of_rays];
result = g2om_get_candidate_search_pattern(context, &gaze_data, number_of_rays, search_pattern);
if( result != G2OM_RESULT_OK ) {
printf("Operation failed with error code: %d\n", result);
return result;
}
return 0;
}