Added Tobii from 4.23 + updated

ThirdParty/GameIntegration/include/tobii_g2om.h

@@ -0,0 +1,970 @@
+/* Copyrighted Tobii AB, 2018. Property of Tobii AB. */
+
+/**
+## 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.
+*/
+
+#ifndef tobii_g2om_h_included
+#define tobii_g2om_h_included
+
+#include <stdint.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef _WIN32
+    #define G2OM_API __declspec( dllimport )
+    #define G2OM_CALL __cdecl
+#elif __GNUC__ >= 4
+    #define G2OM_API __attribute__((visibility("default")))
+    #define G2OM_CALL
+#else
+    #define G2OM_API
+    #define G2OM_CALL
+#endif
+
+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;
+
+typedef struct {
+    uint32_t major;
+    uint32_t minor;
+    uint32_t build_version;
+} g2om_version;
+
+typedef struct g2om_context g2om_context;
+
+typedef struct {
+    float x;
+    float y;
+    float z;
+} g2om_vector;
+
+typedef struct {
+    uint32_t capacity;
+    uint32_t thread_count;
+    uint8_t *license_ptr;
+    uint32_t license_length;
+} g2om_context_create_options;
+
+typedef struct {
+    float data[16];
+} g2om_matrix;
+
+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;
+
+typedef struct {
+    g2om_vector origin;
+    g2om_vector direction;
+} g2om_ray;
+
+typedef struct {
+    g2om_ray ray;
+    uint8_t is_valid;
+} g2om_gaze_ray;
+
+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;
+
+typedef struct {
+    uint8_t is_valid;
+    uint64_t id;
+} g2om_raycast;
+
+typedef struct {
+    g2om_raycast raycast;
+} g2om_raycast_result;
+
+typedef struct {
+    uint64_t id;
+    float score;
+    g2om_gaze_ray adjusted_gaze_ray_world_space;
+} g2om_candidate_result;
+
+typedef enum {
+    G2OM_CORNERS_FLL = 0,    // Front Lower Left
+    G2OM_CORNERS_FUL,        // Front Upper Left
+    G2OM_CORNERS_FUR,        // Front Upper Right
+    G2OM_CORNERS_FLR,        // Front Lower Right
+    G2OM_CORNERS_BLL,        // Back Lower Left
+    G2OM_CORNERS_BUL,        // Back Upper Left
+    G2OM_CORNERS_BUR,        // Back Upper Right
+    G2OM_CORNERS_BLR,        // Back Lower Right
+    G2OM_CORNERS_COUNT
+} g2om_corners;
+
+G2OM_API g2om_result G2OM_CALL g2om_get_version(g2om_version *version_ptr);
+
+G2OM_API g2om_result G2OM_CALL g2om_context_options_init(g2om_context_create_options *options);
+
+G2OM_API g2om_result G2OM_CALL g2om_context_create(g2om_context **context_ptr);
+
+G2OM_API g2om_result G2OM_CALL g2om_context_create_ex(g2om_context **context_ptr, g2om_context_create_options *options);
+
+G2OM_API g2om_result G2OM_CALL g2om_context_destroy(g2om_context **context_ptr);
+
+G2OM_API g2om_result G2OM_CALL 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);
+
+G2OM_API g2om_result G2OM_CALL g2om_get_worldspace_corner_of_candidate(
+    g2om_candidate *candidate_ptr,
+    uint32_t corners_length,
+    g2om_vector *corners_ptr);
+
+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);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // tobii_g2om_h_included
+
+/**
+
+***
+
+## Types
+
+*/
+
+/**
+
+### g2om_result
+
+#### Definition
+
+```c,ignore
+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
+
+```c,ignore
+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
+
+```c,ignore
+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
+
+```c,ignore
+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 to `1`
+ will not spawn any threads and will always execute on the calling thread of `g2om_process()`.
+- `license_ptr` - A pointer to the raw bytes of a license (if any).
+- `license_length` - Length of the license array.
+
+*/
+
+/**
+
+### g2om_vector
+
+#### Definition
+
+```c,ignore
+typedef struct {
+    float x;
+    float y;
+    float z;
+} g2om_vector;
+```
+
+#### Remarks
+
+Our vector definition.
+
+*/
+
+/**
+
+### g2om_matrix
+
+#### Definition
+
+```c,ignore
+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
+
+```c,ignore
+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 space
+- `min_local_space` - A point describing the min point of the object's extent in local space
+- `world_to_local_matrix` - A matrix that transforms a point from world space into object's local space
+- `local_to_world_matrix` - A matrix that transforms a point from object's local space into world space
+
+*/
+
+/**
+
+### g2om_ray
+
+#### Definition
+
+```c,ignore
+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
+
+```c,ignore
+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
+
+```c,ignore
+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
+
+```c,ignore
+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. A `false` 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
+
+```c,ignore
+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
+
+```c,ignore
+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 from `0` to `1`, 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
+
+```c,ignore
+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 a `g2om_version` variable to receive the current version numbers.
+
+### Return value
+
+A `g2om_result` is returned.
+
+#### Example
+
+```c
+#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
+
+```c,ignore
+g2om_result g2om_context_options_init(g2om_context_create_options *options);
+```
+
+#### Arguments
+
+- `options` is a pointer to a `g2om_context_create_options` structure to be initialized.
+
+#### Return value
+
+A `g2om_result` is returned.
+
+#### Example
+
+```c
+#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
+
+```c,ignore
+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 type `g2om_context*` that is, a pointer to a `g2om_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
+
+```c
+#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
+
+```c,ignore
+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 type `g2om_context*` that is, a pointer to a`g2om_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 the `g2om_context_create_options` structure. The structure must be initialized with `g2om_context_options_init()`.
+
+#### Return value
+
+A `g2om_result` is returned.
+
+#### Example
+
+```c
+#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
+
+```c,ignore
+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 valid `g2om_context` instance, that is a pointer
+ to a `g2om_context*`, as created by `g2om_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
+
+```c,ignore
+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 valid `g2om_context` instance as created by calling `g2om_context_create_*()`.
+- `gaze_data_ptr` must be a pointer to a valid `g2om_gaze_data` instance as created by the user.
+- `raycast_ptr` must be a pointer to a valid `g2om_raycast_result` instance as created by the user.
+- `candidates_count` must be a u32 designating the length of the `candidates_ptr` array.
+- `candidates_ptr` must be a pointer to a valid `g2om_candidate` array instance as created by the user.
+- `candidate_results` must be a pointer to a valid `g2om_candidate_result` array instance as created by the
+ user, which will receive it's values from this function. `candidate_results` length **MUST** match
+ `candidates_ptr` length.
+
+#### Return value
+
+A `g2om_result` is returned.
+
+#### Example
+
+```c
+#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
+
+```c,ignore
+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 valid `g2om_candidate` instance as created by the user.
+- `corners_ptr` is a pointer to a `g2om_vector` array, which must be of size 8, to receive the transformed corners.
+
+#### Return value
+
+A `g2om_result` is returned.
+
+#### Example
+
+```c
+#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
+
+```c,ignore
+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
+
+```c
+#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;
+}
+```
+*/

ThirdParty/GameIntegration/include/tobii_gameintegration.h

@@ -0,0 +1,497 @@
+#pragma once
+
+#define TGI_VERSION_MAJOR 4
+#define TGI_VERSION_MINOR 1
+#define TGI_VERSION_REVISION 0
+
+#ifdef _WIN64
+#ifdef _DEBUG
+    const char g_DllName[] = "tobii_gameintegration_x64_d.dll";
+#else
+    const char g_DllName[] = "tobii_gameintegration_x64.dll";
+#endif
+#else
+#ifdef _DEBUG
+    const char g_DllName[] = "tobii_gameintegration_x86_d.dll";
+#else
+    const char g_DllName[] = "tobii_gameintegration_x86.dll";
+#endif
+#endif
+
+#if defined(GAME_INTEGRATION_EXPORT)
+#   define TGI_TYPE_EXPORT __declspec(dllexport)
+#   define TGI_C_EXPORT extern "C" __declspec(dllexport)
+#else
+#   define TGI_TYPE_EXPORT
+#   define TGI_C_EXPORT
+#endif
+
+#include <cstdint>
+#include <assert.h>
+
+namespace TobiiGameIntegration
+{
+    struct ITobiiGameIntegrationApi;
+
+#ifdef __cplusplus
+    extern "C" 
+    {
+#endif
+        // Please, specify a full, real game name, not a code name for the game.
+        // Example: "Assassin's Creed Origins"
+
+        TGI_C_EXPORT ITobiiGameIntegrationApi* __cdecl GetApi(const char* fullGameName, int majorVersion, int minorVersion, int revision);
+        TGI_C_EXPORT ITobiiGameIntegrationApi* __cdecl GetApiDynamic(const char* fullGameName, const char* dllPath, int majorVersion, int minorVersion, int revision);
+        
+#ifdef __cplusplus
+    }
+#endif
+
+    inline ITobiiGameIntegrationApi* GetApi(const char* fullGameName)
+    {
+        return GetApi(fullGameName, TGI_VERSION_MAJOR, TGI_VERSION_MINOR, TGI_VERSION_REVISION);
+    }
+    
+    inline ITobiiGameIntegrationApi* GetApiDynamic(const char* fullGameName, const char* dllPath)
+    {
+        return GetApiDynamic(fullGameName, dllPath, TGI_VERSION_MAJOR, TGI_VERSION_MINOR, TGI_VERSION_REVISION);
+    }
+    
+    inline ITobiiGameIntegrationApi* GetApiDynamic(const char* fullGameName)
+    {
+        return GetApiDynamic(fullGameName, nullptr, TGI_VERSION_MAJOR, TGI_VERSION_MINOR, TGI_VERSION_REVISION);
+    }
+
+    /* Common types */
+
+    struct TGI_TYPE_EXPORT Vector2d
+    {
+        float X;
+        float Y;
+    };
+
+    struct TGI_TYPE_EXPORT Vector3d
+    {
+        float X;
+        float Y;
+        float Z;
+    };
+
+    enum class HMDValidityFlags
+    {
+        LeftEyeIsValid = 1 << 0,
+        RightEyeIsValid = 1 << 1
+    };
+    inline HMDValidityFlags operator |(HMDValidityFlags a, HMDValidityFlags b) { return static_cast<HMDValidityFlags>(static_cast<uint32_t>(a) | static_cast<uint32_t>(b)); }
+    inline HMDValidityFlags& operator |=(HMDValidityFlags &a, HMDValidityFlags b) { return a = a | b; }
+    inline HMDValidityFlags operator &(HMDValidityFlags a, HMDValidityFlags b) { return static_cast<HMDValidityFlags>(static_cast<uint32_t>(a) & static_cast<uint32_t>(b)); }
+    inline HMDValidityFlags& operator &=(HMDValidityFlags& a, HMDValidityFlags b) { return a = a & b; }
+
+    struct TGI_TYPE_EXPORT EyeInfo
+    {
+        EyeInfo() :
+            GazeOriginMM{ 0.0f, 0.0f, 0.0f },
+            GazeDirection{ 0.0f, 0.0f, 0.0f },
+            PupilPosition{ 0.0f, 0.0f },
+            EyeOpenness(0.0f)
+        { }
+
+        Vector3d GazeOriginMM;
+        Vector3d GazeDirection;
+        Vector2d PupilPosition;
+        float EyeOpenness;
+    };
+
+    struct TGI_TYPE_EXPORT HMDGaze
+    {
+        HMDGaze() :
+            Timestamp(0xDEADBEEF),
+            Validity(HMDValidityFlags::LeftEyeIsValid & HMDValidityFlags::RightEyeIsValid),
+            Counter(0),
+            LedMode(0),
+            LeftEyeInfo(),
+            RightEyeInfo()
+        { }
+
+        int64_t Timestamp;
+        HMDValidityFlags Validity;
+        uint32_t Counter;
+        uint32_t LedMode;
+        EyeInfo LeftEyeInfo;
+        EyeInfo RightEyeInfo;
+    };
+
+    struct TGI_TYPE_EXPORT Quaternion
+    {
+        float X;
+        float Y;
+        float Z;
+        float W;
+    };
+
+    struct TGI_TYPE_EXPORT Rectangle
+    {
+        int32_t Left;
+        int32_t Top;
+        int32_t Right;
+        int32_t Bottom;
+    };
+
+    struct TGI_TYPE_EXPORT Dimensions
+    {
+        int32_t Width;
+        int32_t Height;
+    };
+
+    enum UnitType
+    {
+        SignedNormalized = 0,   //  Gaze point, signed normalized, client window bottom, left = (-1, -1), client window top, right = (1, 1)
+        Normalized,             //  Gaze point, unsigned normalized, client window bottom, left = (0, 0), client window top, right = (1, 1)
+        Mm,                     //  Gaze point, mm, client window bottom, left = (0, 0), client window top, right = (window_width_mm, window_height_mm)
+        Pixels,                 //  Gaze point, pixel, client window bottom, left = (0, 0), client window top, right = (window_width_pixels, window_height_pixels)
+        NumberOfUnitTypes       //	Use for looping, array allocation etc 
+    };
+
+
+    /* Eye tracking specific types */
+
+    struct TGI_TYPE_EXPORT GazePoint
+    {
+        int64_t TimeStampMicroSeconds;
+        float X;
+        float Y;
+
+        GazePoint()
+            : TimeStampMicroSeconds(0)
+            , X(0.0f)
+            , Y(0.0f)
+        { }
+    };
+
+    struct TGI_TYPE_EXPORT Rotation
+    {
+        float Yaw;		// Clockwise rotation about the down vector, the angle increases when turning your head right
+        float Pitch;	// Clockwise rotation about the right vector, the angle increases when turning your head up
+        float Roll;		// Clockwise rotation about the forward vector, the angle increases when tilting your head to the right
+
+        Rotation()
+            : Yaw(0.0f)
+            , Pitch(0.0f)
+            , Roll(0.0f)
+        { }
+    };
+
+    struct TGI_TYPE_EXPORT Position
+    {
+        float X;	// Increases when moving your head to the right
+        float Y;	// Increases when moving your head up
+        float Z;	// Increases when moving away from the tracker
+
+        Position()
+            : X(0.0f)
+            , Y(0.0f)
+            , Z(0.0f)
+        { }
+    };
+
+    struct TGI_TYPE_EXPORT Transformation
+    {
+        Rotation Rotation;
+        Position Position;
+
+        Transformation()
+            : Rotation()
+            , Position()
+        { }
+    };
+
+    struct TGI_TYPE_EXPORT HeadPose : Transformation
+    {
+        int64_t TimeStampMicroSeconds;
+
+        HeadPose()
+            : TimeStampMicroSeconds(0)
+        { }
+    };
+
+    enum HeadViewType
+    {
+        None = 0,
+        Direct = 1,
+        Dynamic = 2
+    };
+
+    struct TGI_TYPE_EXPORT SensitivityGradientSettings
+    {
+        float Scale;            // Gradient curve for sensitivity settings
+        float Exponent;
+        float InflectionPoint;
+        float StartPoint;
+        float EndPoint;
+
+        SensitivityGradientSettings()
+            : Scale(1.0f)
+            , Exponent(1.0f)
+            , InflectionPoint(0.5f)
+            , StartPoint(0.0f)
+            , EndPoint(1.0f)
+        {  }
+
+        SensitivityGradientSettings(float scale, float exponent, float inflectionPoint, float startPoint, float endPoint)
+            : Scale(scale),
+            Exponent(exponent),
+            InflectionPoint(inflectionPoint),
+            StartPoint(startPoint),
+            EndPoint(endPoint)
+        { }
+    };
+
+    struct TGI_TYPE_EXPORT HeadViewAutoCenterSettings
+    {
+        bool IsEnabled;
+        float NormalizeFasterGazeDeadZoneNormalized;
+        float ExtendedViewAngleFasterDeadZoneDegrees;
+        float MaxDistanceFromMasterCm;
+        float MaxAngularDistanceDegrees;
+        float FasterNormalizationFactor;
+        float PositionCompensationSpeed;
+        float RotationCompensationSpeed;
+
+        HeadViewAutoCenterSettings()
+            : IsEnabled(true),
+            NormalizeFasterGazeDeadZoneNormalized(0.35f),
+            ExtendedViewAngleFasterDeadZoneDegrees(10.0f),
+            MaxDistanceFromMasterCm(5.0f),
+            MaxAngularDistanceDegrees(15.0f),
+            FasterNormalizationFactor(100.0f),
+            PositionCompensationSpeed(0.01f),
+            RotationCompensationSpeed(0.01f)
+        { }
+    };
+
+    struct TGI_TYPE_EXPORT ExtendedViewSettings
+    {
+        HeadViewType HeadViewType;
+
+        float AspectRatioCorrectionFactor;
+        float HeadViewPitchCorrectionFactor;
+
+        SensitivityGradientSettings GazeViewSensitivityGradientSettings;
+        float GazeViewResponsiveness;
+        float NormalizedGazeViewMinimumExtensionAngle;
+        float NormalizedGazeViewExtensionAngle;
+
+        SensitivityGradientSettings HeadViewSensitivityGradientSettings;
+        float HeadViewResponsiveness;
+        HeadViewAutoCenterSettings HeadViewAutoCenter;
+
+        ExtendedViewSettings()
+            : HeadViewType(HeadViewType::Direct)
+            , AspectRatioCorrectionFactor(1.0f)
+            , HeadViewPitchCorrectionFactor(1.5f)
+            , GazeViewSensitivityGradientSettings(0.5f, 2.25f, 0.8f, 0.0f, 1.0f)
+            , GazeViewResponsiveness(0.5f)
+            , NormalizedGazeViewMinimumExtensionAngle(0.05f) // This is the minimal maximum eview angle from the gaze component. Normalized rotations (so 0.05 => 0.05 * 360 = 18 degrees)
+            , NormalizedGazeViewExtensionAngle(NormalizedGazeViewMinimumExtensionAngle) // This is the maximum extension angle you can achieve with the gaze component.
+            , HeadViewSensitivityGradientSettings(0.65f, 1.25f, 0.5f, 0.0f, 1.0f)
+            , HeadViewResponsiveness(1.0f)
+        
+        { }
+
+        ExtendedViewSettings(const ExtendedViewSettings &other)
+        {
+            *this = other;
+        }
+    };
+
+    // This will generate enum Feature and corresponding FeatureNames array
+#define FOREACH_FEATURE(FEATURE) \
+            FEATURE(AutoPause)\
+            FEATURE(CharacterAwareness)\
+            FEATURE(EnvironmentalAwareness)\
+            FEATURE(EyeContact)\
+            FEATURE(ObjectAwareness)\
+            FEATURE(BungeeZoom)\
+            FEATURE(ZoomAtGaze)\
+            FEATURE(CleanUI)\
+            FEATURE(DirectionalSound)\
+            FEATURE(DynamicDepthOfField)\
+            FEATURE(DynamicLightAdaptation)\
+            FEATURE(FlashlightControl)\
+            FEATURE(PeripheralEffects)\
+            FEATURE(AutoTurn)\
+            FEATURE(ExtendedView)\
+            FEATURE(FreeView)\
+            FEATURE(AimAtGaze)\
+            FEATURE(CoverAtGaze)\
+            FEATURE(EnemyTagging)\
+            FEATURE(InteractAtGaze)\
+            FEATURE(ThrowAtGaze)\
+            FEATURE(TeleportToGaze)\
+            FEATURE(JumpAtGaze)\
+            FEATURE(FireAtGaze)\
+            FEATURE(SecondaryWeaponGaze)\
+            FEATURE(PickUpAtGaze)\
+            FEATURE(SelectAtGaze)\
+            FEATURE(FoveatedRendering)\
+            FEATURE(AvatarEyeMovements)\
+            FEATURE(WheelMenu)\
+            FEATURE(MenuNavigation)\
+            FEATURE(CursorWarp)\
+            FEATURE(CenterAtGaze)\
+
+#define GENERATE_ENUM(ENUM) ENUM,
+#define GENERATE_STRING(STRING) #STRING,
+
+    enum class Feature {
+        FOREACH_FEATURE(GENERATE_ENUM)
+        AMOUNT_OF_FEATURES
+    };
+
+    static char const* FeatureNames[] = {
+        FOREACH_FEATURE(GENERATE_STRING)
+    };
+
+    enum class TrackerType
+    {
+        None = 0,
+        PC,
+        HeadMountedDisplay
+    };
+
+    enum class CapabilityFlags
+    {
+        None = 0,
+        Presence = 1 << 0,
+        Head = 1 << 1,
+        Gaze = 1 << 2,
+        Foveation = 1 << 3,
+        EyeInfo = 1 << 4,
+        HMD = 1 << 5
+    };
+    inline CapabilityFlags operator |(CapabilityFlags a, CapabilityFlags b) { return static_cast<CapabilityFlags>(static_cast<int>(a) | static_cast<int>(b)); }
+    inline CapabilityFlags& operator |=(CapabilityFlags &a, CapabilityFlags b) { return a = a | b; }
+    inline CapabilityFlags operator &(CapabilityFlags a, CapabilityFlags b) { return static_cast<CapabilityFlags>(static_cast<int>(a) & static_cast<int>(b)); }
+    inline CapabilityFlags& operator &=(CapabilityFlags& a, CapabilityFlags b) { return a = a & b; }
+
+    struct TGI_TYPE_EXPORT AimAtGazeFilterSettings
+    {
+        AimAtGazeFilterSettings() :
+            IsEnabled(false),
+            DistanceThreshold(0.1f)
+        {  }
+        
+        bool IsEnabled;
+        float DistanceThreshold;
+    };
+
+    struct TGI_TYPE_EXPORT ResponsiveFilterSettings
+    {
+        ResponsiveFilterSettings() :
+            IsEnabled(false),
+            Responsiveness(0.5f),
+            StickinessDistance(0.1f)
+        {  }
+
+        bool IsEnabled;
+        float Responsiveness;
+        float StickinessDistance;
+    };
+
+    struct TGI_TYPE_EXPORT TrackerInfo
+    {
+        TrackerInfo() :
+            Type(TrackerType::None),
+            Capabilities(CapabilityFlags::None),
+            DisplayRectInOSCoordinates({ 0, 0, 0, 0}),
+            DisplaySizeMm({ 0, 0 }),
+            Url(nullptr),
+            FriendlyName(nullptr),
+            MonitorNameInOS(nullptr),
+            ModelName(nullptr),
+            Generation(nullptr),
+            SerialNumber(nullptr),
+            FirmwareVersion(nullptr),
+            IsAttached(false)
+        { }
+
+        TrackerType Type;
+        CapabilityFlags Capabilities;
+        Rectangle DisplayRectInOSCoordinates;
+        Dimensions DisplaySizeMm;
+        const char* Url;
+        const char* FriendlyName;
+        const char* MonitorNameInOS;
+        const char* ModelName;
+        const char* Generation;
+        const char* SerialNumber;
+        const char* FirmwareVersion;
+        bool IsAttached;
+    };
+
+    struct TGI_TYPE_EXPORT ITrackerController
+    {
+        virtual bool GetTrackerInfo(TrackerInfo& trackerInfo) = 0;
+        virtual bool GetTrackerInfo(const char* url, TrackerInfo& trackerInfo) = 0;
+        virtual void UpdateTrackerInfos() = 0;
+        virtual bool GetTrackerInfos(const TrackerInfo*& trackerInfos, int& numberOfTrackerInfos) = 0;
+        virtual bool TrackHMD() = 0;
+        virtual bool TrackRectangle(const Rectangle& rectangle) = 0;
+        virtual bool TrackWindow(void* windowHandle) = 0;
+        virtual void StopTracking() = 0;
+        virtual bool IsConnected() const = 0;
+        virtual bool IsEnabled() const = 0;
+    };
+
+    struct TGI_TYPE_EXPORT IStreamsProvider
+    {
+        virtual bool GetLatestHeadPose(HeadPose& headPose) = 0;
+        virtual bool GetLatestGazePoint(GazePoint& gazePoint) = 0;
+        virtual int GetGazePoints(const GazePoint*& gazePoints) = 0;
+        virtual int GetHeadPoses(const HeadPose*& headPoses) = 0;
+        virtual bool GetLatestHMDGaze(HMDGaze& latestHMDGaze) = 0;
+        virtual int GetHMDGaze(const HMDGaze*& hmdGaze) = 0;
+        virtual bool IsPresent() = 0;
+        virtual void ConvertGazePoint(const GazePoint& fromGazePoint, GazePoint& toGazePoint, UnitType fromUnit, UnitType toUnit) = 0;
+        
+        virtual void SetAutoUnsubscribeForCapability(CapabilityFlags capability, float timeout) = 0;
+        virtual void UnsetAutoUnsubscribeForCapability(CapabilityFlags capability) = 0;
+    };
+
+    struct TGI_TYPE_EXPORT IExtendedView
+    {
+        virtual Transformation GetTransformation() const = 0;
+        virtual void UpdateSettings(const ExtendedViewSettings& settings) = 0;
+        virtual void UpdateGazeOnlySettings(const ExtendedViewSettings& settings) = 0;
+        virtual void UpdateHeadOnlySettings(const ExtendedViewSettings& settings) = 0;
+        virtual void ResetDefaultHeadPose() = 0;
+    };
+
+    struct TGI_TYPE_EXPORT IFeatures
+    {
+        virtual IExtendedView* GetExtendedView() = 0;
+    };
+
+    struct TGI_TYPE_EXPORT IFilters
+    {
+        virtual const ResponsiveFilterSettings& GetResponsiveFilterSettings() const = 0;
+        virtual void SetResponsiveFilterSettings(ResponsiveFilterSettings settings) = 0;
+        virtual const AimAtGazeFilterSettings& GetAimAtGazeFilterSettings() const = 0;
+        virtual void SetAimAtGazeFilterSettings(AimAtGazeFilterSettings settings) = 0;
+        
+        virtual void GetResponsiveFilterGazePoint(GazePoint& gazePoint) const  = 0;
+        virtual void GetAimAtGazeFilterGazePoint(GazePoint& gazePoint, float &gazePointStability) const = 0;
+    };
+
+    struct TGI_TYPE_EXPORT ITobiiGameIntegrationApi
+    {
+        virtual ITrackerController* GetTrackerController() = 0;
+        virtual IStreamsProvider* GetStreamsProvider() = 0;
+        virtual IFeatures* GetFeatures() = 0;
+        virtual IFilters* GetFilters() = 0;
+
+        virtual bool IsInitialized() = 0;
+        virtual void Update() = 0;
+        virtual void Shutdown() = 0;
+    };
+}