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

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

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

Classes

class  Fove::Compositor
 Compositor API. More...
 
struct  Fove::Exception
 Exception type that is thrown when an error is ignored in the FOVE API. More...
 
class  Fove::Headset
 Main API for using headsets. More...
 
struct  Fove::HeadsetHardwareInfo
 Struct Contains hardware information for the headset. More...
 
class  Fove::Object< CType >
 Base class for classes in the FOVE C++ API. More...
 
class  Fove::ResearchHeadset
 Research API. More...
 
class  Fove::Result< Value >
 Class for return values from the C++ API. More...
 
struct  Fove::Stereo< Type >
 Class to hold two copies of something, one for each left and right respectively. More...
 
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_EyeData
 Eye Radius Information. 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_CXX_NAMESPACE   Fove
 
#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)   enum class Fove_ ## enumName
 
#define FOVE_ENUM_END(enumName)   ; namespace FOVE_CXX_NAMESPACE { using enumName = Fove_ ## enumName; }
 
#define FOVE_ENUM_VAL(enumName, valueName)   valueName
 
#define FOVE_EXCEPTIONS   1
 
#define FOVE_EXPORT   FOVE_EXTERN_C
 
#define FOVE_EXTERN_C
 
#define FOVE_NOEXCEPT
 Define this to empty to remove noexcept specifiers from the API.
 
#define FOVE_STRUCT(structName)   struct Fove_ ## structName
 
#define FOVE_STRUCT_END(structName)   ; namespace FOVE_CXX_NAMESPACE { using structName = Fove_ ## structName; }
 
#define FOVE_STRUCT_END_NO_CXX_ALIAS(structName)   ;
 
#define FOVE_STRUCT_VAL(memberName, defaultVal)   memberName = defaultVal
 

Typedefs

using Fove::AdapterId = Fove_AdapterId
 
using Fove::AlphaMode = Fove_AlphaMode
 
using Fove::BitmapImage = Fove_BitmapImage
 
using Fove::Buffer = Fove_Buffer
 
using Fove::ClientCapabilities = Fove_ClientCapabilities
 
using Fove::CompositorLayer = Fove_CompositorLayer
 
using Fove::CompositorLayerCreateInfo = Fove_CompositorLayerCreateInfo
 
using Fove::CompositorLayerEyeSubmitInfo = Fove_CompositorLayerEyeSubmitInfo
 
using Fove::CompositorLayerSubmitInfo = Fove_CompositorLayerSubmitInfo
 
using Fove::CompositorLayerType = Fove_CompositorLayerType
 
using Fove::CompositorTexture = Fove_CompositorTexture
 
using Fove::DX11Texture = Fove_DX11Texture
 
using Fove::ErrorCode = Fove_ErrorCode
 
using Fove::Eye = Fove_Eye
 
using Fove::EyeData = Fove_EyeData
 
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.
 
using Fove::GazeConvergenceData = Fove_GazeConvergenceData
 
using Fove::GazeVector = Fove_GazeVector
 
using Fove::GLTexture = Fove_GLTexture
 
using Fove::GraphicsAPI = Fove_GraphicsAPI
 
using Fove::ImageType = Fove_ImageType
 
using Fove::LogLevel = Fove_LogLevel
 
using Fove::Matrix44 = Fove_Matrix44
 
using Fove::MetalTexture = Fove_MetalTexture
 
using Fove::Pose = Fove_Pose
 
using Fove::ProjectionParams = Fove_ProjectionParams
 
using Fove::Quaternion = Fove_Quaternion
 
using Fove::Ray = Fove_Ray
 
using Fove::ResearchCapabilities = Fove_ResearchCapabilities
 
using Fove::ResearchGaze = Fove_ResearchGaze
 
using Fove::TextureBounds = Fove_TextureBounds
 
using Fove::Vec2 = Fove_Vec2
 
using Fove::Vec2i = Fove_Vec2i
 
using Fove::Vec3 = Fove_Vec3
 
using Fove::Versions = Fove_Versions
 

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 {
  None = 0, Connection_General = 1, Connect_NotConnected = 7, Connect_ServerUnreachable = 2,
  Connect_RegisterFailed = 3, Connect_DeregisterFailed = 8, Connect_RuntimeVersionTooOld = 4, Connect_HeartbeatNoReply = 5,
  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,
  Data_General = 1000, Data_RegisteredWrongVersion = 1001, Data_UnreadableNotFound = 1002, Data_NoUpdate = 1003,
  Data_Uncalibrated = 1004, Data_MissingIPCData = 1005, Hardware_General = 2000, Hardware_CoreFault = 2001,
  Hardware_CameraFault = 2002, Hardware_IMUFault = 2003, Hardware_ScreenFault = 2004, Hardware_SecurityFault = 2005,
  Hardware_Disconnected = 2006, Hardware_WrongFirmwareVersion = 2007, Server_General = 3000, Server_HardwareInterfaceInvalid = 3001,
  Server_HeartbeatNotRegistered = 3002, Server_DataCreationError = 3003, Server_ModuleError_ET = 3004, Code_NotImplementedYet = 4000,
  Code_FunctionDeprecated = 4001, Position_NoObjectsInView = 5000, Position_NoDlibRegressor = 5001, Position_NoCascadeClassifier = 5002,
  Position_NoModel = 5003, Position_NoImages = 5004, Position_InvalidFile = 5005, Position_NoCamParaSet = 5006,
  Position_CantUpdateOptical = 5007, Position_ObjectNotTracked = 5008, Position_NoCameraFound = 5009, Eye_Left_NoDlibRegressor = 6000,
  Eye_Right_NoDlibRegressor = 6001, Eye_CalibrationFailed = 6002, Eye_LoadCalibrationFailed = 6003, User_General = 7000,
  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 { Debug = 0, Warning = 1, Error = 2 }
 Severity level of log messages.
 
enum  Fove_ResearchCapabilities { None = 0x00, EyeImage = 0x01, 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_registerCapabilities (Fove_Headset *, Fove_ClientCapabilities caps)
 Registers a client capability, enabling the required hardware as needed. 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_unregisterCapabilities (Fove_Headset *, Fove_ClientCapabilities caps)
 Unregisters a client capability previously registered with fove_Headset_RegisterCapabilities or fove_Headset_CreateHeadset functions.
 
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. 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_turnOffPositionTrackingLEDs (Fove_ResearchHeadset *)
 Turns off position tracking LEDs all at once at a default intensity. More...
 
Fove_ErrorCode fove_ResearchHeadset_turnOnPositionTrackingLEDs (Fove_ResearchHeadset *)
 Turns on position tracking LEDs all at once at a default intensity. More...
 
Fove_ErrorCode fove_ResearchHeadset_unregisterCapabilities (Fove_ResearchHeadset *, Fove_ResearchCapabilities caps)
 Unregisters a research capability previously registered with Fove_RegisterResearchCapabilities.
 
Result Fove::logText (const LogLevel level, const std::string &utf8Text)
 Wraps fove_logText()
 

Detailed Description

Complete self-contained FOVE API definition.

Macro Definition Documentation

◆ FOVE_CXX_NAMESPACE

#define FOVE_CXX_NAMESPACE   Fove

Since the C++ API is header-only, the functions in it do not need to be in any particular namespace.

By default, everything is put in the Fove namespace, but this can be customized if the user prefers.

◆ 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.

◆ FOVE_EXCEPTIONS

#define FOVE_EXCEPTIONS   1

Exceptions are enabled by default in the C++ API, because they are a core C++ feature. However, they are only used in specific functions, not everywhere. If you are working in a code base that bans exceptions, define FOVE_EXCEPTIONS to zero. Exceptions are automatically disabled for the unreal engine.

Enumeration Type Documentation

◆ Fove_AlphaMode

enum Fove_AlphaMode
strong

Enum to help interpret the alpha of texture.

Determines how to interpret the alpha of a compositor client texture

Enumerator
Auto 

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

One 

Alpha will always be one (fully opaque)

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
None 

No capabilities requested.

Gaze 

Enables eye tracking.

Orientation 

Enables headset orientation tracking.

Position 

Enables headset position tracking.

◆ Fove_CompositorLayerType

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

Enumerator
Base 

The first and main application layer.

Overlay 

Layer over the base.

Diagnostic 

Layer over Overlay.

◆ Fove_ErrorCode

enum Fove_ErrorCode
strong

An enum of error codes that the system may return.

Enumerator
API_General 

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

API_InitNotCalled 

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

API_InitAlreadyCalled 

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

API_InvalidArgument 

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

API_NotRegistered 

Data was queried without first registering for that data.

API_NullInPointer 

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

API_InvalidEnumValue 

An enum argument passed to an API function was invalid.

API_NullOutPointersOnly 

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

API_OverlappingOutPointers 

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

API_CompositorNotSwapped 

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

API_Timeout 

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

Compositor_UnableToCreateDeviceAndContext 

Compositor was unable to initialize its backend component.

Compositor_UnableToUseTexture 

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

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.

Compositor_IncompatibleCompositorVersion 

Compositor client is not compatible with the currently running compositor.

Compositor_UnableToFindRuntime 

Compositor isn't running or isn't responding.

Compositor_DisconnectedFromRuntime 

Compositor was running and is no longer responding.

Compositor_ErrorCreatingTexturesOnDevice 

Failed to create shared textures for compositor.

Compositor_NoEyeSpecifiedForSubmit 

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

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
strong

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
Neither 

Neither eye.

Left 

Left eye only.

Right 

Right eye only.

Both 

Both eyes.

◆ Fove_GraphicsAPI

enum Fove_GraphicsAPI
strong

enum for type of Graphics API

Type of Graphics API Note: We currently only support DirectX

Enumerator
DirectX 

DirectX (Windows only)

OpenGL 

OpenGL (All platforms, currently in BETA)

Metal 

Metal (Mac only)

◆ Fove_ImageType

enum Fove_ImageType
strong

Indicates the source of an image.

Enumerator
StereoEye 

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

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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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

Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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 }

Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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

Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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.

Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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.

Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ fove_Headset_registerCapabilities()

Fove_ErrorCode fove_Headset_registerCapabilities ( Fove_Headset ,
Fove_ClientCapabilities  caps 
)

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

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

Parameters
capsA set of capabilities to register. Reregistering an existing capability is a no-op
Here is the caller graph for this function:

◆ 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.
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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
Here is the caller graph for this function:

◆ 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 associated with the frame.

Here is the caller graph for this function:

◆ fove_logText()

Fove_ErrorCode fove_logText ( Fove_LogLevel  level,
const char *  utf8Text 
)

Writes some text to the FOVE log.

Parameters
levelWhat severity level the log will use
utf8TextNull-terminated text string in UTF8
Returns
An error code, usually discarded since nothing critical should depend on logging
Here is the caller graph for this function:

◆ 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

Here is the caller graph for this function:

◆ 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 capabilities to register. Reregistering an existing capability is a no-op
Here is the caller graph for this function:

◆ fove_ResearchHeadset_turnOffPositionTrackingLEDs()

Fove_ErrorCode fove_ResearchHeadset_turnOffPositionTrackingLEDs ( Fove_ResearchHeadset )

Turns off position tracking LEDs all at once at a default intensity.

Returns
Any error detected while trying to turn off position tracking LEDs
Here is the caller graph for this function:

◆ fove_ResearchHeadset_turnOnPositionTrackingLEDs()

Fove_ErrorCode fove_ResearchHeadset_turnOnPositionTrackingLEDs ( Fove_ResearchHeadset )

Turns on position tracking LEDs all at once at a default intensity.

Returns
Any error detected while trying to turn on position tracking LEDs
Here is the caller graph for this function: