Fove SDK  v0.16.0
Classes | Macros | Typedefs | Enumerations | Functions
FoveAPI.h File Reference

Complete self-contained FOVE API definition. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
Include dependency graph for FoveAPI.h:

Classes

struct  Fove_AdapterId
 Struct used to identify a GPU adapter (Windows only) More...
 
struct  Fove_BitmapImage
 A 2D bitmap image. More...
 
struct  Fove_Buffer
 A generic memory buffer. More...
 
struct  Fove_CompositorLayer
 Struct used to store information about an existing compositor layer (after it is created) More...
 
struct  Fove_CompositorLayerCreateInfo
 Struct used to define the settings for a compositor client. More...
 
struct  Fove_CompositorLayerEyeSubmitInfo
 Struct used to conglomerate the texture settings for a single eye, when submitting a given layer. More...
 
struct  Fove_CompositorLayerSubmitInfo
 Struct used to conglomerate the texture settings when submitting a given layer. More...
 
struct  Fove_CompositorTexture
 Base class of API-specific texture classes. More...
 
struct  Fove_DX11Texture
 Struct used to submit a DirectX 11 texture. More...
 
struct  Fove_GazeConvergenceData
 Struct to represent the vector pointing where the user is looking at. More...
 
struct  Fove_GazeVector
 Struct to represent a unit vector out from the eye center along which that eye is looking. More...
 
struct  Fove_GLTexture
 Struct used to submit an OpenGL texture. More...
 
struct  Fove_HeadsetHardwareInfo
 Struct Contains hardware information for the headset. More...
 
struct  Fove_Matrix44
 Struct to hold a rectangular array. More...
 
struct  Fove_MetalTexture
 Struct used to submit a texture using the Apple Metal API. More...
 
struct  Fove_Pose
 Struct to represent a combination of position and orientation of Fove Headset. More...
 
struct  Fove_ProjectionParams
 Struct holding information about projection fustum planes. More...
 
struct  Fove_Quaternion
 Struct representation on a quaternion. More...
 
struct  Fove_Ray
 Struct to represent a Ray. More...
 
struct  Fove_ResearchGaze
 Struct for returning gaze data from the research API. More...
 
struct  Fove_TextureBounds
 Struct to represent coordinates in normalized space. More...
 
struct  Fove_Vec2
 Struct to represent a 2D-vector. More...
 
struct  Fove_Vec2i
 Struct to represent a 2D-vector of integers. More...
 
struct  Fove_Vec3
 Struct to represent a 3D-vector. More...
 
struct  Fove_Versions
 Struct to list various version info about the FOVE software. More...
 

Macros

#define FOVE_DEFINE_CXX_API   0
 Macro that controls whether the C++ API will be defined. More...
 
#define FOVE_DEPRECATED(func, rem)   func
 
#define FOVE_ENUM(enumName)   typedef enum
 
#define FOVE_ENUM_END(enumName)   Fove_ ## enumName
 
#define FOVE_ENUM_VAL(enumName, valueName)   Fove_ ## enumName ## _ ## valueName
 
#define FOVE_EXPORT   FOVE_EXTERN_C
 
#define FOVE_EXTERN_C
 
#define FOVE_STRUCT(structName)   typedef struct
 
#define FOVE_STRUCT_END(structName)   Fove_ ## structName
 
#define FOVE_STRUCT_END_NO_CXX_ALIAS(structName)   Fove_ ## structName
 
#define FOVE_STRUCT_VAL(memberName, defaultVal)   memberName
 

Typedefs

typedef struct Fove_Compositor_ * Fove_Compositor
 Opaque type representing a compositor connection.
 
typedef struct Fove_Headset_ * Fove_Headset
 Opaque type representing a headset object.
 
typedef struct Fove_ResearchHeadset_ * Fove_ResearchHeadset
 Opaque type representing a headset with research-specific capabilities.
 

Enumerations

enum  Fove_AlphaMode { Fove_AlphaMode_Auto = 0, Fove_AlphaMode_One = 1, Fove_AlphaMode_Sample = 2 }
 Enum to help interpret the alpha of texture. More...
 
enum  Fove_ClientCapabilities { Fove_ClientCapabilities_None = 0x00, Fove_ClientCapabilities_Gaze = 0x01, Fove_ClientCapabilities_Orientation = 0x02, Fove_ClientCapabilities_Position = 0x04 }
 List of capabilities usable by clients. More...
 
enum  Fove_CompositorLayerType { Fove_CompositorLayerType_Base = 0, Fove_CompositorLayerType_Overlay = 0x10000, Fove_CompositorLayerType_Diagnostic = 0x20000 }
 Compositor layer type, which defines the order that clients are composited. More...
 
enum  Fove_ErrorCode {
  Fove_ErrorCode_None = 0, Fove_ErrorCode_Connection_General = 1, Fove_ErrorCode_Connect_NotConnected = 7, Fove_ErrorCode_Connect_ServerUnreachable = 2,
  Fove_ErrorCode_Connect_RegisterFailed = 3, Fove_ErrorCode_Connect_DeregisterFailed = 8, Fove_ErrorCode_Connect_RuntimeVersionTooOld = 4, Fove_ErrorCode_Connect_HeartbeatNoReply = 5,
  Fove_ErrorCode_Connect_ClientVersionTooOld = 6, Fove_ErrorCode_API_General = 100, Fove_ErrorCode_API_InitNotCalled = 101, Fove_ErrorCode_API_InitAlreadyCalled = 102,
  Fove_ErrorCode_API_InvalidArgument = 103, Fove_ErrorCode_API_NotRegistered = 104, Fove_ErrorCode_API_NullInPointer = 110, Fove_ErrorCode_API_InvalidEnumValue = 111,
  Fove_ErrorCode_API_NullOutPointersOnly = 120, Fove_ErrorCode_API_OverlappingOutPointers = 121, Fove_ErrorCode_API_CompositorNotSwapped = 122, Fove_ErrorCode_API_Timeout = 130,
  Fove_ErrorCode_Data_General = 1000, Fove_ErrorCode_Data_RegisteredWrongVersion = 1001, Fove_ErrorCode_Data_UnreadableNotFound = 1002, Fove_ErrorCode_Data_NoUpdate = 1003,
  Fove_ErrorCode_Data_Uncalibrated = 1004, Fove_ErrorCode_Data_MissingIPCData = 1005, Fove_ErrorCode_Hardware_General = 2000, Fove_ErrorCode_Hardware_CoreFault = 2001,
  Fove_ErrorCode_Hardware_CameraFault = 2002, Fove_ErrorCode_Hardware_IMUFault = 2003, Fove_ErrorCode_Hardware_ScreenFault = 2004, Fove_ErrorCode_Hardware_SecurityFault = 2005,
  Fove_ErrorCode_Hardware_Disconnected = 2006, Fove_ErrorCode_Hardware_WrongFirmwareVersion = 2007, Fove_ErrorCode_Server_General = 3000, Fove_ErrorCode_Server_HardwareInterfaceInvalid = 3001,
  Fove_ErrorCode_Server_HeartbeatNotRegistered = 3002, Fove_ErrorCode_Server_DataCreationError = 3003, Fove_ErrorCode_Server_ModuleError_ET = 3004, Fove_ErrorCode_Code_NotImplementedYet = 4000,
  Fove_ErrorCode_Code_FunctionDeprecated = 4001, Fove_ErrorCode_Position_NoObjectsInView = 5000, Fove_ErrorCode_Position_NoDlibRegressor = 5001, Fove_ErrorCode_Position_NoCascadeClassifier = 5002,
  Fove_ErrorCode_Position_NoModel = 5003, Fove_ErrorCode_Position_NoImages = 5004, Fove_ErrorCode_Position_InvalidFile = 5005, Fove_ErrorCode_Position_NoCamParaSet = 5006,
  Fove_ErrorCode_Position_CantUpdateOptical = 5007, Fove_ErrorCode_Position_ObjectNotTracked = 5008, Fove_ErrorCode_Position_NoCameraFound = 5009, Fove_ErrorCode_Eye_Left_NoDlibRegressor = 6000,
  Fove_ErrorCode_Eye_Right_NoDlibRegressor = 6001, Fove_ErrorCode_Eye_CalibrationFailed = 6002, Fove_ErrorCode_Eye_LoadCalibrationFailed = 6003, Fove_ErrorCode_User_General = 7000,
  Fove_ErrorCode_User_ErrorLoadingProfile = 7001, Fove_ErrorCode_Compositor_UnableToCreateDeviceAndContext = 8000, Fove_ErrorCode_Compositor_UnableToUseTexture = 8001, Fove_ErrorCode_Compositor_DeviceMismatch = 8002,
  Fove_ErrorCode_Compositor_IncompatibleCompositorVersion = 8003, Fove_ErrorCode_Compositor_UnableToFindRuntime = 8004, Fove_ErrorCode_Compositor_DisconnectedFromRuntime = 8006, Fove_ErrorCode_Compositor_ErrorCreatingTexturesOnDevice = 8008,
  Fove_ErrorCode_Compositor_NoEyeSpecifiedForSubmit = 8009, Fove_ErrorCode_UnknownError = 9000
}
 An enum of error codes that the system may return. More...
 
enum  Fove_Eye { Fove_Eye_Neither = 0, Fove_Eye_Left = 1, Fove_Eye_Right = 2, Fove_Eye_Both = 3 }
 Enum to identify which eye is being used. More...
 
enum  Fove_GraphicsAPI { Fove_GraphicsAPI_DirectX = 0, Fove_GraphicsAPI_OpenGL = 1, Fove_GraphicsAPI_Metal = 2 }
 enum for type of Graphics API More...
 
enum  Fove_ImageType { Fove_ImageType_StereoEye = 0x00, Fove_ImageType_Position = 0x01 }
 Indicates the source of an image. More...
 
enum  Fove_LogLevel { Fove_LogLevel_Debug = 0, Fove_LogLevel_Warning = 1, Fove_LogLevel_Error = 2 }
 Severity level of log messages.
 
enum  Fove_ResearchCapabilities { Fove_ResearchCapabilities_None = 0x00, Fove_ResearchCapabilities_EyeImage = 0x01, Fove_ResearchCapabilities_PositionImage = 0x02 }
 Research-API-specific capabilities.
 

Functions

Fove_ErrorCode fove_Compositor_createLayer (Fove_Compositor *, const Fove_CompositorLayerCreateInfo *layerInfo, Fove_CompositorLayer *outLayer)
 Creates a new layer within the compositor. More...
 
Fove_ErrorCode fove_Compositor_destroy (Fove_Compositor *)
 Frees resources used by ta compositor object, including memory and sockets. More...
 
Fove_ErrorCode fove_Compositor_getAdapterId (Fove_Compositor *, Fove_AdapterId *outAdapterId)
 Returns the ID of the GPU currently attached to the headset. More...
 
Fove_ErrorCode fove_Compositor_getLastRenderPose (Fove_Compositor *, Fove_Pose *outPose)
 Get the last cached pose for rendering purposes.
 
Fove_ErrorCode fove_Compositor_isReady (Fove_Compositor *, bool *outIsReady)
 Returns true if we are connected to a running compositor and ready to submit frames for compositing.
 
Fove_ErrorCode fove_Compositor_submit (Fove_Compositor *, const Fove_CompositorLayerSubmitInfo *submitInfo, size_t layerCount)
 Submit a frame to the compositor. More...
 
Fove_ErrorCode fove_Compositor_waitForRenderPose (Fove_Compositor *, Fove_Pose *outPose)
 Wait for the most recent pose for rendering purposes. More...
 
Fove_ErrorCode fove_createHeadset (Fove_ClientCapabilities capabilities, Fove_Headset **outHeadset)
 Creates and returns an Fove_Headset object, which is the entry point to the entire API. More...
 
Fove_ErrorCode fove_Headset_checkEyesClosed (Fove_Headset *, Fove_Eye *outEye)
 Writes out which eyes are closed. More...
 
Fove_ErrorCode fove_Headset_checkEyesTracked (Fove_Headset *, Fove_Eye *outEye)
 Writes out which eyes are being tracked. More...
 
Fove_ErrorCode fove_Headset_checkSoftwareVersions (Fove_Headset *)
 Checks whether the client can run against the installed version of the FOVE SDK. More...
 
Fove_ErrorCode fove_Headset_createCompositor (Fove_Headset *, Fove_Compositor **outCompositor)
 Returns a compositor interface from the given headset. More...
 
Fove_ErrorCode fove_Headset_destroy (Fove_Headset *)
 Frees resources used by a headset object, including memory and sockets. More...
 
Fove_ErrorCode fove_Headset_ensureEyeTrackingCalibration (Fove_Headset *)
 Starts calibration if not already calibrated. More...
 
Fove_ErrorCode fove_Headset_getEyeToHeadMatrices (Fove_Headset *, Fove_Matrix44 *outLeft, Fove_Matrix44 *outRight)
 Writes out the matrices to convert from eye- to head-space coordinates. More...
 
Fove_ErrorCode fove_Headset_getGazeConvergence (Fove_Headset *, Fove_GazeConvergenceData *outConvergenceData)
 Writes out eye convergence data. More...
 
Fove_ErrorCode fove_Headset_getGazeVectors (Fove_Headset *, Fove_GazeVector *outLeft, Fove_GazeVector *outRight)
 Writes out each eye's current gaze vector. More...
 
Fove_ErrorCode fove_Headset_getGazeVectors2D (Fove_Headset *, Fove_Vec2 *outLeft, Fove_Vec2 *outRight)
 Writes out the user's 2D gaze position on the screens seen through the HMD's lenses. More...
 
Fove_ErrorCode fove_Headset_getHardwareInfo (Fove_Headset *, Fove_HeadsetHardwareInfo *outHardwareInfo)
 Writes out information about the hardware information. More...
 
Fove_ErrorCode fove_Headset_getIOD (Fove_Headset *, float *outIOD)
 Interocular distance, returned in meters. More...
 
Fove_ErrorCode fove_Headset_getLatestPose (Fove_Headset *, Fove_Pose *outPose)
 Writes out the pose of the head-mounted display. More...
 
Fove_ErrorCode fove_Headset_getProjectionMatricesLH (Fove_Headset *, float zNear, float zFar, Fove_Matrix44 *outLeftMat, Fove_Matrix44 *outRightMat)
 Writes out the values of passed-in left-handed 4x4 projection matrices. More...
 
Fove_ErrorCode fove_Headset_getProjectionMatricesRH (Fove_Headset *, float zNear, float zFar, Fove_Matrix44 *outLeftMat, Fove_Matrix44 *outRightMat)
 Writes out the values of passed-in right-handed 4x4 projection matrices. More...
 
Fove_ErrorCode fove_Headset_getRawProjectionValues (Fove_Headset *, Fove_ProjectionParams *outLeft, Fove_ProjectionParams *outRight)
 Writes out values for the view frustum of the specified eye at 1 unit away. More...
 
Fove_ErrorCode fove_Headset_getResearchHeadset (Fove_Headset *, Fove_ResearchCapabilities caps, Fove_ResearchHeadset **outHeadset)
 Converts an existing headset object into a research headset. More...
 
Fove_ErrorCode fove_Headset_getSoftwareVersions (Fove_Headset *, Fove_Versions *outSoftwareVersions)
 Writes out information about the current software versions. More...
 
Fove_ErrorCode fove_Headset_isEyeTrackingCalibrated (Fove_Headset *, bool *outEyeTrackingCalibrated)
 Writes out whether eye tracking has been calibrated. More...
 
Fove_ErrorCode fove_Headset_isEyeTrackingCalibrating (Fove_Headset *, bool *outEyeTrackingCalibrating)
 Writes out whether eye tracking is in the process of performing a calibration. More...
 
Fove_ErrorCode fove_Headset_isEyeTrackingEnabled (Fove_Headset *, bool *outEyeTrackingEnabled)
 Writes out whether the eye tracking hardware has started. More...
 
Fove_ErrorCode fove_Headset_isEyeTrackingReady (Fove_Headset *, bool *outEyeTrackingReady)
 Writes out whether eye tracking is actively tracking an eye - or eyes. More...
 
Fove_ErrorCode fove_Headset_isHardwareConnected (Fove_Headset *, bool *outHardwareConnected)
 Writes out whether an HMD is know to be connected or not. More...
 
Fove_ErrorCode fove_Headset_isHardwareReady (Fove_Headset *, bool *outIsReady)
 Writes out whether the hardware for the requested capabilities has started. More...
 
Fove_ErrorCode fove_Headset_isMotionReady (Fove_Headset *, bool *outMotionReady)
 Writes out whether motion tracking hardware has started. More...
 
Fove_ErrorCode fove_Headset_isPositionReady (Fove_Headset *, bool *outPositionReady)
 Writes out whether position tracking hardware has started and returns whether it was successful. More...
 
Fove_ErrorCode fove_Headset_startEyeTrackingCalibration (Fove_Headset *, bool restartIfRunning)
 Starts eye tracking calibration. More...
 
Fove_ErrorCode fove_Headset_stopEyeTrackingCalibration (Fove_Headset *)
 Stops eye tracking calibration if it's running, does nothing if it's not running.
 
Fove_ErrorCode fove_Headset_tareOrientationSensor (Fove_Headset *)
 Tares the orientation of the headset. More...
 
Fove_ErrorCode fove_Headset_tarePositionSensors (Fove_Headset *)
 Tares the position of the headset. More...
 
Fove_ErrorCode fove_Headset_waitForNextEyeFrame (Fove_Headset *)
 Waits for next camera frame and associated eye tracking info becomes available. More...
 
Fove_ErrorCode fove_logText (Fove_LogLevel level, const char *utf8Text)
 Writes some text to the FOVE log something to the FOVE log. More...
 
Fove_ErrorCode fove_ResearchHeadset_getGaze (Fove_ResearchHeadset *, Fove_ResearchGaze *outGaze)
 Returns research-related information from eye tracking.
 
Fove_ErrorCode fove_ResearchHeadset_getImage (Fove_ResearchHeadset *, Fove_ImageType type, Fove_BitmapImage *outImage)
 Returns the latest image of the given type. More...
 
Fove_ErrorCode fove_ResearchHeadset_registerCapabilities (Fove_ResearchHeadset *, Fove_ResearchCapabilities caps)
 Registers a research capability, enabling the required hardware as needed. More...
 
Fove_ErrorCode fove_ResearchHeadset_unregisterCapabilities (Fove_ResearchHeadset *, Fove_ResearchCapabilities caps)
 Deregisters a research capability previously registed with Fove_RegisterResearchCapabilities.
 

Detailed Description

Complete self-contained FOVE API definition.

Macro Definition Documentation

◆ FOVE_DEFINE_CXX_API

#define FOVE_DEFINE_CXX_API   0

Macro that controls whether the C++ API will be defined.

The C API is always defined after including this header, but the C++ API is optional. In C++ mode, the C API is extended (for example, with default values for struct members) automatically.

User can set this macro to 0 or 1, either in code before including this, or via compile-flag to choose.

Defaults to 0 if the compiler is a C compiler, 1 if the compiler is a C++ compiler.

Enumeration Type Documentation

◆ Fove_AlphaMode

Enum to help interpret the alpha of texture.

Determines how to interpret the alpha of a compositor client texture

Enumerator
Fove_AlphaMode_Auto 

Base layers will use One, overlay layers will use Sample.

Fove_AlphaMode_One 

Alpha will always be one (fully opaque)

Fove_AlphaMode_Sample 

Alpha fill be sampled from the alpha channel of the buffer.

◆ Fove_ClientCapabilities

List of capabilities usable by clients.

Most features require registering for the relevant capability. If a client queries data related to a capability it has not registered API_NotRegistered will be returned.

This enum is designed to be used as a flag set, so items may be binary logic operators like |.

The FOVE runtime will keep any given set of hardware/software running so long as one client is registering a capability.

The registration of a capability does not necessarily mean that the capability is running. For example, if no position tracking camera is attached, no position tracking will occur regardless of how many clients registered for it.

Enumerator
Fove_ClientCapabilities_None 

No capabilities requested.

Fove_ClientCapabilities_Gaze 

Enables eye tracking.

Fove_ClientCapabilities_Orientation 

Enables headset orientation tracking.

Fove_ClientCapabilities_Position 

Enables headset position tracking.

◆ Fove_CompositorLayerType

Compositor layer type, which defines the order that clients are composited.

Enumerator
Fove_CompositorLayerType_Base 

The first and main application layer.

Fove_CompositorLayerType_Overlay 

Layer over the base.

Fove_CompositorLayerType_Diagnostic 

Layer over Overlay.

◆ Fove_ErrorCode

An enum of error codes that the system may return.

Enumerator
Fove_ErrorCode_API_General 

There was an error in the usage of the API other than one of the others in this section.

Fove_ErrorCode_API_InitNotCalled 

A function that should only be called after initialis was invoked before/without initialise.

Fove_ErrorCode_API_InitAlreadyCalled 

A function that should only be called before initialise() was invoked, or initialise was invoked multiple times.

Fove_ErrorCode_API_InvalidArgument 

An argument passed to an API function was invalid for a reason other than one of the below reasons.

Fove_ErrorCode_API_NotRegistered 

Data was queried without first registering for that data.

Fove_ErrorCode_API_NullInPointer 

An input argument passed to an API function was invalid for a reason other than the below reasons.

Fove_ErrorCode_API_InvalidEnumValue 

An enum argument passed to an API function was invalid.

Fove_ErrorCode_API_NullOutPointersOnly 

All output arguments were null on a function that requires at least one output (all getters that have no side effects)

Fove_ErrorCode_API_OverlappingOutPointers 

Two (or more) output parameters passed to an API function overlap in memory. Each output parameter should be a unique, separate object.

Fove_ErrorCode_API_CompositorNotSwapped 

This comes from submitting without calling WaitForRenderPose after a complete submit.

Fove_ErrorCode_API_Timeout 

A call to an API could not be completed within a timeout.

Fove_ErrorCode_Compositor_UnableToCreateDeviceAndContext 

Compositor was unable to initialize its backend component.

Fove_ErrorCode_Compositor_UnableToUseTexture 

Compositor was unable to use the given texture (likely due to mismatched client and data types or an incompatible format)

Fove_ErrorCode_Compositor_DeviceMismatch 

Compositor was unable to match its device to the texture's, either because of multiple GPUs or a failure to get the device from the texture.

Fove_ErrorCode_Compositor_IncompatibleCompositorVersion 

Compositor client is not compatible with the currently running compositor.

Fove_ErrorCode_Compositor_UnableToFindRuntime 

Compositor isn't running or isn't responding.

Fove_ErrorCode_Compositor_DisconnectedFromRuntime 

Compositor was running and is no longer responding.

Fove_ErrorCode_Compositor_ErrorCreatingTexturesOnDevice 

Failed to create shared textures for compositor.

Fove_ErrorCode_Compositor_NoEyeSpecifiedForSubmit 

The supplied Fove_Eye for submit is invalid (i.e. is Both or Neither)

Fove_ErrorCode_UnknownError 

Errors that are unknown or couldn't be classified. If possible, info will be logged about the nature of the issue.

◆ Fove_Eye

enum Fove_Eye

Enum to identify which eye is being used.

This is usually returned with any eye tracking information and tells the client which eye(s) the information is based on.

Enumerator
Fove_Eye_Neither 

Neither eye.

Fove_Eye_Left 

Left eye only.

Fove_Eye_Right 

Right eye only.

Fove_Eye_Both 

Both eyes.

◆ Fove_GraphicsAPI

enum for type of Graphics API

Type of Graphics API Note: We currently only support DirectX

Enumerator
Fove_GraphicsAPI_DirectX 

DirectX (Windows only)

Fove_GraphicsAPI_OpenGL 

OpenGL (All platforms, currently in BETA)

Fove_GraphicsAPI_Metal 

Metal (Mac only)

◆ Fove_ImageType

Indicates the source of an image.

Enumerator
Fove_ImageType_StereoEye 

Image comes from an eye camera, with the left/right eyes stiched into one image.

Fove_ImageType_Position 

Image comes from a position tracking camera.

Function Documentation

◆ fove_Compositor_createLayer()

Fove_ErrorCode fove_Compositor_createLayer ( Fove_Compositor ,
const Fove_CompositorLayerCreateInfo layerInfo,
Fove_CompositorLayer outLayer 
)

Creates a new layer within the compositor.

This function create a layer upon which frames may be submitted to the compositor by this client.

A connection to the compositor must exists for this to pass. This means you need to wait for fove_Compositor_isReady before calling this function. However, if connection to the compositor is lost and regained, this layer will persist. For this reason, you should not recreate your layers upon reconnection, simply create them once.

There is no way to delete a layer once created, other than to destroy the Fove_Compositor object. This is a feature we would like to add in the future.

Parameters
layerInfoThe settings for the layer to be created
outLayerA struct where the the defaults of the newly created layer will be written
See also
fove_Compositor_submit

◆ fove_Compositor_destroy()

Fove_ErrorCode fove_Compositor_destroy ( Fove_Compositor )

Frees resources used by ta compositor object, including memory and sockets.

Upon return, this compositor pointer should no longer be used.

See also
fove_Headset_createCompositor

◆ fove_Compositor_getAdapterId()

Fove_ErrorCode fove_Compositor_getAdapterId ( Fove_Compositor ,
Fove_AdapterId outAdapterId 
)

Returns the ID of the GPU currently attached to the headset.

For systems with multiple GPUs, submitted textures to the compositor must from the same GPU that the compositor is using

◆ fove_Compositor_submit()

Fove_ErrorCode fove_Compositor_submit ( Fove_Compositor ,
const Fove_CompositorLayerSubmitInfo submitInfo,
size_t  layerCount 
)

Submit a frame to the compositor.

This function takes the feed from your game engine to the compositor for output.

Parameters
submitInfoAn array of layerCount Fove_LayerSubmitInfo structs, each of which provides texture data for a unique layer
layerCountThe number of layers you are submitting
See also
fove_Compositor_submit

◆ fove_Compositor_waitForRenderPose()

Fove_ErrorCode fove_Compositor_waitForRenderPose ( Fove_Compositor ,
Fove_Pose outPose 
)

Wait for the most recent pose for rendering purposes.

All compositor clients should use this function as the sole means of limiting their frame rate. This allows the client to render at the correct frame rate for the HMD display. Upon this function returning, the client should proceed directly to rendering, to reduce the chance of missing the frame. If outPose is not null, this function will return the latest pose as a conveience to the caller. In general, a client's main loop should look like: { Update(); // Run AI, physics, etc, for the next frame compositor.WaitForRenderPose(&pose); // Wait for the next frame, and get the pose Draw(pose); // Render the scene using the new pose }

◆ fove_createHeadset()

Fove_ErrorCode fove_createHeadset ( Fove_ClientCapabilities  capabilities,
Fove_Headset **  outHeadset 
)

Creates and returns an Fove_Headset object, which is the entry point to the entire API.

The result headset should be destroyed using fove_Headset_destroy when no longer needed.

Parameters
capabilitiesThe desired capabilities (Gaze, Orientation, Position), for multiple capabilities, use bitwise-or input: Fove_ClientCapabilities::Gaze | Fove_ClientCapabilities::Position
outHeadsetA pointer where the address of the newly created headset will be written upon success
See also
fove_Headset_destroy

◆ fove_Headset_checkEyesClosed()

Fove_ErrorCode fove_Headset_checkEyesClosed ( Fove_Headset ,
Fove_Eye outEye 
)

Writes out which eyes are closed.

Parameters
outEyeA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_checkEyesTracked()

Fove_ErrorCode fove_Headset_checkEyesTracked ( Fove_Headset ,
Fove_Eye outEye 
)

Writes out which eyes are being tracked.

Parameters
outEyeA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_checkSoftwareVersions()

Fove_ErrorCode fove_Headset_checkSoftwareVersions ( Fove_Headset )

Checks whether the client can run against the installed version of the FOVE SDK.

Returns
None if this client is compatible with the currently running service Connect_RuntimeVersionTooOld if not compatible with the currently running service Otherwise returns an error representing why this can't be determined

◆ fove_Headset_createCompositor()

Fove_ErrorCode fove_Headset_createCompositor ( Fove_Headset ,
Fove_Compositor **  outCompositor 
)

Returns a compositor interface from the given headset.

Each call to this function creates a new object. The object should be destroyed with fove_Compositor_destroy It is fine to call this function multiple times with the same headset, the same pointer will be returned. It is ok for the compositor to outlive the headset passed in.

See also
fove_Compositor_destroy

◆ fove_Headset_destroy()

Fove_ErrorCode fove_Headset_destroy ( Fove_Headset )

Frees resources used by a headset object, including memory and sockets.

Upon return, this headset pointer, and any research headsets from it, should no longer be used.

See also
fove_createHeadset

◆ fove_Headset_ensureEyeTrackingCalibration()

Fove_ErrorCode fove_Headset_ensureEyeTrackingCalibration ( Fove_Headset )

Starts calibration if not already calibrated.

Does nothing if the user is already calibrated. Does nothing if the calibration is currently running.

All eye tracking content should call this before using the gaze to ensure that there's a valid calibration. After calling this, content should periodically poll for IsEyeTrackingCalibration() to become false, so as to ensure that the content is not updating while obscured by the calibrator

◆ fove_Headset_getEyeToHeadMatrices()

Fove_ErrorCode fove_Headset_getEyeToHeadMatrices ( Fove_Headset ,
Fove_Matrix44 outLeft,
Fove_Matrix44 outRight 
)

Writes out the matrices to convert from eye- to head-space coordinates.

This is simply a translation matrix that returns +/- IOD/2

Parameters
outLeftA pointer to the matrix where left-eye transform data will be written
outRightA pointer to the matrix where right-eye transform data will be written
Returns
Any error detected while fetching and writing data

◆ fove_Headset_getGazeConvergence()

Fove_ErrorCode fove_Headset_getGazeConvergence ( Fove_Headset ,
Fove_GazeConvergenceData outConvergenceData 
)

Writes out eye convergence data.

Parameters
outConvergenceDataA pointer to the convergence data struct to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_getGazeVectors()

Fove_ErrorCode fove_Headset_getGazeVectors ( Fove_Headset ,
Fove_GazeVector outLeft,
Fove_GazeVector outRight 
)

Writes out each eye's current gaze vector.

If either argument is nullptr, only the other value will be written. It is an error for both arguments to be nullptr.

Parameters
outLeftA pointer to the left eye gaze vector which will be written to
outRightA pointer to the right eye gaze vector which will be written to
Returns
Any error detected while fetching and writing the gaze vectors

◆ fove_Headset_getGazeVectors2D()

Fove_ErrorCode fove_Headset_getGazeVectors2D ( Fove_Headset ,
Fove_Vec2 outLeft,
Fove_Vec2 outRight 
)

Writes out the user's 2D gaze position on the screens seen through the HMD's lenses.

The use of lenses and distortion correction creates a screen in front of each eye. This function returns 2D vectors representing where on each eye's screen the user is looking. The vectors are normalized in the range [-1, 1] along both X and Y axes such that the following points are true:

Center: (0, 0) Bottom-Left: (-1, -1) Top-Right: (1, 1)

Parameters
outLeftA pointer to the left eye gaze point in the HMD's virtual screen space
outRightA pointer to the right eye gaze point in the HMD's virtual screen space
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_getHardwareInfo()

Fove_ErrorCode fove_Headset_getHardwareInfo ( Fove_Headset ,
Fove_HeadsetHardwareInfo outHardwareInfo 
)

Writes out information about the hardware information.

Allows you to get serial number, manufacturer, and model name of the headset.

◆ fove_Headset_getIOD()

Fove_ErrorCode fove_Headset_getIOD ( Fove_Headset ,
float *  outIOD 
)

Interocular distance, returned in meters.

This is an estimation of the distance between centers of the left and right eyeballs. Half of the IOD can be used to displace the left and right cameras for stereoscopic rendering. We recommend calling this each frame when doing stereoscoping rendering. Future versions of the FOVE service may update the IOD during runtime as needed.

Parameters
outIODA floating point value where the IOD will be written upon exit if there is no error

◆ fove_Headset_getLatestPose()

Fove_ErrorCode fove_Headset_getLatestPose ( Fove_Headset ,
Fove_Pose outPose 
)

Writes out the pose of the head-mounted display.

Parameters
outPoseA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_getProjectionMatricesLH()

Fove_ErrorCode fove_Headset_getProjectionMatricesLH ( Fove_Headset ,
float  zNear,
float  zFar,
Fove_Matrix44 outLeftMat,
Fove_Matrix44 outRightMat 
)

Writes out the values of passed-in left-handed 4x4 projection matrices.

Writes 4x4 projection matrices for both eyes using near and far planes in a left-handed coordinate system. Either outLeftMat or outRightMat may be nullptr to only write the other matrix, however setting both to nullptr is considered invalid and will return Fove_ErrorCode::API_NullOutPointersOnly.

Parameters
zNearThe near plane in float, Range: from 0 to zFar
zFarThe far plane in float, Range: from zNear to infinity
outLeftMatA pointer to the matrix you want written
outRightMatA pointer to the matrix you want written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_getProjectionMatricesRH()

Fove_ErrorCode fove_Headset_getProjectionMatricesRH ( Fove_Headset ,
float  zNear,
float  zFar,
Fove_Matrix44 outLeftMat,
Fove_Matrix44 outRightMat 
)

Writes out the values of passed-in right-handed 4x4 projection matrices.

Writes 4x4 projection matrices for both eyes using near and far planes in a right-handed coordinate system. Either outLeftMat or outRightMat may be nullptr to only write the other matrix, however setting both to nullptr is considered invalid and will return Fove_ErrorCode::API_NullOutPointersOnly.

Parameters
zNearThe near plane in float, Range: from 0 to zFar
zFarThe far plane in float, Range: from zNear to infinity
outLeftMatA pointer to the matrix you want written
outRightMatA pointer to the matrix you want written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_getRawProjectionValues()

Fove_ErrorCode fove_Headset_getRawProjectionValues ( Fove_Headset ,
Fove_ProjectionParams outLeft,
Fove_ProjectionParams outRight 
)

Writes out values for the view frustum of the specified eye at 1 unit away.

Writes out values for the view frustum of the specified eye at 1 unit away. Please multiply them by zNear to convert to your correct frustum near-plane. Either outLeft or outRight may be nullptr to only write the other struct, however setting both to nullptr is considered and error and the function will return Fove_ErrorCode::API_NullOutPointersOnly.

Parameters
outLeftA pointer to the struct describing the left camera projection parameters
outRightA pointer to the struct describing the right camera projection parameters
Returns
Any error detected while fetching and writing data

◆ fove_Headset_getResearchHeadset()

Fove_ErrorCode fove_Headset_getResearchHeadset ( Fove_Headset ,
Fove_ResearchCapabilities  caps,
Fove_ResearchHeadset **  outHeadset 
)

Converts an existing headset object into a research headset.

It is fine to call this function multiple times with the same headset, the same pointer will be returned. The research API does not provide backwards or forwards compatibility with different FOVE runtimes. Do not release general purpose software using this API, this is meant for researcher user in a controlled environment (lab). The result Fove_ResearchHeadset is destroyed when the input headset object is destroyed. There is no destroy/free function for the research headset specifically.

Parameters
capsThese capabilities are automatically passed to fove_ResearchHeadset_registerCapabilities so as to avoid an extra call
outHeadsetA pointer where the address of the newly created research headset object will be written upon success
See also
fove_Headset_destroy

◆ fove_Headset_getSoftwareVersions()

Fove_ErrorCode fove_Headset_getSoftwareVersions ( Fove_Headset ,
Fove_Versions outSoftwareVersions 
)

Writes out information about the current software versions.

Allows you to get detailed information about the client and runtime versions. Instead of comparing software versions directly, you should simply call CheckSoftwareVersions to ensure that the client and runtime are compatible.

◆ fove_Headset_isEyeTrackingCalibrated()

Fove_ErrorCode fove_Headset_isEyeTrackingCalibrated ( Fove_Headset ,
bool *  outEyeTrackingCalibrated 
)

Writes out whether eye tracking has been calibrated.

Parameters
outEyeTrackingCalibratedA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_isEyeTrackingCalibrating()

Fove_ErrorCode fove_Headset_isEyeTrackingCalibrating ( Fove_Headset ,
bool *  outEyeTrackingCalibrating 
)

Writes out whether eye tracking is in the process of performing a calibration.

Parameters
outEyeTrackingCalibratingA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_isEyeTrackingEnabled()

Fove_ErrorCode fove_Headset_isEyeTrackingEnabled ( Fove_Headset ,
bool *  outEyeTrackingEnabled 
)

Writes out whether the eye tracking hardware has started.

Parameters
outEyeTrackingEnabledA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_isEyeTrackingReady()

Fove_ErrorCode fove_Headset_isEyeTrackingReady ( Fove_Headset ,
bool *  outEyeTrackingReady 
)

Writes out whether eye tracking is actively tracking an eye - or eyes.

This means that hardware is enabled and eye tracking is calibrated when the variable is set to true.

Parameters
outEyeTrackingReadyA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_isHardwareConnected()

Fove_ErrorCode fove_Headset_isHardwareConnected ( Fove_Headset ,
bool *  outHardwareConnected 
)

Writes out whether an HMD is know to be connected or not.

Parameters
outHardwareConnectedA pointer to the value to be written
Returns
Any error detected that might make the out data unreliable
See also
fove_createHeadset

◆ fove_Headset_isHardwareReady()

Fove_ErrorCode fove_Headset_isHardwareReady ( Fove_Headset ,
bool *  outIsReady 
)

Writes out whether the hardware for the requested capabilities has started.

Returns
Any error detected that might make the out data unreliable

◆ fove_Headset_isMotionReady()

Fove_ErrorCode fove_Headset_isMotionReady ( Fove_Headset ,
bool *  outMotionReady 
)

Writes out whether motion tracking hardware has started.

Parameters
outMotionReadyA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_isPositionReady()

Fove_ErrorCode fove_Headset_isPositionReady ( Fove_Headset ,
bool *  outPositionReady 
)

Writes out whether position tracking hardware has started and returns whether it was successful.

Parameters
outPositionReadyA pointer to the variable to be written
Returns
Any error detected while fetching and writing the data

◆ fove_Headset_startEyeTrackingCalibration()

Fove_ErrorCode fove_Headset_startEyeTrackingCalibration ( Fove_Headset ,
bool  restartIfRunning 
)

Starts eye tracking calibration.

Parameters
restartIfRunningIf true, this will cause the calibration to restart if it's already running Otherwise this will do nothing if eye tracking calibration is currently running.

◆ fove_Headset_tareOrientationSensor()

Fove_ErrorCode fove_Headset_tareOrientationSensor ( Fove_Headset )

Tares the orientation of the headset.

Returns
Any error detected while fetching and writing the data

◆ fove_Headset_tarePositionSensors()

Fove_ErrorCode fove_Headset_tarePositionSensors ( Fove_Headset )

Tares the position of the headset.

Returns
Any error detected while fetching and writing the data

◆ fove_Headset_waitForNextEyeFrame()

Fove_ErrorCode fove_Headset_waitForNextEyeFrame ( Fove_Headset )

Waits for next camera frame and associated eye tracking info becomes available.

Allows you to sync your eye tracking loop to the actual eye-camera loop. On each loop, you would first call this blocking function to wait for a new frame and then proceed to consume eye tracking info accociated with the frame.

◆ fove_logText()

Fove_ErrorCode fove_logText ( Fove_LogLevel  level,
const char *  utf8Text 
)

Writes some text to the FOVE log something to the FOVE log.

Parameters
levelWhat severity level the log will use
utf8TextNull-terminated text string in UTF8

◆ fove_ResearchHeadset_getImage()

Fove_ErrorCode fove_ResearchHeadset_getImage ( Fove_ResearchHeadset ,
Fove_ImageType  type,
Fove_BitmapImage outImage 
)

Returns the latest image of the given type.

The image data buffer is invalidated upon the next call to this function with the same image type

◆ fove_ResearchHeadset_registerCapabilities()

Fove_ErrorCode fove_ResearchHeadset_registerCapabilities ( Fove_ResearchHeadset ,
Fove_ResearchCapabilities  caps 
)

Registers a research capability, enabling the required hardware as needed.

Normally this is invoked directly via fove_Headset_getResearchHeadset. You can add and remove capabilities while the object is alive.

Parameters
capsA set of capabitilties to register. Reregistering an existing capability is a no-op