Tracker Target API module

Contents

Upon initialization, the zSpace Core SDK creates instances of the Tracker Target API and registers them to the tracker device. The zSpace display's built-in tracking cameras are an example of a tracker device. The zSpace stylus and polarized glasses are examples of tracker targets. Other peripheral devices, such as mice, can also be tracker targets.

Classes

struct ZCTrackerPose
Struct representing tracker pose information.

Enums

enum ZCTargetType { ZC_TARGET_TYPE_HEAD = 0, ZC_TARGET_TYPE_PRIMARY = 1, ZC_TARGET_TYPE_SECONDARY = 2 }

Typedefs

using ZCTargetType = enum ZCTargetType
using ZCTrackerPose = struct ZCTrackerPose
Struct representing tracker pose information.

Functions

auto zcGetNumTargets(ZCHandle deviceHandle, ZSInt32* numTargets) -> ZCError
auto zcGetNumTargetsByType(ZCContext context, ZCTargetType targetType, ZSInt32* numTargets) -> ZCError
auto zcGetTarget(ZCHandle deviceHandle, ZSInt32 index, ZCHandle* targetHandle) -> ZCError
auto zcGetTargetByName(ZCHandle deviceHandle, const char* targetName, ZCHandle* targetHandle) -> ZCError
auto zcGetTargetByType(ZCContext context, ZCTargetType targetType, ZSInt32 index, ZCHandle* targetHandle) -> ZCError
auto zcGetTargetName(ZCHandle targetHandle, char* buffer, ZSInt32 bufferSize) -> ZCError
auto zcGetTargetNameSize(ZCHandle targetHandle, ZSInt32* size) -> ZCError
auto zcSetTargetEnabled(ZCHandle targetHandle, ZSBool isEnabled) -> ZCError
auto zcIsTargetEnabled(ZCHandle targetHandle, ZSBool* isEnabled) -> ZCError
auto zcIsTargetVisible(ZCHandle targetHandle, ZSBool* isVisible) -> ZCError
auto zcSetTargetMoveEventThresholds(ZCHandle targetHandle, ZSFloat time, ZSFloat distance, ZSFloat angle) -> ZCError
auto zcGetTargetMoveEventThresholds(ZCHandle targetHandle, ZSFloat* time, ZSFloat* distance, ZSFloat* angle) -> ZCError
auto zcGetTargetPose(ZCHandle targetHandle, ZCTrackerPose* pose) -> ZCError
auto zcGetTargetTransformedPose(ZCHandle targetHandle, ZCHandle viewportHandle, ZCCoordinateSpace coordinateSpace, ZCTrackerPose* pose) -> ZCError
auto zcSetTargetPoseBufferingEnabled(ZCHandle targetHandle, ZSBool isPoseBufferingEnabled) -> ZCError
auto zcIsTargetPoseBufferingEnabled(ZCHandle targetHandle, ZSBool* isPoseBufferingEnabled) -> ZCError
auto zcGetTargetPoseBuffer(ZCHandle targetHandle, ZSFloat minDelta, ZSFloat maxDelta, ZCTrackerPose* buffer, ZSInt32* bufferSize) -> ZCError
auto zcResizeTargetPoseBuffer(ZCHandle targetHandle, ZSInt32 capacity) -> ZCError
auto zcGetTargetPoseBufferCapacity(ZCHandle targetHandle, ZSInt32* capacity) -> ZCError

Enum documentation

enum ZCTargetType

Defines the types of tracker targets.

Enumerators
ZC_TARGET_TYPE_HEAD

The tracker target corresponding to the user's head.
ZC_TARGET_TYPE_PRIMARY

The tracker target corresponding to the user's primary hand.
ZC_TARGET_TYPE_SECONDARY

The tracker target corresponding to the user's secondary hand. (Reserved for future use.)

Typedef documentation

typedef enum ZCTargetType ZCTargetType

Defines the types of tracker targets.

typedef struct ZCTrackerPose ZCTrackerPose

Struct representing tracker pose information.

This structure is used by the Tracker Target, Display, and Stereo Frustum APIs.

Function documentation

ZCError zcGetNumTargets(ZCHandle deviceHandle, ZSInt32* numTargets)

Parameters
deviceHandle in A handle to the tracker device.
numTargets out The number of tracker targets for the specified device.

Gets the number of tracker targets owned by a specified tracker device.

ZCError zcGetNumTargetsByType(ZCContext context, ZCTargetType targetType, ZSInt32* numTargets)

Parameters
context in A handle to the internal state of the zSpace SDK.
targetType in The type of tracker target to query.
numTargets out The number of tracker targets of the specified type.

Gets the number of tracker targets of a specified type.

ZCError zcGetTarget(ZCHandle deviceHandle, ZSInt32 index, ZCHandle* targetHandle)

Parameters
deviceHandle in A handle to the tracker device
index in Index into the underlying list of targets owned by the specified device.
targetHandle out A handle to the tracker target.

Gets the handle to a tracker target based on a specified index. Always start with an index equal to 0. This should be used in conjunction with zcGetNumTargets().

ZCError zcGetTargetByName(ZCHandle deviceHandle, const char* targetName, ZCHandle* targetHandle)

Parameters
deviceHandle in A handle to the tracker device.
targetName in Name of the tracker target.
targetHandle out A handle to the tracker target.

Gets the handle to a tracker target by name.

ZCError zcGetTargetByType(ZCContext context, ZCTargetType targetType, ZSInt32 index, ZCHandle* targetHandle)

Parameters
context in A handle to the internal state of the zSpace SDK.
targetType in The type of tracker target to query.
index in Index for the tracker target in the underlying list of all targets of the specified type.
targetHandle out A handle to the tracker target.

Gets the handle to a tracker target based on a specified type and index. Always start with an index equal to 0. This should be used in conjunction with zcGetNumTargetsByType().

ZCError zcGetTargetName(ZCHandle targetHandle, char* buffer, ZSInt32 bufferSize)

Parameters
targetHandle in A handle to the tracker target.
buffer out The user allocated character buffer to store the target's name.
bufferSize in The size of the user allocated buffer.

Gets the tracker target's name.

ZCError zcGetTargetNameSize(ZCHandle targetHandle, ZSInt32* size)

Parameters
targetHandle in A handle to the tracker target.
size out The size of the name in bytes.

Gets the size of the tracker target's name in bytes.

ZCError zcSetTargetEnabled(ZCHandle targetHandle, ZSBool isEnabled)

Parameters
targetHandle in A handle to the tracker target.
isEnabled in True to enable, false otherwise.

Sets whether or not the tracker target is enabled. Disabling a tracker target causes it to no longer update its pose information.

ZCError zcIsTargetEnabled(ZCHandle targetHandle, ZSBool* isEnabled)

Parameters
targetHandle in A handle to the tracker target.
isEnabled out True if enabled, false otherwise.

Checks whether a tracker target is enabled.

ZCError zcIsTargetVisible(ZCHandle targetHandle, ZSBool* isVisible)

Parameters
targetHandle in A handle to the tracker target.
isVisible out True if visible, false otherwise.

Checks whether a tracker target is visible. For a zSpace-specific tracker target, this checks whether or not the target is currently visible and tracked by the zSpace tracking cameras.

ZCError zcSetTargetMoveEventThresholds(ZCHandle targetHandle, ZSFloat time, ZSFloat distance, ZSFloat angle)

Parameters
targetHandle in A handle to the tracker target.
time in The time threshold in seconds.
distance in The distance threshold in meters.
angle in The angle threshold in degrees.

Sets the thresholds that control the frequency of move events for the tracker target. Use this function to increase or decrease the target's sensitivity when generating events for physical movement.

For some change in time 't', distance 'd', and angle 'a' since the last move event, thresholds are applied in the following logical manner to generate new events:

(t >= time) && ((d >= distance) || (a >= angle))

ZCError zcGetTargetMoveEventThresholds(ZCHandle targetHandle, ZSFloat* time, ZSFloat* distance, ZSFloat* angle)

Parameters
targetHandle in A handle to the tracker target.
time out The time threshold in seconds.
distance out The distance threshold in meters.
angle out The angle threshold in degrees.

Gets the thresholds that control the frequency of move events for the tracker target.

ZCError zcGetTargetPose(ZCHandle targetHandle, ZCTrackerPose* pose)

Parameters
targetHandle in A handle to the tracker target.
pose out The last valid tracker-space pose.

Gets the tracker target's last valid tracker-space pose.

ZCError zcGetTargetTransformedPose(ZCHandle targetHandle, ZCHandle viewportHandle, ZCCoordinateSpace coordinateSpace, ZCTrackerPose* pose)

Parameters
targetHandle in A handle to the tracker target.
viewportHandle in A handle to the viewport.
coordinateSpace in The coordinate space to transform the pose to.
pose out The last valid transformed pose.

Gets the tracker target's last valid pose in the specified coordinate space.

ZCError zcSetTargetPoseBufferingEnabled(ZCHandle targetHandle, ZSBool isPoseBufferingEnabled)

Parameters
targetHandle in A handle to the tracker target.
isPoseBufferingEnabled in True to enable pose buffering, false otherwise.

Enables or disables pose buffering. Each buffered pose is timestamped so that the tracker target's movement can be queried over a specified time interval.

ZCError zcIsTargetPoseBufferingEnabled(ZCHandle targetHandle, ZSBool* isPoseBufferingEnabled)

Parameters
targetHandle in A handle to the tracker target.
isPoseBufferingEnabled out True if enabled, false otherwise.

Checks whether pose buffering is enabled.

ZCError zcGetTargetPoseBuffer(ZCHandle targetHandle, ZSFloat minDelta, ZSFloat maxDelta, ZCTrackerPose* buffer, ZSInt32* bufferSize)

Parameters
targetHandle in A handle to the tracker target.
minDelta in A timestamp relative to the current time, in seconds.
maxDelta in A timestamp relative to the current time, in seconds.
buffer out A user allocated buffer of ZCTrackerPoses.
bufferSize in/out The size of the user allocated pose buffer.

Gets the tracker target's pose buffer for the specified time period.

ZCError zcResizeTargetPoseBuffer(ZCHandle targetHandle, ZSInt32 capacity)

Parameters
targetHandle in A handle to the tracker target.
capacity in The new capacity of the pose buffer.

Resizes the pose buffer.

ZCError zcGetTargetPoseBufferCapacity(ZCHandle targetHandle, ZSInt32* capacity)

Parameters
targetHandle in A handle to the tracker target.
capacity out The pose buffer's current capacity.

Gets the capacity of the target's pose buffer.