org.lwjgl.openxr.HTCXViveTrackerInteraction Maven / Gradle / Ivy

Go to download
/*
 * Copyright LWJGL. All rights reserved.
 * License terms: https://www.lwjgl.org/license
 * MACHINE GENERATED FILE, DO NOT EDIT
 */
package org.lwjgl.openxr;

import org.jspecify.annotations.*;

import java.nio.*;

import org.lwjgl.system.*;

import static org.lwjgl.system.Checks.*;
import static org.lwjgl.system.JNI.*;
import static org.lwjgl.system.MemoryUtil.*;

/**
 * The XR_HTCX_vive_tracker_interaction extension.
 * 
 * This extension defines a new interaction profile for HTC VIVE Tracker. HTC VIVE Tracker is a generic tracked device which can be attached to anything to make them trackable. For example, it can be attached to user’s hands or feet to track the motion of human body. It can also be attached to any other devices the user wants to track and interact with.
 * 
 * In order to enable the functionality of this extension, you must pass the name of the extension into {@link XR10#xrCreateInstance CreateInstance} via the {@link XrInstanceCreateInfo} {@code enabledExtensionNames} parameter as indicated in the extension section.
 * 
 * This extension allows:
 * 
 * 
 * An application to enumerate the subpaths of all current connected VIVE trackers.
 * An application to receive notification of the top level paths of a VIVE tracker when it is connected.
 * 
 * 
 * The paths of a VIVE tracker contains two paths below:
 * 
 * 
 * VIVE tracker persistent path indicate a specific tracker whose lifetime lasts longer than an instance, which means it must not change during its hardware lifetime. The format of this path string is unspecified and should be treated as an opaque string.
 * VIVE tracker role path may be constructed as "/user/vive_tracker_htcx/role/ROLE_VALUE", where ROLE_VALUE takes one of the following values. The role path may be assigned from the tool provided by the runtime and is {@link XR10#XR_NULL_PATH NULL_PATH} if it has not been assigned. If this role path refers to more than one tracker, the runtime should choose one of them to be currently active. The role path may be changed during the lifetime of instance. Whenever it is changed, the runtime must send event {@link #XR_TYPE_EVENT_DATA_VIVE_TRACKER_CONNECTED_HTCX TYPE_EVENT_DATA_VIVE_TRACKER_CONNECTED_HTCX} to provide the new role path of that tracker.
 * 
 * 
 * ROLE_VALUE
 * 
 * {@code XR_NULL_PATH}
 * {@code handheld_object}
 * {@code left_foot}
 * {@code right_foot}
 * {@code left_shoulder}
 * {@code right_shoulder}
 * {@code left_elbow}
 * {@code right_elbow}
 * {@code left_knee}
 * {@code right_knee}
 * {@code left_wrist} (rev: 3)
 * {@code right_wrist} (rev: 3)
 * {@code left_ankle} (rev: 3)
 * {@code right_ankle} (rev: 3)
 * {@code waist}
 * {@code chest}
 * {@code camera}
 * {@code keyboard}
 * 
 * 
 * 
 * Either the persistent path or the role path can be be passed as a subaction path to indicate a specific tracker. For example, {@link XrActionCreateInfo}{@code ::subactionPaths} into function {@link XR10#xrCreateAction CreateAction} or {@link XrActionSpaceCreateInfo}{@code ::subactionPath} into function {@link XR10#xrCreateActionSpace CreateActionSpace}. Please see Example 1 below.
 * 
 * 
 * As with other controllers, if a VIVE tracker is connected and bound to a top-level user path, or disconnected while bound to top-level user path, the runtime must send event {@link XR10#XR_TYPE_EVENT_DATA_INTERACTION_PROFILE_CHANGED TYPE_EVENT_DATA_INTERACTION_PROFILE_CHANGED}, and the application may call {@link XR10#xrGetCurrentInteractionProfile GetCurrentInteractionProfile} to check if the tracker is active or not.
 * 
 * The device that a tracker is attached to probably has a different motion model than what the tracker assumes. The motion tracking might not be as expected in this case.
 */
public class HTCXViveTrackerInteraction {

    /** The extension specification version. */
    public static final int XR_HTCX_vive_tracker_interaction_SPEC_VERSION = 3;

    /** The extension name. */
    public static final String XR_HTCX_VIVE_TRACKER_INTERACTION_EXTENSION_NAME = "XR_HTCX_vive_tracker_interaction";

    /**
     * Extends {@code XrStructureType}.
     * 
     * Enum values:
     * 
     * 
     * {@link #XR_TYPE_VIVE_TRACKER_PATHS_HTCX TYPE_VIVE_TRACKER_PATHS_HTCX}
     * {@link #XR_TYPE_EVENT_DATA_VIVE_TRACKER_CONNECTED_HTCX TYPE_EVENT_DATA_VIVE_TRACKER_CONNECTED_HTCX}
     * 
     */
    public static final int
        XR_TYPE_VIVE_TRACKER_PATHS_HTCX                = 1000103000,
        XR_TYPE_EVENT_DATA_VIVE_TRACKER_CONNECTED_HTCX = 1000103001;

    protected HTCXViveTrackerInteraction() {
        throw new UnsupportedOperationException();
    }

    // --- [ xrEnumerateViveTrackerPathsHTCX ] ---

    /**
     * Unsafe version of: {@link #xrEnumerateViveTrackerPathsHTCX EnumerateViveTrackerPathsHTCX}
     *
     * @param pathCapacityInput the capacity of the {@code paths}, or 0 to retrieve the required capacity.
     */
    public static int nxrEnumerateViveTrackerPathsHTCX(XrInstance instance, int pathCapacityInput, long pathCountOutput, long paths) {
        long __functionAddress = instance.getCapabilities().xrEnumerateViveTrackerPathsHTCX;
        if (CHECKS) {
            check(__functionAddress);
        }
        return callPPPI(instance.address(), pathCapacityInput, pathCountOutput, paths, __functionAddress);
    }

    /**
     * Enumerates all connected VIVE trackers.
     * 
     * C Specification
     * 
     * The {@link #xrEnumerateViveTrackerPathsHTCX EnumerateViveTrackerPathsHTCX} function is defined as:
     * 
     * 
     * XrResult xrEnumerateViveTrackerPathsHTCX(
     *     XrInstance                                  instance,
     *     uint32_t                                    pathCapacityInput,
     *     uint32_t*                                   pathCountOutput,
     *     XrViveTrackerPathsHTCX*                     paths);
     * 
     * Description
     * 
     * {@link #xrEnumerateViveTrackerPathsHTCX EnumerateViveTrackerPathsHTCX} enumerates all connected VIVE trackers to retrieve their paths under current instance.
     * 
     * Valid Usage (Implicit)
     * 
     * 
     * The {@link HTCXViveTrackerInteraction XR_HTCX_vive_tracker_interaction} extension must be enabled prior to calling {@link #xrEnumerateViveTrackerPathsHTCX EnumerateViveTrackerPathsHTCX}
     * {@code instance} must be a valid {@code XrInstance} handle
     * {@code pathCountOutput} must be a pointer to a {@code uint32_t} value
     * If {@code pathCapacityInput} is not 0, {@code paths} must be a pointer to an array of {@code pathCapacityInput} {@link XrViveTrackerPathsHTCX} structures
     * 
     * 
     * Return Codes
     * 
     * 
     * On success, this command returns
     * 
     * {@link XR10#XR_SUCCESS SUCCESS}
     * 
     * On failure, this command returns
     * 
     * {@link XR10#XR_ERROR_FUNCTION_UNSUPPORTED ERROR_FUNCTION_UNSUPPORTED}
     * {@link XR10#XR_ERROR_VALIDATION_FAILURE ERROR_VALIDATION_FAILURE}
     * {@link XR10#XR_ERROR_RUNTIME_FAILURE ERROR_RUNTIME_FAILURE}
     * {@link XR10#XR_ERROR_HANDLE_INVALID ERROR_HANDLE_INVALID}
     * {@link XR10#XR_ERROR_INSTANCE_LOST ERROR_INSTANCE_LOST}
     * {@link XR10#XR_ERROR_SIZE_INSUFFICIENT ERROR_SIZE_INSUFFICIENT}
     * 
     * 
     * 
     * See Also
     * 
     * {@link XrViveTrackerPathsHTCX}
     *
     * @param instance        an instance previously created.
     * @param pathCountOutput a pointer to the count of {@link XrViveTrackerPathsHTCX} {@code paths} written, or a pointer to the required capacity in the case that {@code pathCapacityInput} is insufficient.
     * @param paths           a pointer to an array of {@link XrViveTrackerPathsHTCX} VIVE tracker paths, but can be {@code NULL} if {@code pathCapacityInput} is 0.
     */
    @NativeType("XrResult")
    public static int xrEnumerateViveTrackerPathsHTCX(XrInstance instance, @NativeType("uint32_t *") IntBuffer pathCountOutput, @NativeType("XrViveTrackerPathsHTCX *") XrViveTrackerPathsHTCX.@Nullable Buffer paths) {
        if (CHECKS) {
            check(pathCountOutput, 1);
        }
        return nxrEnumerateViveTrackerPathsHTCX(instance, remainingSafe(paths), memAddress(pathCountOutput), memAddressSafe(paths));
    }

}