IDisplayInfo#

Fully qualified name: omni::platforminfo::IDisplayInfo

Defined in omni/platforminfo/IDisplayInfo.h

class IDisplayInfo : public omni::core::Generated<omni::platforminfo::IDisplayInfo_abi>#

Interface to collect and retrieve information about displays attached to the system.

Each display is a viewport onto the desktop’s virtual screen space and has an origin and size. Most displays are capable of switching between several modes. A mode is a combination of a viewport resolution (width, height, and color depth), and refresh rate. Display info may be collected using this interface, but it does not handle making changes to the current mode for any given display.

Public Functions

inline size_t getDisplayCount() noexcept#

Retrieves the total number of displays connected to the system.

Thread Safety: This call is thread safe.

Returns:: The total number of displays connected to the system. This typically includes displays that are currently turned off. Note that the return value here is volatile and may change at any point due to user action (either in the OS or by unplugging or connecting a display). This value should not be cached for extended periods of time.

inline bool getDisplayInfo( size_t displayIndex, omni::platforminfo::DisplayInfo *infoOut, ) noexcept#

Retrieves information about a single connected display.

Thread Safety: This call is thread safe.

Parameters:

displayIndex – [in] The zero based index of the display to retrieve the information for. This call will fail if the index is out of the range of the number of connected displays, thus it is not necessary to IDisplayInfo::getDisplayCount() to enumerate display information in a counted loop.
infoOut – [out] Receives the information for the requested display. This may not be nullptr. This returned information may change at any time due to user action and should therefore not be cached.

Returns:

true if the information for the requested display is successfully retrieved. Returns false if the displayIndex index was out of the range of connected display devices or the information could not be retrieved for any reason.

inline size_t getModeCount( const omni::platforminfo::DisplayInfo *display, ) noexcept#

Retrieves the total number of display modes for a given display.

Thread Safety: This call is thread safe.

Parameters:: display – [in] The display to retrieve the mode count for. This may not be nullptr. This must have been retrieved from a recent call to IDisplayInfo::getDisplayInfo().
Returns:: The total number of display modes supported by the requested display. Returns 0 if the mode count information could not be retrieved. A connected valid display will always support at least one mode.

inline bool getModeInfo( const omni::platforminfo::DisplayInfo *display, omni::platforminfo::ModeIndex modeIndex, omni::platforminfo::ModeInfo *infoOut, ) noexcept#

Retrieves the information for a single display mode for a given display.

Thread Safety: This call is thread safe.

Parameters:

display – [in] The display to retrieve the mode count for. This may not be nullptr. This must have been retrieved from a recent call to IDisplayInfo::getDisplayInfo().
modeIndex – [in] The zero based index of the mode to retrieve for the given display. This may also be omni::platforminfo::kModeIndexCurrent to retrieve the information for the given display’s current mode. This call will simply fail if this index is out of range of the number of modes supported by the given display, thus it is not necessary to call omni::platforminfo::IDisplayInfo::getModeCount() to use in a counted loop.
infoOut – [out] Receives the information for the requested mode of the given display. This may not be nullptr.

Returns:

true if the information for the requested mode is successfully retrieved. Returns false if the given index was out of range of the number of modes supported by the given display or the mode’s information could not be retrieved for any reason.

inline bool getTotalDisplaySize( carb::Int2 *origin, carb::Int2 *size, ) noexcept#

Retrieves the total virtual screen size that all connected displays cover.

Remark

This retrieves the total virtual screen size for the system. This is the union of the rectangles that all connected displays cover. Note that this will also include any empty space between or around displays that is not covered by another display.

Thread Safety: This call is thread safe.

Parameters:

origin – [out] Receives the coordinates of the origin of the rectangle that the virtual screen covers. This may be nullptr if the origin point is not needed.
size – [out] Receives the width and height of the rectangle that the virtual screen covers. This may be nullptr if the size is not needed.

Returns:

true if either the origin, size, or both origin and size of the virtual screen are retrieved successfully. Returns false if the size of the virtual screen could not be retrieved or both origin and size are nullptr.

inline void *cast(omni::core::TypeId id) noexcept#

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.

inline void acquire() noexcept#

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

inline void release() noexcept#

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

Protected Functions

virtual size_t getDisplayCount_abi() noexcept = 0#

Retrieves the total number of displays connected to the system.

Thread Safety: This call is thread safe.

Returns:: The total number of displays connected to the system. This typically includes displays that are currently turned off. Note that the return value here is volatile and may change at any point due to user action (either in the OS or by unplugging or connecting a display). This value should not be cached for extended periods of time.

virtual bool getDisplayInfo_abi( size_t displayIndex, DisplayInfo *infoOut, ) noexcept = 0#

Retrieves information about a single connected display.

Thread Safety: This call is thread safe.

Parameters:

displayIndex – [in] The zero based index of the display to retrieve the information for. This call will fail if the index is out of the range of the number of connected displays, thus it is not necessary to IDisplayInfo::getDisplayCount() to enumerate display information in a counted loop.
infoOut – [out] Receives the information for the requested display. This may not be nullptr. This returned information may change at any time due to user action and should therefore not be cached.

Returns:

true if the information for the requested display is successfully retrieved. Returns false if the displayIndex index was out of the range of connected display devices or the information could not be retrieved for any reason.

virtual size_t getModeCount_abi( const DisplayInfo *display, ) noexcept = 0#

Retrieves the total number of display modes for a given display.

Thread Safety: This call is thread safe.

Parameters:: display – [in] The display to retrieve the mode count for. This may not be nullptr. This must have been retrieved from a recent call to IDisplayInfo::getDisplayInfo().
Returns:: The total number of display modes supported by the requested display. Returns 0 if the mode count information could not be retrieved. A connected valid display will always support at least one mode.

virtual bool getModeInfo_abi( const DisplayInfo *display, ModeIndex modeIndex, ModeInfo *infoOut, ) noexcept = 0#

Retrieves the information for a single display mode for a given display.

Thread Safety: This call is thread safe.

Parameters:

display – [in] The display to retrieve the mode count for. This may not be nullptr. This must have been retrieved from a recent call to IDisplayInfo::getDisplayInfo().
modeIndex – [in] The zero based index of the mode to retrieve for the given display. This may also be omni::platforminfo::kModeIndexCurrent to retrieve the information for the given display’s current mode. This call will simply fail if this index is out of range of the number of modes supported by the given display, thus it is not necessary to call omni::platforminfo::IDisplayInfo::getModeCount() to use in a counted loop.
infoOut – [out] Receives the information for the requested mode of the given display. This may not be nullptr.

Returns:

true if the information for the requested mode is successfully retrieved. Returns false if the given index was out of range of the number of modes supported by the given display or the mode’s information could not be retrieved for any reason.

virtual bool getTotalDisplaySize_abi( carb::Int2 *origin, carb::Int2 *size, ) noexcept = 0#

Retrieves the total virtual screen size that all connected displays cover.

Remark

This retrieves the total virtual screen size for the system. This is the union of the rectangles that all connected displays cover. Note that this will also include any empty space between or around displays that is not covered by another display.

Thread Safety: This call is thread safe.

Parameters:

origin – [out] Receives the coordinates of the origin of the rectangle that the virtual screen covers. This may be nullptr if the origin point is not needed.
size – [out] Receives the width and height of the rectangle that the virtual screen covers. This may be nullptr if the size is not needed.

Returns:

true if either the origin, size, or both origin and size of the virtual screen are retrieved successfully. Returns false if the size of the virtual screen could not be retrieved or both origin and size are nullptr.

virtual void *cast_abi(TypeId id) noexcept = 0#

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.

virtual void acquire_abi() noexcept = 0#

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

virtual void release_abi() noexcept = 0#

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.