Display API

Detailed Description

The display manager tracks all connected displays. You can use displays of different types, as well as multiple displays of the same type. For example, you could have two zSpace displays.

Note:
For brevity, most of the code examples in this section omit getting the handle for the display. For a complete example, refer to zsFindDisplayByType().

List of Functions

ZSError  zsRefreshDisplays (ZSContext context)
ZSError  zsGetNumDisplays (ZSContext context, ZSInt32* numDisplays)
ZSError  zsGetNumDisplaysByType (ZSContext context, ZSDisplayType displayType, ZSInt32* numDisplays)
ZSError  zsFindDisplay (ZSContext context, ZSInt32 x, ZSInt32 y, ZSHandle* displayHandle)
ZSError  zsFindDisplayByIndex (ZSContext context, ZSInt32 index, ZSHandle* displayHandle)
ZSError  zsFindDisplayByType (ZSContext context, ZSDisplayType displayType, ZSInt32 index, ZSHandle* displayHandle)
ZSError  zsGetDisplayType (ZSHandle displayHandle, ZSDisplayType* displayType)
ZSError  zsGetDisplayNumber (ZSHandle displayHandle, ZSInt32* number)
ZSError  zsGetDisplayAdapterIndex (ZSHandle displayHandle, ZSInt32* adapterIndex)
ZSError  zsGetDisplayMonitorIndex (ZSHandle displayHandle, ZSInt32* monitorIndex)
ZSError  zsGetDisplayAttribute (ZSHandle displayHandle, ZSDisplayAttribute attribute, char* buffer, ZSInt32 bufferSize)
ZSError  zsGetDisplaySize (ZSHandle displayHandle, ZSFloat* width, ZSFloat* height)
ZSError  zsGetDisplayPosition (ZSHandle displayHandle, ZSInt32* x, ZSInt32* y)
ZSError  zsGetDisplayNativeResolution (ZSHandle displayHandle, ZSInt32* x, ZSInt32* y)
ZSError  zsGetDisplayAngle (ZSHandle displayHandle, ZSFloat* x, ZSFloat* y, ZSFloat* z)
ZSError  zsGetDisplayVerticalRefreshRate (ZSHandle displayHandle, ZSFloat* refreshRate)
ZSError  zsIsDisplayHardwarePresent (ZSHandle displayHandle, ZSBool* isHardwarePresent)
ZSError  zsIntersectDisplay (ZSHandle displayHandle, const ZSTrackerPose* pose, ZSDisplayIntersectionInfo* intersectionInfo)

List of Data Structures

struct   ZSDisplayIntersectionInfo
  Struct representing display intersection information. More...

List of Enumerations

enum   ZSDisplayType {
  ZS_DISPLAY_TYPE_UNKNOWN = -1,
  ZS_DISPLAY_TYPE_GENERIC = 0,
  ZS_DISPLAY_TYPE_ZSPACE = 1
}
enum   ZSDisplayAttribute {
  ZS_DISPLAY_ATTRIBUTE_ADAPTER_NAME = 0,
  ZS_DISPLAY_ATTRIBUTE_ADAPTER_STRING = 1,
  ZS_DISPLAY_ATTRIBUTE_ADAPTER_ID = 2,
  ZS_DISPLAY_ATTRIBUTE_ADAPTER_VENDOR_ID = 3,
  ZS_DISPLAY_ATTRIBUTE_ADAPTER_DEVICE_ID = 4,
  ZS_DISPLAY_ATTRIBUTE_ADAPTER_KEY = 5,
  ZS_DISPLAY_ATTRIBUTE_MONITOR_NAME = 6,
  ZS_DISPLAY_ATTRIBUTE_MONITOR_STRING = 7,
  ZS_DISPLAY_ATTRIBUTE_MONITOR_ID = 8,
  ZS_DISPLAY_ATTRIBUTE_MONITOR_VENDOR_ID = 9,
  ZS_DISPLAY_ATTRIBUTE_MONITOR_DEVICE_ID = 10,
  ZS_DISPLAY_ATTRIBUTE_MONITOR_KEY = 11,
  ZS_DISPLAY_ATTRIBUTE_MANUFACTURER_NAME = 12,
  ZS_DISPLAY_ATTRIBUTE_PRODUCT_CODE = 13,
  ZS_DISPLAY_ATTRIBUTE_SERIAL_NUMBER = 14,
  ZS_DISPLAY_ATTRIBUTE_VIDEO_INTERFACE = 15
}

Function Descriptions

ZSError zsFindDisplay ( ZSContext  context,
ZSInt32  x,
ZSInt32  y,
ZSHandle*   displayHandle 
)

Gets the display handle based on the specified (x, y) pixel coordinates on the virtual desktop.

Parameters:
[in] context A handle to the internal state of the zSpace SDK.
[in] x The x pixel coordinate on the virtual desktop.
[in] y The y pixel coordinate on the virtual desktop.
[out] displayHandle The handle for the display at the specified pixel location.
ZSError zsFindDisplayByIndex ( ZSContext  context,
ZSInt32  index,
ZSHandle*   displayHandle 
)

Gets the display handle at a specified index.

Parameters:
[in] context A handle to the internal state of the zSpace SDK.
[in] index The index of the display to query.
[out] displayHandle The handle for the display at the specified index.
Example:
 ZSContext context = ...;

 ZSInt32 numDisplays = 0;
 zsGetNumDisplays(context, &numDisplays);
 
 // Iterate over all connected displays. 
 for (int i = 0; i < numDisplays; ++i)
 {
   ZSHandle displayHandle;
   zsFindDisplayByIndex(context, i, &displayHandle);
 }
ZSError zsFindDisplayByType ( ZSContext  context,
ZSDisplayType  displayType,
ZSInt32  index,
ZSHandle*   displayHandle 
)

Gets the display handle for a specified type. Note that in this case, the index is per type. Thus if you have only one device of a given type, the index is 0.

Parameters:
[in] context A handle to the internal state of the zSpace SDK.
[in] displayType The display type to query.
[in] index The index for the specified device of this type.
[out] displayHandle The handle for the display of the specified type.
Example:
 ZSContext context = ...;

 ZSHandle displayHandle = 0;
 zsFindDisplayByType(context, ZS_DISPLAY_TYPE_ZSPACE, 0, &displayHandle);
ZSError zsGetDisplayAdapterIndex ( ZSHandle  displayHandle,
ZSInt32*   adapterIndex 
)

Gets the index of the GPU that is connected to the specified display. For example, if your system contains the following GPU configuration, the adapter indexes would be:

  • NVidia Quadro 3700 GPU (adapter index: 0)
  • NVidia Quadro 4000 GPU (adapter index: 1)
Parameters:
[in] displayHandle A handle to the display.
[out] adapterIndex The index of the display's GPU.
ZSError zsGetDisplayAngle ( ZSHandle  displayHandle,
ZSFloat*   x,
ZSFloat*   y,
ZSFloat*   z 
)

Gets the display's angles about each axis in degrees.

Parameters:
[in] displayHandle A handle to the display.
[out] x The angle of the display about the x axis.
[out] y The angle of the display about the y axis.
[out] z The angle of the display about the z axis.
ZSError zsGetDisplayAttribute ( ZSHandle  displayHandle,
ZSDisplayAttribute  attribute,
char*   buffer,
ZSInt32  bufferSize 
)

Gets the string value of the specified attribute for the display. See ZSDisplayAttribute for a list of the available attributes.

Parameters:
[in] displayHandle A handle to the display.
[in] attribute The attribute to query.
[out] buffer The user allocated character buffer to hold the attribute's string value.
[in] bufferSize The size of the user allocated buffer.
ZSError zsGetDisplayMonitorIndex ( ZSHandle  displayHandle,
ZSInt32*   monitorIndex 
)

Gets the index of the monitor attached to the display's GPU. For example, if your system contains the following GPU and display configuration, the adapter and monitor indexes would be:

NVidia Quadro 3700 GPU (adapter index: 0)

  • Generic Monitor 1 (monitor index: 0)
  • Generic Monitor 2 (monitor index: 1)

NVidia Quadro 4000 GPU (adapter index: 1)

  • zStation (monitor index: 0)

Parameters:
[in] displayHandle A handle to the display.
[out] monitorIndex The index for the attached monitor.
ZSError zsGetDisplayNativeResolution ( ZSHandle  displayHandle,
ZSInt32*   x,
ZSInt32*   y 
)

Gets the display's preferred native resolution in pixels.

Parameters:
[in] displayHandle A handle to the display.
[out] x The width in pixels.
[out] y The height in pixels.
ZSError zsGetDisplayNumber ( ZSHandle  displayHandle,
ZSInt32*   number 
)

Gets the display's number. The display number refers to the number shown for the display when you set screen resolution in the Windows Control Panel.

Parameters:
[in] displayHandle A handle to the display.
[out] number The display's number.
ZSError zsGetDisplayPosition ( ZSHandle  displayHandle,
ZSInt32*   x,
ZSInt32*   y 
)

Gets the (x, y) pixel location of the specified display on the virtual desktop (top-left corner).

Parameters:
[in] displayHandle A handle to the display.
[out] x The x pixel location.
[out] y The y pixel location.
Example:
 ZSHandle displayHandle;
 ZSInt32 x = 0;
 ZSInt32 y = 0;
 zsGetDisplayPosition(displayHandle, &x, &y);
ZSError zsGetDisplaySize ( ZSHandle  displayHandle,
ZSFloat*   width,
ZSFloat*   height 
)

Gets the display's size in meters.

Parameters:
[in] displayHandle A handle to the display.
[out] width The display's width in meters.
[out] height The display's height in meters.
ZSError zsGetDisplayType ( ZSHandle  displayHandle,
ZSDisplayType*   displayType 
)

Gets the display's type.

Parameters:
[in] displayHandle A handle to the display.
[out] displayType The display's type.
ZSError zsGetDisplayVerticalRefreshRate ( ZSHandle  displayHandle,
ZSFloat*   refreshRate 
)

Gets the display's vertical refresh rate.

Parameters:
[in] displayHandle A handle to the display.
[out] refreshRate The vertical refresh rate.
ZSError zsGetNumDisplays ( ZSContext  context,
ZSInt32*   numDisplays 
)

Gets the number of connected displays.

Parameters:
[in] context A handle to the internal state of the zSpace SDK.
[out] numDisplays The number of connected displays.
ZSError zsGetNumDisplaysByType ( ZSContext  context,
ZSDisplayType  displayType,
ZSInt32*   numDisplays 
)

Gets the number of connected displays based on a specified type.

Parameters:
[in] context A handle to the internal state of the zSpace SDK.
[in] displayType The type of display to query.
[out] numDisplays The number of displays of the specified type.
Example:
 ZSContext context = ...;

 // Get the number of zSpace displays.
 ZSInt32 numDisplays = 0;
 zsGetNumDisplaysByType(context, ZS_DISPLAY_TYPE_ZSPACE, &numDisplays);
ZSError zsIntersectDisplay ( ZSHandle  displayHandle,
const ZSTrackerPose*   pose,
ZSDisplayIntersectionInfo*   intersectionInfo 
)

Performs a raycast against the display. The incoming pose is assumed to transform the direction of the negative Z vector, which is then used for the intersection test.

Parameters:
[in] displayHandle A handle to the display.
[in] pose A ZSTrackerPose in tracker space.
[out] intersectionInfo Struct containing information about the intersection (i.e. hit, screen position, etc.)
ZSError zsIsDisplayHardwarePresent ( ZSHandle  displayHandle,
ZSBool*   isHardwarePresent 
)

Checks if the specified display is connected via the USB port. Currently this only applies to zSpace displays.

Parameters:
[in] displayHandle A handle to the display.
[out] isHardwarePresent True if connected, false otherwise.
ZSError zsRefreshDisplays ( ZSContext  context )

Refreshes all of the underlying display information.

Warning:
This invalidates any cached display data that has been returned in prior queries. You must query for these display handles again.
Parameters:
[in] context A handle to the internal state of the zSpace SDK.

Enumeration Descriptions

Defines the attributes that you can query for the display. See zsGetDisplayAttribute().

Enumerator:
ZS_DISPLAY_ATTRIBUTE_ADAPTER_NAME 

The graphics adapter name.

ZS_DISPLAY_ATTRIBUTE_ADAPTER_STRING 

The graphics adapter context string.

ZS_DISPLAY_ATTRIBUTE_ADAPTER_ID 

The entire ID string of the graphics adapter.

ZS_DISPLAY_ATTRIBUTE_ADAPTER_VENDOR_ID 

The vendor ID of the graphics adapter.

ZS_DISPLAY_ATTRIBUTE_ADAPTER_DEVICE_ID 

The device ID of the graphics adapter.

ZS_DISPLAY_ATTRIBUTE_ADAPTER_KEY 

Reserved.

ZS_DISPLAY_ATTRIBUTE_MONITOR_NAME 

The monitor name.

ZS_DISPLAY_ATTRIBUTE_MONITOR_STRING 

The monitor context string.

ZS_DISPLAY_ATTRIBUTE_MONITOR_ID 

The entire ID string of the monitor.

ZS_DISPLAY_ATTRIBUTE_MONITOR_VENDOR_ID 

The vendor ID of the monitor.

ZS_DISPLAY_ATTRIBUTE_MONITOR_DEVICE_ID 

The device ID of the monitor.

ZS_DISPLAY_ATTRIBUTE_MONITOR_KEY 

Reserved.

ZS_DISPLAY_ATTRIBUTE_MANUFACTURER_NAME 

The display's manufacturer name.

ZS_DISPLAY_ATTRIBUTE_PRODUCT_CODE 

The display's product code.

ZS_DISPLAY_ATTRIBUTE_SERIAL_NUMBER 

The display's serial number.

ZS_DISPLAY_ATTRIBUTE_VIDEO_INTERFACE 

The display's video interface.

Defines the types of displays for the Display APIs.

Enumerator:
ZS_DISPLAY_TYPE_UNKNOWN 
ZS_DISPLAY_TYPE_GENERIC 
ZS_DISPLAY_TYPE_ZSPACE