Open topic with navigation

# 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

enum ZSDisplayAttribute

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.

enum ZSDisplayType

Defines the types of displays for the Display APIs.

Enumerator:

  ZS_DISPLAY_TYPE_UNKNOWN |
  ZS_DISPLAY_TYPE_GENERIC |
  ZS_DISPLAY_TYPE_ZSPACE |

Open topic with navigation