Varjo Native SDK
Varjo_mr.h File Reference

Go to the source code of this file.

Functions

varjo_Bool varjo_Lock (struct varjo_Session *session, varjo_LockType lockType)
 Try to lock the given lock type. More...
 
void varjo_Unlock (struct varjo_Session *session, varjo_LockType lockType)
 Unlock a previously locked lock. More...
 
void varjo_MRSetVideoRender (struct varjo_Session *session, varjo_Bool enabled)
 Start video pass through rendering on the HMD displays. More...
 
void varjo_MRSetVideoDepthEstimation (struct varjo_Session *session, varjo_Bool enabled)
 Start depth estimation for the video pass through image. More...
 
void varjo_MRSetVRViewOffset (struct varjo_Session *session, double percentage)
 Change virtual camera rendering position between users eyes and video pass through cameras. More...
 
void varjo_MRSetChromaKey (struct varjo_Session *session, varjo_Bool enabled)
 Start chroma keying for the video pass through image. More...
 
void varjo_MRSetChromaKeyGlobal (struct varjo_Session *session, varjo_Bool enabled)
 Enables video pass through and starts chroma keying for all application layers regardless if they have chroma key flag set. More...
 
VARJO_DEPRECATED_API varjo_Bool varjo_MRLockChromaKeyConfig (struct varjo_Session *session)
 Try to lock the chroma key configuration. More...
 
VARJO_DEPRECATED_API void varjo_MRUnlockChromaKeyConfig (struct varjo_Session *session)
 Unlock previously locked chroma key configuration. More...
 
int32_t varjo_MRGetChromaKeyConfigCount (struct varjo_Session *session)
 Get number of chroma key config indices supported. More...
 
void varjo_MRSetChromaKeyConfig (struct varjo_Session *session, int32_t index, const struct varjo_ChromaKeyConfig *config)
 Set video chroma keying configuration to select color matcher and setting parameters for it. More...
 
struct varjo_ChromaKeyConfig varjo_MRGetChromaKeyConfig (struct varjo_Session *session, int32_t index)
 Get currently applied chroma keying configuration for given index. More...
 
VARJO_DEPRECATED_API varjo_Bool varjo_MRLockCameraConfig (struct varjo_Session *session)
 Try to lock the camera configuration. More...
 
VARJO_DEPRECATED_API void varjo_MRUnlockCameraConfig (struct varjo_Session *session)
 Unlock previously locked camera configuration. More...
 
int32_t varjo_MRGetCameraPropertyModeCount (struct varjo_Session *session, varjo_CameraPropertyType prop)
 Get amount of camera property modes. More...
 
void varjo_MRGetCameraPropertyModes (struct varjo_Session *session, varjo_CameraPropertyType prop, varjo_CameraPropertyMode *modes, int32_t maxSize)
 Get available property modes. More...
 
varjo_CameraPropertyMode varjo_MRGetCameraPropertyMode (struct varjo_Session *session, varjo_CameraPropertyType type)
 Returns currently set mode for given property type. More...
 
void varjo_MRSetCameraPropertyMode (struct varjo_Session *session, varjo_CameraPropertyType type, varjo_CameraPropertyMode mode)
 Sets property mode. More...
 
varjo_CameraPropertyConfigType varjo_MRGetCameraPropertyConfigType (struct varjo_Session *session, varjo_CameraPropertyType prop)
 Get manual property config type for given property. More...
 
int32_t varjo_MRGetCameraPropertyValueCount (struct varjo_Session *session, varjo_CameraPropertyType prop)
 Get amount of possible manual camera property values. More...
 
void varjo_MRGetCameraPropertyValues (struct varjo_Session *session, varjo_CameraPropertyType prop, struct varjo_CameraPropertyValue *values, int32_t maxSize)
 Get possible manual property values. More...
 
struct varjo_CameraPropertyValue varjo_MRGetCameraPropertyValue (struct varjo_Session *session, varjo_CameraPropertyType type)
 Returns the latest manual property value set with varjo_MRSetCameraPropertyValue for the given property type. More...
 
void varjo_MRSetCameraPropertyValue (struct varjo_Session *session, varjo_CameraPropertyType type, const struct varjo_CameraPropertyValue *value)
 Sets manual property value. More...
 
void varjo_MRResetCameraProperty (struct varjo_Session *session, varjo_CameraPropertyType type)
 Resets the camera property mode and manual mode value to defaults. More...
 
void varjo_MRResetCameraProperties (struct varjo_Session *session)
 Resets all camera properties to the default mode and value. More...
 

Function Documentation

◆ varjo_Lock()

varjo_Bool varjo_Lock ( struct varjo_Session *  session,
varjo_LockType  lockType 
)

Try to lock the given lock type.

Client must successfully acquire lock before any calls to features behind the lock.

varjo_Unlock must be called after the feature is not needed anymore and it is free to be used by other clients.

Each lock type can be locked by one application at a time. Lock call returns varjo_True if the calling client holds the lock after the call. If the lock was held by the calling client already, varjo_Error_AlreadyLocked error is set. Return value is varjo_False if another client is holding the lock.

Note: Application needs to hold the lock as long it is going to use the feature.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_AlreadyLocked

Parameters
sessionVarjo session handle.
lockTypeLock type to be locked.
Returns
varjo_True if the client holds the lock after the call, otherwise varjo_False.

◆ varjo_MRGetCameraPropertyConfigType()

varjo_CameraPropertyConfigType varjo_MRGetCameraPropertyConfigType ( struct varjo_Session *  session,
varjo_CameraPropertyType  prop 
)

Get manual property config type for given property.

Config type can be:

  • List: List of discrete values.
  • Range: Min and max values.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType

Parameters
sessionVarjo session handle.
propCamera property type.

◆ varjo_MRGetCameraPropertyMode()

varjo_CameraPropertyMode varjo_MRGetCameraPropertyMode ( struct varjo_Session *  session,
varjo_CameraPropertyType  type 
)

Returns currently set mode for given property type.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType

Parameters
sessionVarjo session handle.
typeCamera property type.
Returns
Current mode.

◆ varjo_MRGetCameraPropertyModeCount()

int32_t varjo_MRGetCameraPropertyModeCount ( struct varjo_Session *  session,
varjo_CameraPropertyType  prop 
)

Get amount of camera property modes.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType

Parameters
sessionVarjo session handle.
propCamera property type.

◆ varjo_MRGetCameraPropertyModes()

void varjo_MRGetCameraPropertyModes ( struct varjo_Session *  session,
varjo_CameraPropertyType  prop,
varjo_CameraPropertyMode modes,
int32_t  maxSize 
)

Get available property modes.

The needed size for the 'modes' output parameter can be obtained by calling varjo_MRGetCameraPropertyModeCount.

If manual property mode is supported, varjo_MRSetCameraPropertyValue can be used to set the manual property value.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType

Parameters
sessionVarjo session handle.
propCamera property type.
modesFills this array with the possible property modes.
maxSizeMaximum amount of modes that fit into 'modes'. Should be >= varjo_MRGetCameraPropertyModeCount().

◆ varjo_MRGetCameraPropertyValue()

struct varjo_CameraPropertyValue varjo_MRGetCameraPropertyValue ( struct varjo_Session *  session,
varjo_CameraPropertyType  type 
)

Returns the latest manual property value set with varjo_MRSetCameraPropertyValue for the given property type.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType

Parameters
sessionVarjo session handle.
typeCamera property type.
Returns
Current value.

◆ varjo_MRGetCameraPropertyValueCount()

int32_t varjo_MRGetCameraPropertyValueCount ( struct varjo_Session *  session,
varjo_CameraPropertyType  prop 
)

Get amount of possible manual camera property values.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType

Parameters
sessionVarjo session handle.
propCamera property type.

◆ varjo_MRGetCameraPropertyValues()

void varjo_MRGetCameraPropertyValues ( struct varjo_Session *  session,
varjo_CameraPropertyType  prop,
struct varjo_CameraPropertyValue values,
int32_t  maxSize 
)

Get possible manual property values.

The needed size for the 'values' output parameter can be obtained by calling GetCameraPropertyValueCount.

Values have different meaning depending on the property.

  • ExposureTime: Floating point frames per second. e.g. 90.0 -> ~11ms exposure time.
  • ISOValue: Integer ISO values. e.g. "200" -> ISO200.
  • WhiteBalance: Integer color temperatures in Kelvin.
  • FlickerCompensation: Integer in Hz. e.g "50" -> compensation for 50 Hz. This is useful when using the HMD indoors with mostly artificial light bulbs, which flicker at the frequency of 50Hz or 60Hz and can cause visual flicker artifacts on the video pass through image. The correct setting depends on the underlying power grid's frequency. e.g. In most parts of Africa/Asia/Australia/Europe the frequency is 50 Hz and in most parts of North and South America 60 Hz.
  • Sharpness: Integer denoting the power of the sharpness filter. The lowest value corresponds to small amount of filtering and the highest value corresponds to the largest amount of filtering.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType

Parameters
sessionVarjo session handle.
propCamera property type.
valuesFills this array with the possible property values. It's either a list or a range depending on the property. This can be determined from GetCameraPropertyConfigType-call.
maxSizeMaximum amount of values that fit into 'values'. Should be >= GetCameraPropertyValueCount().

◆ varjo_MRGetChromaKeyConfig()

struct varjo_ChromaKeyConfig varjo_MRGetChromaKeyConfig ( struct varjo_Session *  session,
int32_t  index 
)

Get currently applied chroma keying configuration for given index.

Use varjo_MRGetChromaKeyConfigCount for getting maximum count.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_IndexOutOfBounds

Parameters
sessionVarjo session handle.
indexChroma key index.
Returns
Currently applied chroma keying configuration.

◆ varjo_MRGetChromaKeyConfigCount()

int32_t varjo_MRGetChromaKeyConfigCount ( struct varjo_Session *  session)

Get number of chroma key config indices supported.

Maximum index will be count-1.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable

Parameters
sessionVarjo session handle.
Returns
Number of supported chroma key configs.

◆ varjo_MRLockCameraConfig()

VARJO_DEPRECATED_API varjo_Bool varjo_MRLockCameraConfig ( struct varjo_Session *  session)

Try to lock the camera configuration.

This call needs to succeed before calls to

varjo_MRUnlockCameraConfig should be called after the configuration has been changed.

The configuration can be locked by one application at a time. Locking fails, if another client has the configuration locked already.

Note: If an application wants to prevent others from changing the camera settings, the lock can be held for a long period of time.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraAlreadyLocked

Parameters
sessionVarjo session handle.
Returns
varjo_True if locked successfully, otherwise varjo_False.
Deprecated:
varjo_Lock provides generic lock functionality for mixed reality features.

◆ varjo_MRLockChromaKeyConfig()

VARJO_DEPRECATED_API varjo_Bool varjo_MRLockChromaKeyConfig ( struct varjo_Session *  session)

Try to lock the chroma key configuration.

This call needs to succeed before any calls altering the chroma key config state.

varjo_MRUnlockChromaKeyConfig should be called after the configuration has been changed.

The configuration can be locked by one application at a time. Locking fails, if another client has the configuration locked already.

Note: If an application wants to prevent others from changing the chroma key settings, the lock can be held for a long period of time.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_ChromaKeyAlreadyLocked

Parameters
sessionVarjo session handle.
Returns
varjo_True if locked successfully, otherwise varjo_False.
Deprecated:
varjo_Lock provides generic lock functionality for mixed reality features.

◆ varjo_MRResetCameraProperties()

void varjo_MRResetCameraProperties ( struct varjo_Session *  session)

Resets all camera properties to the default mode and value.

Before calling this function, camera config has to be locked succesfully with varjo_MRLockCameraConfig.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType, varjo_Error_CameraNotLocked

Parameters
sessionVarjo session handle.

◆ varjo_MRResetCameraProperty()

void varjo_MRResetCameraProperty ( struct varjo_Session *  session,
varjo_CameraPropertyType  type 
)

Resets the camera property mode and manual mode value to defaults.

Before calling this function, camera config has to be locked succesfully with varjo_MRLockCameraConfig.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType, varjo_Error_CameraNotLocked

Parameters
sessionVarjo session handle.
typeCamera property type.

◆ varjo_MRSetCameraPropertyMode()

void varjo_MRSetCameraPropertyMode ( struct varjo_Session *  session,
varjo_CameraPropertyType  type,
varjo_CameraPropertyMode  mode 
)

Sets property mode.

Before calling this function, camera config has to be locked succesfully with varjo_MRLockCameraConfig.

While property mode is set to manual, the camera uses the latest manual property value set with varjo_MRSetCameraPropertyValue.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType, varjo_Error_CameraInvalidPropertyMode, varjo_Error_CameraNotLocked

Parameters
sessionVarjo session handle.
typeCamera property type.
modeCamera property mode to be set.

◆ varjo_MRSetCameraPropertyValue()

void varjo_MRSetCameraPropertyValue ( struct varjo_Session *  session,
varjo_CameraPropertyType  type,
const struct varjo_CameraPropertyValue value 
)

Sets manual property value.

Before calling this function, camera config has to be locked succesfully with varjo_MRLockCameraConfig.

While property mode is set to manual, the camera uses the latest set property value. The value can be set even if property mode is not set to manual, in which case the camera starts using it once mode is set to manual.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraInvalidPropertyType, varjo_Error_CameraInvalidPropertyValue, varjo_Error_CameraNotLocked

Parameters
sessionVarjo session handle.
typeCamera property type.
valueConst pointer to camera property value to be set.

◆ varjo_MRSetChromaKey()

void varjo_MRSetChromaKey ( struct varjo_Session *  session,
varjo_Bool  enabled 
)

Start chroma keying for the video pass through image.

This enables occlusion between VR and MR content when the VR content is submitted as a layer with chroma key testing enabled (varjo_LayerFlag_ChromaKeyMasking).

This setting is ignored unless varjo_MRSetVideoRender has been enabled.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable

Parameters
sessionVarjo session handle.
enabledOn/off toggle.

◆ varjo_MRSetChromaKeyConfig()

void varjo_MRSetChromaKeyConfig ( struct varjo_Session *  session,
int32_t  index,
const struct varjo_ChromaKeyConfig config 
)

Set video chroma keying configuration to select color matcher and setting parameters for it.

Index can be used to set multiple chroma key configs that will all be evaluated into a single mask. Use varjo_MRGetChromaKeyConfigCount for getting maximum count. Config values will be clamped to valid range.

Before calling this function, chroma key config has to be locked succesfully with varjo_MRLockChromaKeyConfig.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable varjo_Error_ChromaKeyNotLocked, varjo_Error_ChromaKeyInvalidType, varjo_Error_IndexOutOfBounds

Parameters
sessionVarjo session handle.
indexChroma key index.
configPointer to chroma key configuration structure to be applied.

◆ varjo_MRSetChromaKeyGlobal()

void varjo_MRSetChromaKeyGlobal ( struct varjo_Session *  session,
varjo_Bool  enabled 
)

Enables video pass through and starts chroma keying for all application layers regardless if they have chroma key flag set.

Varjo system layers are not chroma keyed. This is used as force override to make it possible to run non-MR applications with chroma keying. For application specific chroma keying, use varjo_MRSetChromaKey.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable

Parameters
sessionVarjo session handle.
enabledToggle global override on/off.

◆ varjo_MRSetVideoDepthEstimation()

void varjo_MRSetVideoDepthEstimation ( struct varjo_Session *  session,
varjo_Bool  enabled 
)

Start depth estimation for the video pass through image.

This enables occlusion between VR and MR content when the VR content is submitted as a layer with a depth buffer attachment (varjo_ViewExtensionDepth) and depth testing enabled (varjo_LayerFlag_DepthTesting).

The default depth test range is [0m, 0.75m]. This means that depth test against the video layer is performed only at close distance (hands), and beyond that VR content is always visible. Applications can override this behavior by providing explicit depth test range in varjo_ViewExtensionDepthTestRange extension. In that case, default is not used and depth test is calculated according to the application provided range. This is useful for enabling the full depth range.

This setting is ignored unless varjo_MRSetVideoRender has been enabled.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable

Parameters
sessionVarjo session handle.
enabledOn/off toggle.

◆ varjo_MRSetVideoRender()

void varjo_MRSetVideoRender ( struct varjo_Session *  session,
varjo_Bool  enabled 
)

Start video pass through rendering on the HMD displays.

Video is rendered as a background layer. i.e. Any application rendering is done on top of the video, unless occlusion is enabled (varjo_MRSetVideoDepthEstimation).

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable

Parameters
sessionVarjo session handle.
enabledOn/off.

◆ varjo_MRSetVRViewOffset()

void varjo_MRSetVRViewOffset ( struct varjo_Session *  session,
double  percentage 
)

Change virtual camera rendering position between users eyes and video pass through cameras.

The scene is rendered twice from the position of the users eyes. In full VR the eye position corresponds to the physical position of the users eyes. When using video pass through there is a physical offset between the users eyes and the stereo camera pair. So in contrast to full VR, when rendering in MR mode: To remove stereo disparity problems between the real and virtual world and prevent 'floating' of the VR objects anchored to the real world, the scene should be rendered from the physical position of the camera pair in most cases. This is the default mode and corresponds to setting eye offset 'percentage' to 1.0.

But there can be scenes that are predominantly VR where it makes sense to render the scene using the VR eye position. e.g. The scene only contains a small 'magic window' to view the real world or the real world is only shown as a backdrop.

This function can be used to switch the rendering position. It can be used for smooth interpolated change in case it needs to be done the middle of the scene.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable

Parameters
sessionVarjo session handle.
percentage[0.0, 1.0] Linear interpolation of the rendering position between the position of HMD users eyes and the video pass through camera position. Given value will be clamped to the accepted range.

◆ varjo_MRUnlockCameraConfig()

VARJO_DEPRECATED_API void varjo_MRUnlockCameraConfig ( struct varjo_Session *  session)

Unlock previously locked camera configuration.

Note: After unlocking the configuration other applications are free to modify the settings.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_CameraNotLocked

Parameters
sessionVarjo session handle.
Deprecated:
varjo_Unlock provides generic unlock functionality for mixed reality features.

◆ varjo_MRUnlockChromaKeyConfig()

VARJO_DEPRECATED_API void varjo_MRUnlockChromaKeyConfig ( struct varjo_Session *  session)

Unlock previously locked chroma key configuration.

Note: After unlocking the configuration other applications are free to modify the settings.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_ChromaKeyNotLocked

Parameters
sessionVarjo session handle.
Deprecated:
varjo_Unlock provides generic unlock functionality for mixed reality features.

◆ varjo_Unlock()

void varjo_Unlock ( struct varjo_Session *  session,
varjo_LockType  lockType 
)

Unlock a previously locked lock.

If the lock was not held by the calling client, varjo_Error_NotLocked error is set. This is the case if the lock is not locked at all or another client has the lock.

Note: After unlocking the lock other applications are free to acquire the lock and access locked features at any time.

Possible errors: varjo_Error_OperationFailed, varjo_Error_NotAvailable, varjo_Error_CapabilityNotAvailable, varjo_Error_NotLocked

Parameters
sessionVarjo session handle.
lockTypeLock type to be locked.