API Reference


GestureFailure StartGestureDetection(GestureOption *option)

Start detection with given option, non-blocking.

option is both in/out parameter. GestureOption::mode Mode of option may be modified if requirements is not met on the device. The resulting mode is the actual mode used in detection. If option is null, default option will be used (auto backend + best mode).

void StopGestureDetection()

Stop the detection. Blocking call until the pipeline is actually stopped.

int GetGestureResult(const GestureResult **points, int *frameIndex)

Get detection result in world coordinate. Returns at most one left and one right hand. Return value is number of detections in points, at most 2.

You should call this function periodically to get latest results.

Points:(return value) A pointer to an array of GestureResult. The pointer is valid until next call to GetGestureResult() or StopGestureDetection(). The pointer need NOT to be freed.
FrameIndex:(return value) A pointer to frame index (can be null). This can be used to check if results are updated. Set to -1 if detection is not started or stopped due to error.

Example usage:

const GestureResult* points = NULL;
int frameIndex;
int size = GetGestureResult(&points, &frameIndex);
void UseExternalTransform(bool value)

This function should be called before StartGestureDetection to indicate if caller is providing camera transform or not. Default is false. Call it after StartGestureDetection has no use.

If set to true, the result points are in camera coordinate instead of world coordinate and caller is responsible for applying camera transform to the result points. This is useful if the camera position is different from OpenVR & WaveVR raw HMD data, useful for cases like teleporting.

Currently, this is used in Unity & Unreal plugin.


class GestureOption

Struct used as input/output parameter for StartGestureDetection().

GestureBackend backend = GestureBackend::GestureBackendAuto

Backend to use.

GestureMode mode = GestureMode::GestureModeSkeleton

Mode to use.

class GestureResult

Struct containing detection result for one hand.

bool isLeft

Returns if this hand is left/right.

float points[63]

Returns position of the hand. The meaning of this field is different based on actual GestureMode.

Index (3*i, 3*i+1, 3*i+2) composes a (x, y, z) point. There is total 21 points. +x is right, +y is up, +z is front. Unit is meter.

  • GestureMode2DPoint

    Only first point is used as the position of hand. z is always 0.25.

  • GestureMode3DPoint

    Only first point is used as the position of hand. z is calculated depth.

  • GestureModeSkeleton

    The points is a 21-sized array with all the keypoints of the hand. See Hand Positions (Modes) for order of the keypoints.


    Some keypoints may be missing due to occulusion from other objects or hand itself. In such cases, a place-holder position is returned which cannot be used as real position. Use x == 0 && y == 0 && z == 0 to check if a keypoint is valid.

GestureType gesture

Returns pre-defined gesture type.

float confidence

Returns confidence of the hand, within [0, 1].

float pinchLevel

Returns pinch (thumb & index) level of the hand, within [0, 1], higher means more possible to pinch. Recommended threshold is PINCH_LEVEL_THRESHOLD.

Enums & Constants


Default threshold for pinch level. Levels higher than PINCH_LEVEL_THRESHOLD (0.7) is pinching.

enum GestureBackend

Enum for selecting computation backend.

enumerator GestureBackendAuto = 0

Default backend, use GPU on PC and CPU on Android. Recommended.

enumerator GestureBackendCPU = 1

Use CPU, not supported on PC

enumerator GestureBackendGPU = 2

Use GPU, supported on PC/Android

enum GestureMode

Enum for detection mode. Larger mode return more info, but runs more slowly. If a mode is not supported on a device, will fallback to previous supported mode.

See also

See Hand Positions (Modes) section for detailed modes description.

enumerator GestureMode2DPoint = 0

Fastest mode, return one 2d point for hand.

enumerator GestureMode3DPoint = 1

Return one 3d point for hand, supported on all dual camera devices.

enumerator GestureModeSkeleton = 2

Return skeleton (21 points) for hand, supported on PC and Focus.

enum GestureType

Enum for predefined gesture classification.

See also

See Pre-defined gesture classification section for detailed gesture description.

enumerator GestureTypeUnknown = 0

All other gestures not in predefined set.

enumerator GestureTypePoint = 1
enumerator GestureTypeFist = 2
enumerator GestureTypeOK = 3
enumerator GestureTypeLike = 4
enumerator GestureTypeFive = 5
enumerator GestureTypeVictory = 6
enum GestureFailure

Enum for possible errors in hand detection.

enumerator GestureFailureNone = 0

No error occurs.

enumerator GestureFailureOpenCL = -1

(Only on Windows) OpenCL is not supported on the machine.

See also

See Notes for Windows for possible solutions.

enumerator GestureFailureCamera = -2

Start camera failed. This happens if Vive Hand Tracking SDK failed to get camera frames.

  • Windows: See Camera Setup for possible solutions.
  • Android phone & WaveVR: Make sure camera permission is granted before start detection.
    • Some phones does not support NDK Camera2 API (or return no cameras in API).
    • Most WaveVR devices other than Vive Focus does not support camera API yet.
enumerator GestureFailureInternal = -10

Internal errors.

enumerator GestureFailureCPUOnPC = -11

CPU backend is not supported on Windows. Please use different backend when you start detection.