SDK DOCUMENTATION
Varjo.h File Reference

Go to the source code of this file.

Functions

varjo_Bool varjo_IsAvailable ()
 Checks whether Varjo system is available. More...
 
const char * varjo_GetVersionString ()
 Gets the short version of the library. More...
 
const uint64_t varjo_GetVersion ()
 Gets the version number of the library. More...
 
struct varjo_Session * varjo_SessionInit (void)
 Initializes a Varjo client session. More...
 
void varjo_SessionShutDown (struct varjo_Session *session)
 Shuts down a session and releases all the resources internally allocated by Varjo session. More...
 
varjo_Nanoseconds varjo_GetCurrentTime (struct varjo_Session *session)
 Gets the current time in a format that Varjo API uses. More...
 
struct varjo_FrameInfovarjo_CreateFrameInfo (struct varjo_Session *session)
 Creates a frame info with initial values. More...
 
void varjo_FreeFrameInfo (struct varjo_FrameInfo *frameInfo)
 Frees an allocated frame info. More...
 
struct varjo_SubmitInfovarjo_CreateSubmitInfo (struct varjo_Session *session)
 Creates a submit info for ending a frame with default viewport layout. More...
 
void varjo_FreeSubmitInfo (struct varjo_SubmitInfo *submitInfo)
 Frees an allocated submit info. More...
 
void varjo_LayoutDefaultViewports (struct varjo_Session *session, struct varjo_Viewport *viewports)
 Layout default viewport configuration. More...
 
void varjo_SetCenteredProjection (struct varjo_Session *session, varjo_Bool enabled)
 Forces the provided projection matrices to be centered. More...
 
struct varjo_AlignedView varjo_GetAlignedView (double *projectionMatrix)
 Gets an aligned view from a projection matrix. More...
 
void varjo_UpdateClipPlaneDistances (struct varjo_Session *session, double *projectionMatrix, double nearClipDistance, double farClipDistance)
 Updates clip plane distances in the projection matrix. More...
 
void varjo_WaitSync (struct varjo_Session *session, struct varjo_FrameInfo *frameInfo)
 Called at the start of a frame. More...
 
void varjo_BeginFrame (struct varjo_Session *session, struct varjo_SubmitInfo *submitInfo)
 Begin rendering the frame. More...
 
void varjo_EndFrame (struct varjo_Session *session, struct varjo_FrameInfo *frameInfo, struct varjo_SubmitInfo *submitInfo)
 End the current frame. More...
 
varjo_Nanoseconds varjo_FrameGetDisplayTime (struct varjo_Session *session)
 Gets the time when the frame is scheduled to be displayed. More...
 
struct varjo_Matrix varjo_FrameGetPose (struct varjo_Session *session, varjo_PoseType type)
 Gets a pose for the current frame. More...
 
struct varjo_Matrix varjo_GetRelativePoseTransform (struct varjo_Session *session, varjo_PoseType src, varjo_PoseType dest)
 Gets a relative transformation from source pose to destination pose. More...
 
struct varjo_Matrix varjo_ApplyTransform (struct varjo_Session *session, struct varjo_Matrix *m1, struct varjo_Matrix *m2)
 Applies transform using post multiplication. More...
 
void varjo_ResetPose (struct varjo_Session *session, varjo_Bool position, varjo_RotationReset rotation)
 Resets pose tracking origin. More...
 
struct varjo_ViewDescription varjo_GetViewDescription (struct varjo_Session *session, int32_t viewIndex)
 Gets the display information for a given view. More...
 
struct varjo_Mesh2Dfvarjo_CreateOcclusionMesh (struct varjo_Session *session, int32_t viewIndex, varjo_WindingOrder windingOrder)
 Creates the occlusion mesh for a given view index. More...
 
void varjo_FreeOcclusionMesh (struct varjo_Mesh2Df *mesh)
 Frees the memory allocated by varjo_CreateOcclusionMesh. More...
 
varjo_Error varjo_GetError (struct varjo_Session *session)
 Gets the latest error code. More...
 
VARJO_DEPRECATED_API const char * varjo_GetErrorDescription (struct varjo_Session *session)
 Gets the current error description string in english. More...
 
const char * varjo_GetErrorDesc (varjo_Error error)
 Gets error description for the specified error code. More...
 
VARJO_DEPRECATED_API void varjo_ClearError (struct varjo_Session *session)
 Resets the error status. More...
 
void varjo_GazeInit (struct varjo_Session *session)
 Initializes the gaze tracking system. More...
 
varjo_Bool varjo_IsGazeAllowed (struct varjo_Session *session)
 Is gaze allowed to be used? More...
 
struct varjo_Gaze varjo_GetGaze (struct varjo_Session *session)
 Gets the current state of the user gaze. More...
 
int32_t varjo_GetGazeArray (struct varjo_Session *session, struct varjo_Gaze *array, int32_t maxSizeOfArray)
 Gets gaze measurements since last query. More...
 
void varjo_SyncProperties (struct varjo_Session *session)
 Updates and synchronizes system properties with the system state. More...
 
int32_t varjo_GetPropertyCount (struct varjo_Session *session)
 Gets the number of system properties. More...
 
varjo_PropertyKey varjo_GetPropertyKey (struct varjo_Session *session, int32_t index)
 Gets a property key for a property index. More...
 
const char * varjo_GetPropertyName (struct varjo_Session *session, varjo_PropertyKey propertyKey)
 Gets the name of the property key. More...
 
varjo_Bool varjo_HasProperty (struct varjo_Session *session, varjo_PropertyKey propertyKey)
 Checks if the key has value in the properties. More...
 
varjo_Bool varjo_GetPropertyBool (struct varjo_Session *session, varjo_PropertyKey propertyKey)
 Gets a boolean value of a property. More...
 
double varjo_GetPropertyDouble (struct varjo_Session *session, varjo_PropertyKey propertyKey)
 Gets a floating point value of a property. More...
 
int32_t varjo_GetPropertyInt (struct varjo_Session *session, varjo_PropertyKey propertyKey)
 Gets an integer value of a property. More...
 
void varjo_RequestGazeCalibration (struct varjo_Session *session)
 Requests a HMD gaze calibration. More...
 
struct varjo_SwapChainConfig varjo_GetDefaultSwapChainConfig (struct varjo_Session *session)
 Gets the default swap chain config. More...
 
struct varjo_SwapChainLimits varjo_GetSwapChainLimits (struct varjo_Session *session)
 Gets swap chain limits. More...
 
void varjo_GetSupportedTextureFormats (struct varjo_Session *session, varjo_RenderAPI renderApi, int32_t *formatCount, varjo_TextureFormat *formats)
 Gets supported texture formats in the order of most preferred to least preferred. More...
 
varjo_Bool varjo_IsSwapChainConfigSupported (struct varjo_Session *session, varjo_RenderAPI renderApi, const struct varjo_SwapChainConfig *config)
 Is the given swap chain config supported. More...
 
int32_t varjo_GetSwapChainCurrentIndex (struct varjo_Session *session)
 Gets the current swap chain texture index. More...
 
struct varjo_Eventvarjo_AllocateEvent ()
 Allocates an event. More...
 
void varjo_FreeEvent (struct varjo_Event *event)
 Free an event. More...
 
varjo_Bool varjo_PollEvent (struct varjo_Session *session, struct varjo_Event *evt)
 Polls events. More...
 

Function Documentation

◆ varjo_AllocateEvent()

struct varjo_Event* varjo_AllocateEvent ( )

Allocates an event.

Helper function if you don't want to do the allocation by yourself.

Returns
Allocated event.

◆ varjo_ApplyTransform()

struct varjo_Matrix varjo_ApplyTransform ( struct varjo_Session *  session,
struct varjo_Matrix m1,
struct varjo_Matrix m2 
)

Applies transform using post multiplication.

Parameters
sessionVarjo session handle.
m1First transform.
m2Second transform.
Returns
Second transformation applied to the first one.

◆ varjo_BeginFrame()

void varjo_BeginFrame ( struct varjo_Session *  session,
struct varjo_SubmitInfo submitInfo 
)

Begin rendering the frame.

This function should be called only from the rendering thread.

Parameters
sessionVarjo session handle.
submitInfoSubmit info to fill in the frame metadata.

◆ varjo_ClearError()

VARJO_DEPRECATED_API void varjo_ClearError ( struct varjo_Session *  session)

Resets the error status.

The errors are persistent - the error code and description refer to the first Varjo API call that has failed and the following API calls may fail as a cascading result. Thus you should clear error status after handling the error.

Parameters
sessionVarjo session handle.
Deprecated:
varjo_GetError will reset the error status.

◆ varjo_CreateFrameInfo()

struct varjo_FrameInfo* varjo_CreateFrameInfo ( struct varjo_Session *  session)

Creates a frame info with initial values.

Allocates enough data to hold all of the views.

Use varjo_FreeFrameInfo to free the allocated memory.

Parameters
sessionVarjo session handle.
Returns
Frame info.

◆ varjo_CreateOcclusionMesh()

struct varjo_Mesh2Df* varjo_CreateOcclusionMesh ( struct varjo_Session *  session,
int32_t  viewIndex,
varjo_WindingOrder  windingOrder 
)

Creates the occlusion mesh for a given view index.

Due to lens distortion some display pixels are not visible in the optical path so the application can stencil out pixels to reduce shading workload and improve performance.

Mesh data is a triangle list where each triplet of vertices forms a triangle.

Use varjo_FreeOcclusionMesh to free the created mesh.

Parameters
sessionVarjo session handle.
viewIndexView number to get the occlusion mesh for. Must be in range [0, varjo_GraphicsInfo::viewCount - 1].
windingOrderWinding order of the triangles
Returns
Occlusion mesh, null if the viewIndex invalid.

◆ varjo_CreateSubmitInfo()

struct varjo_SubmitInfo* varjo_CreateSubmitInfo ( struct varjo_Session *  session)

Creates a submit info for ending a frame with default viewport layout.

Other fields areinitialized with default values. Allocates enough data to hold all of the views.

Use varjo_FreeSubmitInfo to free the allocated memory.

Parameters
sessionVarjo session handle.
Returns
Submit info.

◆ varjo_EndFrame()

void varjo_EndFrame ( struct varjo_Session *  session,
struct varjo_FrameInfo frameInfo,
struct varjo_SubmitInfo submitInfo 
)

End the current frame.

This function should be called only from the rendering thread.

Parameters
sessionVarjo session handle.
frameInfoView and projection matrices the frame was rendered with.
submitInfoTextures and viewports to submit.

◆ varjo_FrameGetDisplayTime()

varjo_Nanoseconds varjo_FrameGetDisplayTime ( struct varjo_Session *  session)

Gets the time when the frame is scheduled to be displayed.

This time refers to the average perceived moment of when the image is shown.

The display time is updated in varjo_WaitSync and is guaranteed to remain constant for the duration of the frame.

This is a helper function for when you don't have access to varjo_FrameInfo.

Parameters
sessionVarjo session handle.
Returns
Nanoseconds since epoch.

◆ varjo_FrameGetPose()

struct varjo_Matrix varjo_FrameGetPose ( struct varjo_Session *  session,
varjo_PoseType  type 
)

Gets a pose for the current frame.

If it's called before varjo_WaitSync() is complete, it will return new pose. Following calls to varjo_FrameGetPose() will return the same matrix. varjo_WaitSync() will also derive it's matrices from that pose. If varjo_FrameGetPose() is called after varjo_WaitSync() it will derive matrixes from that pose.

Parameters
sessionVarjo session handle.
typeType of the pose.
Returns
The pose matrix.

◆ varjo_FreeEvent()

void varjo_FreeEvent ( struct varjo_Event event)

Free an event.

Must be allocated with varjo_AllocateEvent.

Parameters
eventEvent to free.

◆ varjo_FreeFrameInfo()

void varjo_FreeFrameInfo ( struct varjo_FrameInfo frameInfo)

Frees an allocated frame info.

Parameters
frameInfoFrame info to free.

◆ varjo_FreeOcclusionMesh()

void varjo_FreeOcclusionMesh ( struct varjo_Mesh2Df mesh)

Frees the memory allocated by varjo_CreateOcclusionMesh.

Parameters
meshOcclusion mesh to free.

◆ varjo_FreeSubmitInfo()

void varjo_FreeSubmitInfo ( struct varjo_SubmitInfo submitInfo)

Frees an allocated submit info.

Parameters
submitInfoSubmit info to free.

◆ varjo_GazeInit()

void varjo_GazeInit ( struct varjo_Session *  session)

Initializes the gaze tracking system.

Parameters
sessionVarjo session handle.

◆ varjo_GetAlignedView()

struct varjo_AlignedView varjo_GetAlignedView ( double *  projectionMatrix)

Gets an aligned view from a projection matrix.

Note: the projection matrix from varjo_FrameInfo might not always be axis aligned.

Parameters
projectionMatrixProjection matrix.
Returns
Aligned view.

◆ varjo_GetCurrentTime()

varjo_Nanoseconds varjo_GetCurrentTime ( struct varjo_Session *  session)

Gets the current time in a format that Varjo API uses.

This is a realtime monotonic counter since system-specific starting point and is not affected by time-of-day setting.

Parameters
sessionVarjo session handle.
Returns
Nanoseconds since epoch.

◆ varjo_GetDefaultSwapChainConfig()

struct varjo_SwapChainConfig varjo_GetDefaultSwapChainConfig ( struct varjo_Session *  session)

Gets the default swap chain config.

Parameters
sessionVarjo session handle.
Returns
Default swap chain config.

◆ varjo_GetError()

varjo_Error varjo_GetError ( struct varjo_Session *  session)

Gets the latest error code.

You should check for errors at least once a frame.

Error status will be cleared after this function.

Use varjo_GetErrorDesc to get more detailed error description.

Returns
Error code if there was an error, varjo_NoError if there wasn't.

◆ varjo_GetErrorDesc()

const char* varjo_GetErrorDesc ( varjo_Error  error)

Gets error description for the specified error code.

Returns
Error description string.

◆ varjo_GetErrorDescription()

VARJO_DEPRECATED_API const char* varjo_GetErrorDescription ( struct varjo_Session *  session)

Gets the current error description string in english.

Returns
Error description string.
Deprecated:
use varjo_GetErrorDesc(varjo_Error)

◆ varjo_GetGaze()

struct varjo_Gaze varjo_GetGaze ( struct varjo_Session *  session)

Gets the current state of the user gaze.

Gaze system must have been previously initialized by calling varjo_GazeInit.

Parameters
sessionVarjo session handle.
Returns
Current state of the user gaze.

◆ varjo_GetGazeArray()

int32_t varjo_GetGazeArray ( struct varjo_Session *  session,
struct varjo_Gaze array,
int32_t  maxSizeOfArray 
)

Gets gaze measurements since last query.

Gaze system must have been previously initialized by calling varjo_GazeInit.

Parameters
sessionVarjo session handle.
arrayArray of varjo_Gaze structures
maxSizeOfArrayNumber of elements in array
Returns
Number of items written to array

◆ varjo_GetPropertyBool()

varjo_Bool varjo_GetPropertyBool ( struct varjo_Session *  session,
varjo_PropertyKey  propertyKey 
)

Gets a boolean value of a property.

Parameters
sessionVarjo session handle.
propertyKeyThe property key.
Returns
Value of a boolean property if exists, false if the property does not exist. Undefined if the key type is not a boolean.

◆ varjo_GetPropertyCount()

int32_t varjo_GetPropertyCount ( struct varjo_Session *  session)

Gets the number of system properties.

Parameters
sessionVarjo session handle.
Returns
Number of system properties.

◆ varjo_GetPropertyDouble()

double varjo_GetPropertyDouble ( struct varjo_Session *  session,
varjo_PropertyKey  propertyKey 
)

Gets a floating point value of a property.

Parameters
sessionVarjo session handle.
propertyKeyThe property key.
Returns
Value of a floating point property if exists, 0.0 if the property does not exist. Undefined if the key type is not a float.

◆ varjo_GetPropertyInt()

int32_t varjo_GetPropertyInt ( struct varjo_Session *  session,
varjo_PropertyKey  propertyKey 
)

Gets an integer value of a property.

Parameters
sessionVarjo session handle.
propertyKeyThe property key.
Returns
Value of an integer property if exists, 0 if the property does not exist. Undefined if the key type is not an integer.

◆ varjo_GetPropertyKey()

varjo_PropertyKey varjo_GetPropertyKey ( struct varjo_Session *  session,
int32_t  index 
)

Gets a property key for a property index.

Parameters
sessionVarjo session handle.
indexZero-based index.
Returns
Key at index location in the properties. 0 if the key index is out of bounds.

◆ varjo_GetPropertyName()

const char* varjo_GetPropertyName ( struct varjo_Session *  session,
varjo_PropertyKey  propertyKey 
)

Gets the name of the property key.

Parameters
sessionVarjo session handle.
propertyKeyThe property key.
Returns
Name of the property key.

◆ varjo_GetRelativePoseTransform()

struct varjo_Matrix varjo_GetRelativePoseTransform ( struct varjo_Session *  session,
varjo_PoseType  src,
varjo_PoseType  dest 
)

Gets a relative transformation from source pose to destination pose.

Parameters
sessionVarjo session handle.
srcSource pose.
destDestination pose.
Returns
Relative transformation from source pose to destination pose.

◆ varjo_GetSupportedTextureFormats()

void varjo_GetSupportedTextureFormats ( struct varjo_Session *  session,
varjo_RenderAPI  renderApi,
int32_t *  formatCount,
varjo_TextureFormat formats 
)

Gets supported texture formats in the order of most preferred to least preferred.

To allocate memory for the formats output buffer, you should first call this function by passing null formats and query the count for the formats.

Parameters
sessionVarjo session handle.
renderApiRendering API being used.
formatCountOutput pointer for the format count. Cannot be null.
formatsOutput pointer for the formats. Can be null.

◆ varjo_GetSwapChainCurrentIndex()

int32_t varjo_GetSwapChainCurrentIndex ( struct varjo_Session *  session)

Gets the current swap chain texture index.

Parameters
sessionVarjo session handle.
Returns
Index of texture to which application should draw.

◆ varjo_GetSwapChainLimits()

struct varjo_SwapChainLimits varjo_GetSwapChainLimits ( struct varjo_Session *  session)

Gets swap chain limits.

Parameters
sessionVarjo session handle.
Returns
Swap chain limits.

◆ varjo_GetVersion()

const uint64_t varjo_GetVersion ( )

Gets the version number of the library.

Use VARJO_MAKE_VERSION macro to create a version that can be then used to test against the returned version number.

eg. VARJO_MAKE_VERSION(0, 7, 0, 0) >= varjo_GetVersion()

Returns
Varjo version number.

◆ varjo_GetVersionString()

const char* varjo_GetVersionString ( )

Gets the short version of the library.

Eg. "0.7.0.0".

Returns
Varjo version string.

◆ varjo_GetViewDescription()

struct varjo_ViewDescription varjo_GetViewDescription ( struct varjo_Session *  session,
int32_t  viewIndex 
)

Gets the display information for a given view.

Use this to retrieve information about which display or eye the given view belongs to.

varjo_ViewDescription also contains the default render texture dimensions.

Parameters
sessionVarjo session handle.
viewIndexView number to get the display information for. Must be in range [0, varjo_GraphicsInfo::viewCount - 1].
Returns
View description.

◆ varjo_HasProperty()

varjo_Bool varjo_HasProperty ( struct varjo_Session *  session,
varjo_PropertyKey  propertyKey 
)

Checks if the key has value in the properties.

Parameters
sessionVarjo session handle.
propertyKeyThe property key.
Returns
1 if the property key has a value, 0 if the value doesn't exist.

◆ varjo_IsAvailable()

varjo_Bool varjo_IsAvailable ( )

Checks whether Varjo system is available.

If varjo_IsAvailable() returns false, it's guaranteed that the session cannot be initialized. If this returns true, application may try initiating a new session.

This call executes fast and can be called per frame unlike varjo_SessionInit.

Returns
0 if Varjo system is not available, 1 if it is available.

◆ varjo_IsGazeAllowed()

varjo_Bool varjo_IsGazeAllowed ( struct varjo_Session *  session)

Is gaze allowed to be used?

User can disallow gaze tracking completely.

Parameters
sessionVarjo session handle.
Returns
varjo_True if gaze is allowed to be used, varjo_False otherwise.

◆ varjo_IsSwapChainConfigSupported()

varjo_Bool varjo_IsSwapChainConfigSupported ( struct varjo_Session *  session,
varjo_RenderAPI  renderApi,
const struct varjo_SwapChainConfig config 
)

Is the given swap chain config supported.

Parameters
sessionVarjo session handle.
renderApiRendering API being used.
configConfig to test.
Returns
varjo_True if the config is supported. If varjo_False, check varjo_GetError for more information.

◆ varjo_LayoutDefaultViewports()

void varjo_LayoutDefaultViewports ( struct varjo_Session *  session,
struct varjo_Viewport viewports 
)

Layout default viewport configuration.

The default view consists of a single texture that contains all the four viewports.

This is a helper function as the viewport can be freely configured.

Parameters
sessionVarjo session handle.
viewportsPointer to varjo_GraphicsInfo::viewCount viewports.

◆ varjo_PollEvent()

varjo_Bool varjo_PollEvent ( struct varjo_Session *  session,
struct varjo_Event evt 
)

Polls events.

Holds the latest 100 events in the queue. If the queue size exceeds that, starts dropping events starting from the oldest. Make sure to call often enough (eg. once per frame) if you don't want to miss an event.

Use this in a loop to go through all of the queued events.

Parameters
sessionVarjo session handle.
evtEvent to receive data to.
Returns
varjo_True if there was an event, varjo_False if all events have been processed.

◆ varjo_RequestGazeCalibration()

void varjo_RequestGazeCalibration ( struct varjo_Session *  session)

Requests a HMD gaze calibration.

This attempts to trigger the gaze calibration sequence if the user has allowed gaze tracking from Varjo settings and Varjo system is in a state where it can bring up the calibration UI.

Parameters
sessionVarjo session handle.

◆ varjo_ResetPose()

void varjo_ResetPose ( struct varjo_Session *  session,
varjo_Bool  position,
varjo_RotationReset  rotation 
)

Resets pose tracking origin.

This will reset the tracking origin to the current transform of the user. rotation parameter can be used to reset only some components of the transform.

Parameters
sessionVarjo session handle.
positionReset position
rotationRotation reset type

◆ varjo_SessionInit()

struct varjo_Session* varjo_SessionInit ( void  )

Initializes a Varjo client session.

varjo_SessionInit initializes a new Varjo session and returns an opaque pointer handle representing the session which should be passed to all Varjo API calls that are related to this session. When done, the session needs to be cleaned up by calling varjo_SessionShutDown.

There can be multiple simultaneous sessions, but generally applications don't need more than one. Single session can be shared between different threads.

◆ varjo_SessionShutDown()

void varjo_SessionShutDown ( struct varjo_Session *  session)

Shuts down a session and releases all the resources internally allocated by Varjo session.

Session pointer will become invalid after calling this function.

Parameters
sessionVarjo session handle.

◆ varjo_SetCenteredProjection()

void varjo_SetCenteredProjection ( struct varjo_Session *  session,
varjo_Bool  enabled 
)

Forces the provided projection matrices to be centered.

This may result in suboptimal resolution.

Parameters
sessionVarjo session handle.
enabledTrue, if the matrices need to be centered. False if off-center projection is ok.

◆ varjo_SyncProperties()

void varjo_SyncProperties ( struct varjo_Session *  session)

Updates and synchronizes system properties with the system state.

Parameters
sessionVarjo session handle.

◆ varjo_UpdateClipPlaneDistances()

void varjo_UpdateClipPlaneDistances ( struct varjo_Session *  session,
double *  projectionMatrix,
double  nearClipDistance,
double  farClipDistance 
)

Updates clip plane distances in the projection matrix.

Uses graphics API convention.

Parameters
sessionVarjo session handle.
projectionMatrixProjection matrix to modify.
nearClipDistanceNear clip distance to use.
farClipDistanceFar clip distance to use.

◆ varjo_WaitSync()

void varjo_WaitSync ( struct varjo_Session *  session,
struct varjo_FrameInfo frameInfo 
)

Called at the start of a frame.

Obtains required metadata for the frame and blocks until optimal time to start rendering so that the application can use the latest possible pose data. In some cases, compositor may block the call for longer duration. (e.g. if it has something else to display.)

varjo_WaitSync() and varjo_FrameGetPose() will always derive matrixes from the same pose. So it's safe to call varjo_FrameGetPose() before varjo_WaitSync() is complete.

Parameters
sessionVarjo session handle.
frameInfoOutput pointer for frame info.