6 Summary of API Function

6.1 Get version information

getSDKVersion

Function name: String getSDKVersion ()

Functions: Get SDK version number.

Parameter: none

Return value: SDK version number

Method of calling: PicovrSDK.getSDKVersion ()

6.2 Render related

SetEyeBufferSize

Function name: void SetEyeBufferSize( int width, int height)

Functions: Set the size of eye buffers. And this function should be called while activity “onResume()” to make it effective. It can’t take effect dynamically.

Parameter: width: length in horizontal direction ;height: length in vertical direction .

Return value: none

Method of calling: PicovrSDK.SetEyeBufferSize( 1920, 1920 )

GetEyeBufferWidth

Function name: int GetEyeBufferWidth()

Functions: Get the width of eye buffers.

Parameter: none

Return value: width of eye buffers.

Method of calling: PicovrSDK.GetEyeBufferWidth()

GetEyeBufferHeight

Function name: int GetEyeBufferHeight()

Functions: Get the height of eye buffers.

Parameter: none

Return value: height of eye buffers.

Method of calling: PicovrSDK.GetEyeBufferHeight()

setProjectionFov

Function name: void setProjectionFov(float fovDegreesX, float fovDegreesY)

Functions: Set render FOV value. At present, the two values should be the same. And this function should be called while activity “onResume()” to make it effective. It can’t take effect dynamically.

Parameter: fovDegreesX: FOV in horizontal direction ;fovDegreesY: FOV in vertical direction .

Return value: none

Method of calling: PicovrSDK. setProjectionFov (120f,120f)

nativeSetMultisamples

Function name: void nativeSetMultisamples(long nativePtr, int samples)

Functions: Set the property of eyebuffer anti-aliasing. Please note that this is a member function of VRActivity and should be called in onCreate() of its sub-class. If too late, it may not take effect because eyebuffer has completed initialization.

Parameter： nativePtr: A pointer to NativeApp instance. In the oncreate() function of vractivity, getnativeptr() will be called and the return value will be saved in the member variable “nativePtr”. Please pass in the variable as a parameter directly；

Samples: Anti-aliasing sampling multiple, currently supports 0, 2, 4.

Return value: none

Method of calling: this.nativeSetMultisamples(this.nativePtr,4);

6.3 Sensor tracking related

startSensor

Function name: int startSensor (int index)

Functions: Start sensor tracking

Parameter: 0

Return value: 0: Call success; 1: Call failure

Method of calling: PicovrSDK.startSensor (0)

stopSensor

Function name: int stopSensor (int index)

Functions: Stop sensor tracking

Parameter: 0

Return value: 0: Call success; 1: Call failure

Method of calling: PicovrSDK.stopSensor(0)

resetSensor

Function name: int resetSensor (int index)

Functions: Reset sensor tracking, the direction is determined by the system, and the horizontal and vertical directions are reset by default

Parameter: 0

Return value: 0: Call success; 1: Call failure

Method of calling: PicovrSDK.resetSensor (0)

resetSensorWithOption

Function name: int resetSensorWithOption (int index, int resetRot, int resetPos)

Functions: Selectively reset sensor attitude and position

Parameter: index: 0 resetRot: Orientation resetPos: Position 0: Not reset 1: Reset

Return value: 0: Call success; 1: Call failure

Method of calling: PicovrSDK.resetSensorWithOption(0,1,1)

GetMainSensor

Function name: float [] GetMainSensor ()

Functions: Get the direction and position data of the main Sensor. Please call it after the SDK is running normally. If the SDK is not initialized normally, the call fails and the default value is returned.

Parameter: none

Return value: float array, including {x, y, z, w, px, py, pz}

Method of calling: PicovrSDK.GetMainSensor()

getHmdPose

Function name: float [] getHmdPose (float time)

Functions: Get the predicted direction and position data of the main Sensor. Please call it after the SDK is running normally. If the SDK is not initialized normally, the call fails and the default value is returned.

Parameter: time: predict time, unit is millisecond

Return value: float array, including {x, y, z, w, px, py, pz}

Method of calling: for example, predict the data after 50ms, PicovrSDK.getHmdPose( 50 )

getPredictedDisplayTime

Function name: float getPredictedDisplayTime( )

Functions: Predict the time interval for the next frame to refresh to the screen.

Parameter: none.

Return value: millisecond.

Method of calling: for example, float predict = PicovrSDK.getPredictedDisplayTime( );

getPredictedHeadPoseState

Function name: int getPredictedHeadPoseState(float timeInMs, float[] data, long[] timeStamp)

Functions: Obtain the pose data of the specified prediction time.

Parameter:

timeInMs: Prediction time, unit is millisecond.

data: Contains the acquired pose data, in order of {x, y, z, w, px, py, pz}.

timestamp: Contains the timestamp of the acquired pose, in order of { poseTimeStampNs, poseFetchTimeNs, expectedDisplayTimeNs }.

Return value: The quality of pose data increases from 0 to 3

Method of calling: for example, predict the data after 50ms, PicovrSDK.getPredictedHeadPoseState( 50, poseData, poseTime);

nativeSetRenderPose

Function name: void nativeSetRenderPose( long nativePtr, float[] pose, long[] timeStamp )

Functions: Submit the pose data used for rendering the scene to the SDK. This interface should be called in “onFrameEnd”. If you choose to use the pose data in callback interface “onFrameBegin”, you do not need to call this interface again.

Parameter:

nativePtr : NativeApp pointer. Store in “nativePtr” field when VRActivity be created.

pose : pose data in order of {x, y, z, w, px, py, pz}.

timestamp : timestamps of pose data in order of { poseTimeStampNs, poseFetchTimeNs, expectedDisplayTimeNs }.

Return value: none

Method of calling: for example, nativeSetRenderPose(nativePtr,poseData,poseTime);

6.4 Power, volume and brightness related

Note: Please apply for permission to modify system settings before realizing these functions. Refer to Android Universal Implementation Solution for details.

Pvr_InitAudioDevice

Function name: void Pvr_InitAudioDevice (Context context)

Functions: Initialize volume service

Parameter: Context

Return value: none

Method of calling: SysActivity.Pvr_InitAudioDevice (context)

Pvr_GetMaxAudionumber

Function name: int Pvr_GetMaxAudionumber ()

Functions: Get maximum volume

Parameter: none

Return value: Maximum volume

Method of calling: SysActivity. Pvr_GetMaxAudionumber ()

Pvr_GetAudionumber

Function name: int Pvr_GetAudionumber ()

Functions: Get current volume

Parameter: none

Return value: Current volume value (range from 0 to 15)

Method of calling: SysActivity.Pvr_GetAudionumber ()

Pvr_UpAudio

Function name: void Pvr_UpAudio ()

Functions: Volume Up

Parameter: none

Return value: none

Method of calling: SysActivity.Pvr_UpAudio ()

Pvr_DownAudio

Function name: void Pvr_DownAudio ()

Functions: Volume Down

Parameter: none

Return value: none

Method of calling: SysActivity.Pvr_DownAudio ()

Pvr_ChangeAudio

Function name: void Pvr_ChangeAudio (int num)

Functions: Set volume

Parameter: Set the volume value (volume value range from 0 to 15)

Return value: none

Method of calling: SysActivity.Pvr_ChangeAudio (num)

Pvr_GetCommonBrightness

Function name: int Pvr_GetCommonBrightness (Context context)

Functions: Get the current common device brightness value

Parameter: Context

Return value: Current brightness value (brightness values range from 0 to 255)

Method of calling: SysActivity.Pvr_GetCommonBrightness (context)

Pvr_SetCommonBrightness

Function name: boolean Pvr_SetCommonBrightness (int num, Context context)

Functions: Set the current common device brightness value

Parameter: Current brightness value (brightness values range from 0 to 255), Context

Return value: true: true, false: false

Method of calling: SysActivity.Pvr_SetCommonBrightness (num,context)

6.5 Controller related

6.5.1 Pico Goblin/G2

Description for main class：

1. HbManager.java

※public void InitServices()

Initialize and bind HummingBirdControllerService

※public void Pause() , public void Resume()

When the program enters the background, unregister the broadcast receiver and unbind HummingBirdControllerService. Reconnect it when resumed.

※public void setHbListener(HbListener listener)

Set listener for HbController

※public HbController getHbController()

Get HbController object

2. HbController.java

HbController class will be updated to the internal variables after getting the controller data from system-related service, which can be got from the functional interface. See Table 6.1 for details.

※public void Start() , public void Stop()

Control the registration and logout of listeners

※public void update()

Update the controller data (acceleration, angular velocity, quaternion, and key values), and notify the listener to execute the corresponding callback function

※public void startUpdateThread(), public void stopUpdateThread()

Control the start and end of internal update thread in HbController The thread calls update( ) every 15ms to read the controller data when the controller is connected. Developers can use the thread directly or call the update( ) interface as needed.

API	Description
public int getConnectState()	Get the controller connection status , Return value 0: Disconnect , Return value 1: Connecting , Return value 2: Connected
public boolean getButtonState(ButtonNum b)	Get the controller specified key status, (False: Up True: Down)
public int getBatteryLevel()	Get the controller power, Return value range: 1~5
public Orientation getOrientation()	Get the quaternion to which the controller is currently pointing {x,y,z,w} See com.picovr.client.Orientation class for the return value of SDK interface
public float[] getAccel()	Get the acceleration data of the controller {x,y,z} It’s a Float[3] array
public float[] getAngular()	Get the angular velocity data of the controller {x,y,z} It’s a Float[3] array
public long getLastUpdateTimeStamp()	Get the timestamp of the last update data for the controller.
public boolean isTouching()	Query whether the controller TouchPad is in touch state (False: Not touch, true: Touching)
public int[] getTouchPosition()	Get the touch coordinates of the controller TouchPad {x,y}
public int getTrigerKeyEvent()	Get the analog data of Trigger key of the controller (valid for G2 controller) Return value: 0，Up；1，Down

Table 6.1 HbController Function Interface

3. HbListener.java

※ public void onConnect();

Controller connection

※ public void onDisconnect();

Controller disconnection

※ public void onDataUpdate();

Controller data updated

※ public void onReCenter();

It has no actual function. Abandoned.

※ public void onBindService();

System HummingBirdControllerService bound successfully

6.5.2 Pico Neo/Neo 2/Neo 3

The following are the main class descriptions in the jar package:

1. CVControllerManager.java

※ public void bindService() , public void unbindService()

Responsible for binding and unbinding system services, called when the application starts and pauses, such as onResume, onPause for Activity.

※ public void setListener(CVControllerListener listener)

Set up the listener to callback the notifications of the controller status.

※ public CVController getMainController() , public CVController getSubController()

Only for Pico Neo, you can get the objects of the main controller and the sub-controller by these interfaces.

※ public CVController getLeftController() , public CVController getRightController()

Only for Pico Neo 2/Neo 3, you can get the objects of the left controller and the right controller by these interfaces. Note that, for Pico Neo 2/Neo 3, if you need getting the main/sub attribute of controllers, you can call the following interface:

ControllerClient.getMainControllerIndex();

Its return value is serial number of controllers. Value 0 means that left controller is main. Value 1 means that right controller is main.

※ public void updateControllerData(float[] hmdData) Only applicable for Pico Neo 2/Neo 3, use this interface to update controller data

2. CVController.java

• Before acquiring controller data using APIs listed below, it’s required to firstly call interface CVControllerManager.updateControllerData(float[] hmdData)

@Override
public void onFrameBegin(HmdState hmdState) {
    float[] hmdOrientation = hmdState.getOrientation();
    float[] hmdPosition = hmdState.getPos();
    float[] hmdData = new float[7];
    hmdData[0] = hmdOrientation[0];
    hmdData[1] = hmdOrientation[1];
    hmdData[2] = hmdOrientation[2];
    hmdData[3] = hmdOrientation[3];

    hmdData[4] = hmdPosition[0];
    hmdData[5] = hmdPosition[1];
    hmdData[6] = hmdPosition[2];

    cvManager.updateControllerData(hmdData);
}

API	Description
public int getConnectState()	Get the controller connection status Return value 0: Disconnect Return value 1: Connect
public int getSerialNum()	Get the serial number identification of the controller.Neo controller is universal. This serial number is only for index, and has no practical significance.Neo2/Neo3 controller hardware is divided into left and right. 0 represents left hand and 1 represents right hand.
public int get6DofAbility()	Get the ability of the controller 6Dof， Return value 1: Support 3Dof only, Return value 0 or 2: Support 6Dof
public boolean getButtonState(ButtonNum b)	Get the controller specified key status (False: Up True: Down)
public int getBatteryLevel()	Get the controller power. Return value scope: Pico Neo ，0~10 Pico Neo2/Neo3 ，1~5
public float[] getOrientation()	Get the quaternion to which the controller is currently pointing {x,y,z,w},The interface returns to Float[4] array
public float[] getPosition()	Get the position data of the controller {x,y,z}, The interface returns to Float[3] array
public float[] getAcc()	Get the acceleration data of the controller {x,y,z}, It’s a Float[3] array
public float[] getAgl()	Get the angular velocity data of the controller {x,y,z},It’s a Float[3] array
public int getTriggerNum()	Get the trigger data of the Trigger key for the controller Range 0~255
public int[] getTouchPad ()	Get the touch coordinates of the controller TouchPad {x,y},The interface returns to int[2] array
public float[] getDataPredict(float var1)	Get the direction and position data predicted of the controller. Parameter: predicted time in millisecond. The interface returns an array of float [7], including {x, y, z, w, px, py, pz}
public static void vibrateCV2ControllerStrength(float strength,int time,int controllerSerialNum) Note: this interface is defined in ControllerClient class, can be called by using ControllerClient.vibrateCV2ControllerStrength.	Set the vibration of controller. Parameter: strength, range 0~1 time, range 0~65535 ms ； controllerSerialNum, 0 left, 1 right

Table 6.2 CVController Function Interface

3. CVControllerListener.java

※ Public void onBindSuccess();

Binding system service succeeded.

※ public void onBindFail();

Binding system service abnormally disconnected

※ public void onThreadStart();

Binding system service successfully, start normal operation

※ public void onConnectStateChanged(int serialNum,int state);

Controller connection status changes, serialNum: controller serial no., state: connection

※ public void onMainControllerChanged(int serialNum);

Main controller changes, serialNum: main controller serial no.

On Pico Neo, the objects of the main and sub controllers can be updated through “getMainController” and “getSubController” after receiving the notification.

On Pico Neo 2/Neo 3, you always get the object of the left controller through “getMainController”, and get the object of the right controller through “getSubController”.

※ public void onChannelChanged(int device, int channel);

The connection channel of controller changes. device: controller serial no., channel: connection channel.

6.5.3 ArmModel simulation

SDK provides an algorithm that simulates the ArmModel for use with 3dof controller. It can simulate the motion path of human arm, calculate a 3d coordinate, and apply the coordinate to the rendering of the controller model to make up for the lack of 6dof data, so as to make the experience more real.

getPvrHandness

Function name: int getPvrHandness(Context context)

Functions: Get the leftgrip and rightgrip parameters in system settings

Parameter: context

Return value: 0, rightgrip; 1, leftgrip.

Method of calling: VrActivity.getPvrHandness(context)

setArmModelParameter

Function name: void setArmModelParameter(int hand, int gazeType, float elbowHeight, float elbowDepth, float pointerTiltAngle);

Functions: Set ArmModel parameter

Parameter： hand 0: right hand, 1: left hand, default 0

gazeType 0: Never，1: During Motion, 2: Always, Default 1

elbowHeight default 0.0f

elbowDepth default 0.0f

pointerTiltAngle default 15.0f

Return value: none

Method of calling: PicovrSDK.setArmModelParameter(0,1,0,0,15)

setControllerData

Function name: void setControllerData (float[] orientation, float[] accel, float[] gyro, int[] keyData )

Functions: transfer the controller data to ArmModel

Parameter： orientation, quaternion

accel, accelerometer data

Gyro, Gyroscope data

keyData, Key data

Return value: none

Method of calling: PicovrSDK.setControllerData ( orientation, accel, gyro, keyData )

calcArmModelParameters

Function name: void calcArmModelParameters ()

Functions: calculate ArmModel position according to controller data Note that calls should be made before getPointerPose ().

Parameter: none

Return value: none

Method of calling: PicovrSDK. calcArmModelParameters()

getPointerPose

Function name: void getPointerPose ( float[] rotation, float[] position)

Functions: get the position and direction of the controller calculated by ArmModel

Parameter： rotation , quaternion

position ，three-dimensional coordinate

Return value: none

Method of calling: PicovrSDK.getPointerPose ( rotation, position）

6.6 SeeThrough Camera related

GetSeethroughFrameFU

Function name: void GetSeethroughFrameFU(int eye, int textureId);

Functions: assign seethrough image data to texture

Parameter：eye: 0：LeftEye，1: RightEye,

textureId: opengl texture handle

Return value: none

Method of calling: PicovrSDK.GetSeeThroughFrameFU(eye, textureId)

SetCameraImageRect

Function name: void SetCameraImageRect(int width, int height)

Functions: set the width and height of the seethrough image, In pixels

Parameter：width: the width of the image,

height: the height of the image

Return value: none

Method of calling: PicovrSDK.SetCameraImageRect(width, height);

StartCameraPreview

Function name: void StartCameraPreview(int value)

Function: enable/disable seethrough camera preview

Parameter: value 0: disable，1: enable

Return value: none

Method of calling: PicovrSDK.StartCameraPreview(value);