sxrApi.h

Go to the documentation of this file.

//=============================================================================
//
//                  Copyright (c) 2018 QUALCOMM Technologies Inc.
//                              All Rights Reserved.
//
//==============================================================================

#ifndef _SXR_API_H_
#define _SXR_API_H_

#include <stdlib.h>
#include <jni.h>

#define SXR_MAJOR_VERSION       3
#define SXR_MINOR_VERSION       0
#define SXR_REVISION_VERSION    2

#define SXR_MAX_RENDER_LAYERS   16

enum SxrResult
{
    // Return code for success
    SXR_ERROR_NONE = 0,

    // Return code for cases that don't fall into defined error codes
    SXR_ERROR_UNKNOWN = 1,

    // Return code to indicate that SXR isn't supported, or the necessary functionality in the system drivers
    // or VR service isn't supported.
    SXR_ERROR_UNSUPPORTED,

    // Return code for calls to functions made without first calling sxrInitialize
    SXR_ERROR_VRMODE_NOT_INITIALIZED,

    // Return code for calls made into functions that require VR mode to be in a started state
    SXR_ERROR_VRMODE_NOT_STARTED,

    // Return code for calls made into functions that require VR mode to be in a stopped state
    SXR_ERROR_VRMODE_NOT_STOPPED,

    // Return code for calls made into functions where the service fails or isn't accessible
    SXR_ERROR_QVR_SERVICE_UNAVAILABLE,

    // Error for any failures in JNI/Java calls made through the API
    SXR_ERROR_JAVA_ERROR,
};

enum sxrEventType
{
    kEventNone = 0,
    kEventSdkServiceStarting = 1,
    kEventSdkServiceStarted = 2,
    kEventSdkServiceStopped = 3,
    kEventControllerConnecting = 4,
    kEventControllerConnected = 5,
    kEventControllerDisconnected = 6,
    kEventThermal = 7,
    kEventVrModeStarted = 8,
    kEventVrModeStopping = 9,
    kEventVrModeStopped = 10,
    kEventSensorError = 11,
    kEventMagnometerUncalibrated = 12,
    kEventBoundarySystemCollision = 13,
    kEvent6dofRelocation = 14,
    kEvent6dofWarningFeatureCount = 15,
    kEvent6dofWarningLowLight = 16,
    kEvent6dofWarningBrightLight = 17,
    kEvent6dofWarningCameraCalibration = 18
};

struct ANativeWindow;

struct sxrVector2
{
    float x,y;
};

struct sxrVector3
{
    float x,y,z;
};

struct sxrVector4
{
    float x,y,z,w;
};

struct sxrQuaternion
{
    float x, y, z, w;
};

struct sxrMatrix4
{
    float M[4][4];
};

enum sxrWhichEye
{
    kLeftEye = 0,
    kRightEye,
    kNumEyes
};

enum sxrEyeMask
{
    kEyeMaskLeft = 0x00000001,
    kEyeMaskRight = 0x00000002,
    kEyeMaskBoth = 0x00000003
};

enum sxrLayerFlags
{
    kLayerFlagNone       = 0x00000000,
    kLayerFlagHeadLocked = 0x00000001,
    kLayerFlagOpaque     = 0x00000002
};

enum sxrColorSpace
{
    kColorSpaceLinear = 0,
    kColorSpaceSRGB = 1,
    kNumColorSpaces
};

struct sxrHeadPose
{
    sxrQuaternion   rotation;
    sxrVector3      position;
};

enum sxrTrackingMode
{
    kTrackingRotation = (1 << 0),
    kTrackingPosition = (1 << 1),
    kTrackingEye      = (1 << 2)
};

struct sxrHeadPoseState
{
    sxrHeadPose         pose;                   
    int32_t             poseStatus;             
    uint64_t            poseTimeStampNs;        
    uint64_t            poseFetchTimeNs;        
    uint64_t            expectedDisplayTimeNs;  
};

enum sxrEyePoseStatus
{
    kGazePointValid             = (1 << 0),
    kGazeVectorValid            = (1 << 1),
    kEyeOpennessValid           = (1 << 2),
    kEyePupilDilationValid      = (1 << 3),
    kEyePositionGuideValid      = (1 << 4)
};

struct sxrEyePoseState
{
    int64_t             timestamp;                  

    int32_t             leftEyePoseStatus;          
    int32_t             rightEyePoseStatus;         
    int32_t             combinedEyePoseStatus;      
    
    float               leftEyeGazePoint[3];        
    float               rightEyeGazePoint[3];       
    float               combinedEyeGazePoint[3];    

    float               leftEyeGazeVector[3];       
    float               rightEyeGazeVector[3];      
    float               combinedEyeGazeVector[3];   

    float               leftEyeOpenness;            
    float               rightEyeOpenness;           

    float               leftEyePupilDilation;       
    float               rightEyePupilDilation;      

    float               leftEyePositionGuide[3];    
    float               rightEyePositionGuide[3];   
};

enum sxrPerfLevel
{
    kPerfSystem     = 0,            
    kPerfMinimum    = 1,            
    kPerfMedium     = 2,            
    kPerfMaximum    = 3,            
    kNumPerfLevels
};

enum sxrOptionFlags
{
    kProtectedContent = (1 << 0),
    kMotionAwareFrames = (1 << 1)
};

struct sxrBeginParams
{
    int32_t         mainThreadId;           
    sxrPerfLevel    cpuPerfLevel;           
    sxrPerfLevel    gpuPerfLevel;           
    ANativeWindow*  nativeWindow;           
    int32_t         optionFlags;            
    sxrColorSpace   colorSpace;             
};

enum sxrFrameOption
{
    kDisableDistortionCorrection    = ( 1 << 0 ),   
    kDisableReprojection            = ( 1 << 1 ),   
    kEnableMotionToPhoton           = ( 1 << 2 ),   
    kDisableChromaticCorrection     = ( 1 << 3 )   
};

enum sxrTextureType
{
    kTypeTexture = 0,               
    kTypeTextureArray,              
    kTypeImage,                     
    kTypeEquiRectTexture,           
    kTypeEquiRectImage,             
    kTypeCubemapTexture,            
    kTypeVulkan,                    
};

struct sxrVulkanTexInfo
{
    uint32_t            memSize;
    uint32_t            width;
    uint32_t            height;
    uint32_t            numMips;
    uint32_t            bytesPerPixel;
    uint32_t            renderSemaphore;
};


enum sxrWarpType
{
    kSimple                         
};

enum sxrWarpMeshType
{
    kMeshTypeColumsLtoR = 0,    // Columns Left to Right
    kMeshTypeColumsRtoL,        // Columns Right to Left
    kMeshTypeRowsTtoB,          // Rows Top to Bottom
    kMeshTypeRowsBtoT,          // Rows Bottom to Top
};

enum sxrWarpMeshEnum
{
    kMeshEnumLeft = 0,  // Column mesh for left half of screen
    kMeshEnumRight,     // Column mesh for right half of screen
    kMeshEnumUL,        // Row mesh for Upper Left part of the screen
    kMeshEnumUR,        // Row mesh for Upper Right part of the screen
    kMeshEnumLL,        // Row mesh for Lower Left part of the screen
    kMeshEnumLR,        // Row mesh for Lower Right part of the screen
    kWarpMeshCount
};

struct sxrLayoutCoords
{
    float               LowerLeftPos[4];                        
    float               LowerRightPos[4];                       
    float               UpperLeftPos[4];                        
    float               UpperRightPos[4];                       

    float               LowerUVs[4];                            
    float               UpperUVs[4];                            

    float               TransformMatrix[16];                    
};

struct sxrRenderLayer
{
    int32_t             imageHandle;        
    sxrTextureType      imageType;          
    sxrLayoutCoords     imageCoords;        
    sxrEyeMask          eyeMask;            
    uint32_t            layerFlags;         
    sxrVulkanTexInfo    vulkanInfo;         
};


struct sxrFrameParams
{
    int32_t             frameIndex;                             
    int32_t             minVsyncs;                              

    sxrRenderLayer      renderLayers[SXR_MAX_RENDER_LAYERS];    

    uint32_t            frameOptions;                           
    sxrHeadPoseState    headPoseState;                          
    sxrWarpType         warpType;                               
    float               fieldOfView;                            
};

struct sxrInitParams
{
    JavaVM*         javaVm;                 
    JNIEnv*         javaEnv;                
    jobject         javaActivityObject;     
};

struct sxrViewFrustum
{
    float               left;           
    float               right;          
    float               top;            
    float               bottom;         

    float               near;           
    float               far;            
};

struct sxrFoveation
{
    sxrVector2 gain;             
    float area;                  
    float minimum;               
};

struct sxrDeviceInfo
{
    int32_t         displayWidthPixels;         
    int32_t         displayHeightPixels;        
    float           displayRefreshRateHz;       
    int32_t         displayOrientation;         
    int32_t         targetEyeWidthPixels;       
    int32_t         targetEyeHeightPixels;      
    float           targetFovXRad;              
    float           targetFovYRad;              
    sxrViewFrustum  leftEyeFrustum;             
    sxrViewFrustum  rightEyeFrustum;            
    float           targetEyeConvergence;       
    float           targetEyePitch;             
    int32_t         deviceOSVersion;            
    sxrWarpMeshType warpMeshType;               
    sxrFoveation    lowFoveation;               
    sxrFoveation    medFoveation;               
    sxrFoveation    highFoveation;              

    // Tracking Camera
    float           trackingCalibration[12];    
    float           trackingPrincipalPoint[2];  
    float           trackingFocalLength[2];     
    float           trackingRadialDist[8];      
};

enum sxrThermalLevel
{
    kSafe,
    kLevel1,
    kLevel2,
    kLevel3,
    kCritical,
    kNumThermalLevels
};

enum sxrThermalZone
{
    kCpu,
    kGpu,
    kSkin,
    kNumThermalZones
};

struct sxrEventData_Thermal
{
    sxrThermalZone  zone;               
    sxrThermalLevel level;              
};

typedef union 
{
    sxrEventData_Thermal    thermal;
    uint32_t                data[2];
} sxrEventData;

struct sxrEvent
{
    sxrEventType    eventType;              
    uint32_t        deviceId;               
    float           eventTimeStamp;         
    sxrEventData    eventData;              
};

enum sxrControllerMessageType
{
    kControllerMessageRecenter = 0,
    kControllerMessageVibration = 1
};

enum sxrControllerQueryType
{
    kControllerQueryBatteryRemaining = 0,
    kControllerQueryControllerCaps = 1
};

enum sxrControllerConnectionState {
    kNotInitialized = 0,
    kDisconnected = 1,
    kConnected = 2,
    kConnecting = 3,
    kError = 4
};

namespace sxrControllerTouch {
  enum {
    None                = 0x00000000,
    One                 = 0x00000001,
    Two                 = 0x00000002,
    Three               = 0x00000004,
    Four                = 0x00000008,
    PrimaryThumbstick   = 0x00000010,
    SecondaryThumstick  = 0x00000020,
    Any                 = ~None
  };
}

namespace sxrControllerAxis1D {
enum {
  PrimaryIndexTrigger   = 0x00000000,
  SecondaryIndexTrigger = 0x00000001,
  PrimaryHandTrigger    = 0x00000002,
  SecondaryHandTrigger  = 0x00000003
};
}

namespace sxrControllerAxis2D {
enum {
  PrimaryThumbstick     = 0x00000000,
  SecondaryThumbstick   = 0x00000001
};
}

namespace sxrControllerButton {
enum {
  None                    = 0x00000000,
  One                     = 0x00000001,
  Two                     = 0x00000002,
  Three                   = 0x00000004,
  Four                    = 0x00000008,
  DpadUp                  = 0x00000010,
  DpadDown                = 0x00000020,
  DpadLeft                = 0x00000040,
  DpadRight               = 0x00000080,
  Start                   = 0x00000100,
  Back                    = 0x00000200,
  PrimaryShoulder         = 0x00001000,
  PrimaryIndexTrigger     = 0x00002000,
  PrimaryHandTrigger      = 0x00004000,
  PrimaryThumbstick       = 0x00008000,
  PrimaryThumbstickUp     = 0x00010000,
  PrimaryThumbstickDown   = 0x00020000,
  PrimaryThumbstickLeft   = 0x00040000,
  PrimaryThumbstickRight  = 0x00080000,
  SecondaryShoulder       = 0x00100000,
  SecondaryIndexTrigger   = 0x00200000,
  SecondaryHandTrigger    = 0x00400000,
  SecondaryThumbstick     = 0x00800000,
  SecondaryThumbstickUp   = 0x01000000,
  SecondaryThumbstickDown = 0x02000000,
  SecondaryThumbstickLeft = 0x04000000,
  SecondaryThumbstickRight = 0x08000000,
  Up                      = 0x10000000,
  Down                    = 0x20000000,
  Left                    = 0x40000000,
  Right                   = 0x80000000,
  Any                     = ~None
};
}

// Current state of the controller
struct sxrControllerState {
    sxrQuaternion   rotation;

    sxrVector3      position;
    
    sxrVector3      gyroscope;
    
    sxrVector3      accelerometer;
    
    uint64_t        timestamp;

    uint32_t        buttonState;   
    
    sxrVector2      analog2D[4];       

    float           analog1D[8];       

    uint32_t        isTouching;
     
    sxrControllerConnectionState connectionState;
};

// Caps of the Controller.
struct sxrControllerCaps {
    char deviceManufacturer[64];
    
    char deviceIdentifier[64];
    
    uint32_t caps; //0 bit = Provides Rotation; 1 bit = Position;

    uint32_t activeButtons;
    
    uint32_t active2DAnalogs;
    
    uint32_t active1DAnalogs;
    
    uint32_t activeTouchButtons;
};

#ifndef SXRP_EXPORT
    #define SXRP_EXPORT
#endif

#ifdef __cplusplus 
extern "C" {
#endif

SXRP_EXPORT const char* sxrGetVersion();

SXRP_EXPORT SxrResult sxrGetXrServiceVersion(char *pRetBuffer, int bufferSize);

SXRP_EXPORT SxrResult sxrGetXrClientVersion(char *pRetBuffer, int bufferSize);

SXRP_EXPORT SxrResult sxrInitialize(const sxrInitParams* pInitParams);

SXRP_EXPORT SxrResult sxrShutdown();

SXRP_EXPORT sxrDeviceInfo   sxrGetDeviceInfo();

SXRP_EXPORT SxrResult sxrSetPerformanceLevels(sxrPerfLevel cpuPerfLevel, sxrPerfLevel gpuPerfLevel);

SXRP_EXPORT SxrResult sxrBeginXr(const sxrBeginParams* pBeginParams);

SXRP_EXPORT SxrResult sxrEndXr();

SXRP_EXPORT float sxrGetPredictedDisplayTime();

SXRP_EXPORT float sxrGetPredictedDisplayTimePipelined(unsigned int depth);

SXRP_EXPORT sxrHeadPoseState sxrGetPredictedHeadPose( float predictedTimeMs );

SXRP_EXPORT sxrHeadPoseState sxrGetHistoricHeadPose(int64_t timestampNs);

SXRP_EXPORT SxrResult sxrGetEyePose(sxrEyePoseState *pReturnPose);

SXRP_EXPORT SxrResult sxrRecenterPose();

SXRP_EXPORT SxrResult sxrRecenterPosition();

SXRP_EXPORT SxrResult sxrRecenterOrientation(bool yawOnly=true);

SXRP_EXPORT uint32_t sxrGetSupportedTrackingModes();

SXRP_EXPORT SxrResult sxrSetTrackingMode(uint32_t trackingModes);

SXRP_EXPORT uint32_t sxrGetTrackingMode();

SXRP_EXPORT bool sxrPollEvent(sxrEvent *pEvent);

SXRP_EXPORT SxrResult sxrBeginEye(sxrWhichEye whichEye, sxrTextureType imageType = kTypeTexture);

SXRP_EXPORT SxrResult sxrEndEye(sxrWhichEye whichEye, sxrTextureType imageType = kTypeTexture);

SXRP_EXPORT SxrResult sxrSubmitFrame(const sxrFrameParams* pFrameParams);

SXRP_EXPORT int sxrControllerStartTracking(const char* controllerDesc);

SXRP_EXPORT void sxrControllerStopTracking(int controllerHandle);

SXRP_EXPORT sxrControllerState sxrControllerGetState(int controllerHandle, int controllerSpace = 0);

SXRP_EXPORT void sxrControllerSendMessage(int controllerHandle, int what, int arg1, int arg2);

SXRP_EXPORT int sxrControllerQuery(int controllerHandle, int what, void* memory, unsigned int memorySize);

SXRP_EXPORT SxrResult sxrSetWarpMesh(sxrWarpMeshEnum whichMesh, void *pVertexData, int vertexSize, int nVertices, unsigned int* pIndices, int nIndices);

SXRP_EXPORT SxrResult sxrGetOcclusionMesh(sxrWhichEye whichEye, int *pTriangleCount, int *pVertexStride, float *pTriangles);

SXRP_EXPORT bool sxrIsBoundarySystemEnabled();

SXRP_EXPORT void sxrEnableBoundarySystem(bool enableBoundary = true);

SXRP_EXPORT void sxrForceDisplayBoundarySystem(bool forceDisplayBoundary = true);

SXRP_EXPORT SxrResult sxrSetBoundaryParameters(float *pMinValues, float *pMaxValues, float visibilityRadius);

SXRP_EXPORT SxrResult sxrGetBoundaryParameters(float *pMinValues, float *pMaxValues, float *pVisibilityRadius);

#ifdef __cplusplus 
}
#endif

#endif //_SXR_API_H_