Leap::Screen Class Reference

#include <Leap.h>

Inheritance diagram for Leap::Screen:

Detailed Description

The Screen class represents a computer monitor screen.

The Screen class reports characteristics describing the position and orientation of the monitor screen within the Leap coordinate system. These characteristics include the bottom-left corner position of the screen, direction vectors for the horizontal and vertical axes of the screen, and the screen's normal vector. The screen must be properly registered with the Screen Locator for the Leap to report these characteristics accurately. The Screen class also reports the size of the screen in pixels, using information obtained from the operating system. (Run the Screen Locator from the Leap Application Settings dialog, on the Screen page.)

You can get the point of intersection between the screen and a ray projected from a Pointable object using the Screen::intersect() function. Likewise, you can get the closest point on the screen to a point in space using the Screen::project() function. Again, the screen location must be registered with the Screen Locator for these functions to return accurate values.

Note that Screen objects can be invalid, which means that they do not contain valid screen coordinate data and do not correspond to a physical entity. Test for validity with the Screen::isValid() function.

Public Member Functions
	Screen (ScreenImplementation *)
LEAP_EXPORT	Screen ()
LEAP_EXPORT int32_t	id () const
LEAP_EXPORT Vector	intersect (const Pointable &pointable, bool normalize, float clampRatio=1.0f) const
LEAP_EXPORT Vector	intersect (const Vector &position, const Vector &direction, bool normalize, float clampRatio=1.0f) const
LEAP_EXPORT Vector	project (const Vector &position, bool normalize, float clampRatio=1.0f) const
LEAP_EXPORT Vector	horizontalAxis () const
LEAP_EXPORT Vector	verticalAxis () const
LEAP_EXPORT Vector	bottomLeftCorner () const
LEAP_EXPORT Vector	normal () const
LEAP_EXPORT int	widthPixels () const
LEAP_EXPORT int	heightPixels () const
LEAP_EXPORT float	distanceToPoint (const Vector &point) const
LEAP_EXPORT bool	isValid () const
LEAP_EXPORT bool	operator== (const Screen &) const
LEAP_EXPORT bool	operator!= (const Screen &) const
LEAP_EXPORT std::string	toString () const

Static Public Member Functions
static LEAP_EXPORT const Screen &	invalid ()

Friends
LEAP_EXPORT friend std::ostream &	operator<< (std::ostream &, const Screen &)

Additional Inherited Members
Protected Attributes inherited from Leap::Interface
class SharedObject *	m_object
Protected Member Functions inherited from Leap::Interface
LEAP_EXPORT	Interface (void *owner)
LEAP_EXPORT	Interface (Implementation *reference, void *owner)
LEAP_EXPORT	Interface (const Interface &rhs)
LEAP_EXPORT Interface &	operator= (const Interface &rhs)
virtual LEAP_EXPORT	~Interface ()
template<typename T >
T *	get () const

Constructor details

Screen() [1/2]

Leap::Screen::Screen

(

ScreenImplementation *

)

Screen() [2/2]

LEAP_EXPORT Leap::Screen::Screen

(

)

Constructs a Screen object.

An uninitialized screen is considered invalid. Get valid Screen objects from a ScreenList object obtained using the Controller::locatedScreens() method.

Function details

bottomLeftCorner()

LEAP_EXPORT Vector Leap::Screen::bottomLeftCorner

(

)

const

A Vector representing the bottom left corner of this Screen within the Leap coordinate system.

The point represented by this vector defines the origin of the screen in the Leap coordinate system.

Together, horizontalAxis(), verticalAxis(), and bottomLeftCorner() describe the physical position, size and orientation of this Screen.

Returns

A Vector containing the coordinates of the bottom-left corner of this Screen.

distanceToPoint()

LEAP_EXPORT float Leap::Screen::distanceToPoint

(

const Vector &

point

)

const

The shortest distance from the specified point to the plane in which this Screen lies.

Returns

The length of the perpendicular line segment extending from the plane this Screen lies in to the specified point.

heightPixels()

LEAP_EXPORT int Leap::Screen::heightPixels

(

)

const

The vertical resolution of this screen, in pixels.

Returns

The height of this Screen in pixels.

horizontalAxis()

LEAP_EXPORT Vector Leap::Screen::horizontalAxis

(

)

const

A Vector representing the horizontal axis of this Screen within the Leap coordinate system.

The magnitude of this vector estimates the physical width of this Screen in millimeters. The direction of this vector is parallel to the bottom edge of the screen and points toward the right edge of the screen.

Together, horizontalAxis(), verticalAxis(), and bottomLeftCorner() describe the physical position, size and orientation of this Screen.

Returns

A Vector representing the bottom, horizontal edge of this Screen.

id()

LEAP_EXPORT int32_t Leap::Screen::id

(

)

const

A unique identifier for this screen based on the screen information in the configuration. A default screen with ID, 0, always exists and contains default characteristics, even if no screens have been located.

intersect() [1/2]

LEAP_EXPORT Vector Leap::Screen::intersect	(	const Pointable &	pointable,
		bool	normalize,
		float	clampRatio = 1.0f
	)		const

Returns the intersection between this screen and a ray projecting from a Pointable object.

The projected ray emanates from the Pointable tipPosition along the Pointable's direction vector.

Set the normalize parameter to true to request the intersection point in normalized screen coordinates. Normalized screen coordinates are usually values between 0 and 1, where 0 represents the screen's origin at the bottom-left corner and 1 represents the opposite edge (either top or right). When you request normalized coordinates, the z-component of the returned vector is zero. Multiply a normalized coordinate by the values returned by Screen::widthPixels() or Screen::heightPixels() to calculate the screen position in pixels (remembering that many other computer graphics coordinate systems place the origin in the top-left corner).

Set the normalize parameter to false to request the intersection point in Leap coordinates (millimeters from the Leap origin).

If the Pointable object points outside the screen's border (but still intersects the plane in which the screen lies), the returned intersection point is clamped to the nearest point on the edge of the screen.

You can use the clampRatio parameter to contract or expand the area in which you can point. For example, if you set the clampRatio parameter to 0.5, then the positions reported for intersection points outside the central 50% of the screen are moved to the border of this smaller area. If, on the other hand, you expanded the area by setting clampRatio to a value such as 3.0, then you could point well outside screen's physical boundary before the intersection points would be clamped. The positions for any points clamped would also be placed on this larger outer border. The positions reported for any intersection points inside the clamping border are unaffected by clamping.

If the Pointable object does not point toward the plane of the screen (i.e. it is pointing parallel to or away from the screen), then the components of the returned vector are all set to NaN (not-a-number).

Parameters

pointable	The Pointable object to check for screen intersection.
normalize	If true, return normalized coordinates representing the intersection point as a percentage of the screen's width and height. If false, return Leap coordinates (millimeters from the Leap origin, which is located at the center of the top surface of the Leap device). If true and the clampRatio parameter is set to 1.0, coordinates will be of the form (0..1, 0..1, 0). Setting the clampRatio to a different value changes the range for normalized coordinates. For example, a clampRatio of 5.0 changes the range of values to be of the form (-2..3, -2..3, 0).
clampRatio	Adjusts the clamping border around this screen. By default this ratio is 1.0, and the border corresponds to the actual boundaries of the screen. Setting clampRatio to 0.5 would reduce the interaction area. Likewise, setting the ratio to 2.0 would increase the interaction area, adding 50% around each edge of the physical monitor. Intersection points outside the interaction area are repositioned to the closest point on the clamping border before the vector is returned.

Returns

A Vector containing the coordinates of the intersection between this screen and a ray projecting from the specified Pointable object.

intersect() [2/2]

LEAP_EXPORT Vector Leap::Screen::intersect	(	const Vector &	position,
		const Vector &	direction,
		bool	normalize,
		float	clampRatio = 1.0f
	)		const

Returns the intersection between this screen and a ray projecting from the specified position along the specified direction.

Set the normalize parameter to true to request the intersection point in normalized screen coordinates. Normalized screen coordinates are usually values between 0 and 1, where 0 represents the screen's origin at the bottom-left corner and 1 represents the opposite edge (either top or right). When you request normalized coordinates, the z-component of the returned vector is zero. Multiply a normalized coordinate by the values returned by Screen::widthPixels() or Screen::heightPixels() to calculate the screen position in pixels (remembering that many other computer graphics coordinate systems place the origin in the top-left corner).

Set the normalize parameter to false to request the intersection point in Leap coordinates (millimeters from the Leap origin).

If the specified ray points outside the screen's border (but still intersects the plane in which the screen lies), the returned intersection point is clamped to the nearest point on the edge of the screen.

You can use the clampRatio parameter to contract or expand the area in which you can point. For example, if you set the clampRatio parameter to 0.5, then the positions reported for intersection points outside the central 50% of the screen are moved to the border of this smaller area. If, on the other hand, you expanded the area by setting clampRatio to a value such as 3.0, then you could point well outside screen's physical boundary before the intersection points would be clamped. The positions for any points clamped would also be placed on this larger outer border. The positions reported for any intersection points inside the clamping border are unaffected by clamping.

If the specified ray does not point toward the plane of the screen (i.e. it is pointing parallel to or away from the screen), then the components of the returned vector are all set to NaN (not-a-number).

Parameters

position	The position from which to check for screen intersection.
direction	The direction in which to check for screen intersection.
normalize	If true, return normalized coordinates representing the intersection point as a percentage of the screen's width and height. If false, return Leap coordinates (millimeters from the Leap origin, which is located at the center of the top surface of the Leap device). If true and the clampRatio parameter is set to 1.0, coordinates will be of the form (0..1, 0..1, 0). Setting the clampRatio to a different value changes the range for normalized coordinates. For example, a clampRatio of 5.0 changes the range of values to be of the form (-2..3, -2..3, 0).
clampRatio	Adjusts the clamping border around this screen. By default this ratio is 1.0, and the border corresponds to the actual boundaries of the screen. Setting clampRatio to 0.5 would reduce the interaction area. Likewise, setting the ratio to 2.0 would increase the interaction area, adding 50% around each edge of the physical monitor. Intersection points outside the interaction area are repositioned to the closest point on the clamping border before the vector is returned.

Returns

A Vector containing the coordinates of the intersection between this screen and a ray projecting from the specified position in the specified direction.

invalid()

static LEAP_EXPORT const Screen& Leap::Screen::invalid ( )

static

Returns an invalid Screen object.

You can use the instance returned by this function in comparisons testing whether a given Screen instance is valid or invalid. (You can also use the Screen::isValid() function.)

Returns

The invalid Screen instance.

isValid()

LEAP_EXPORT bool Leap::Screen::isValid

(

)

const

Reports whether this is a valid Screen object.

Important: A valid Screen object does not necessarily contain up-to-date screen location information. Location information is only accurate until the Leap device or the monitor are moved. In addition, the primary screen always contains default location information even if the user has never run the screen location utility. This default location information will not return accurate results.

Returns

True, if this Screen object contains valid data.

normal()

LEAP_EXPORT Vector Leap::Screen::normal

(

)

const

A Vector normal to the plane in which this Screen lies.

The normal vector is a unit direction vector orthogonal to the screen's surface plane. It points toward a viewer positioned for typical use of the monitor.

Returns

A Vector representing this Screen's normal vector.

operator!=()

LEAP_EXPORT bool Leap::Screen::operator!=

(

const Screen &

)

const

Compare Screen object inequality. Two Screen objects are equal if and only if both Screen objects represent the exact same Screens and both Screens are valid.

operator==()

LEAP_EXPORT bool Leap::Screen::operator==

(

const Screen &

)

const

Compare Screen object equality. Two Screen objects are equal if and only if both Screen objects represent the exact same Screens and both Screens are valid.

project()

LEAP_EXPORT Vector Leap::Screen::project	(	const Vector &	position,
		bool	normalize,
		float	clampRatio = 1.0f
	)		const

Returns the projection from the specified position onto this screen.

Set the normalize parameter to true to request the projection point in normalized screen coordinates. Normalized screen coordinates are usually values between 0 and 1, where 0 represents the screen's origin at the bottom-left corner and 1 represents the opposite edge (either top or right). When you request normalized coordinates, the z-component of the returned vector is zero. Multiply a normalized coordinate by the values returned by Screen::widthPixels() or Screen::heightPixels() to calculate the screen position in pixels (remembering that many other computer graphics coordinate systems place the origin in the top-left corner).

Set the normalize parameter to false to request the projection point in Leap coordinates (millimeters from the Leap origin).

If the specified point projects outside the screen's border, the returned projection point is clamped to the nearest point on the edge of the screen.

You can use the clampRatio parameter to contract or expand the area in which you can point. For example, if you set the clampRatio parameter to 0.5, then the positions reported for projection points outside the central 50% of the screen are moved to the border of this smaller area. If, on the other hand, you expanded the area by setting clampRatio to a value such as 3.0, then you could point well outside screen's physical boundary before the projection points would be clamped. The positions for any points clamped would also be placed on this larger outer border. The positions reported for any projection points inside the clamping border are unaffected by clamping.

Parameters

position	The position from which to project onto this screen.
normalize	If true, return normalized coordinates representing the projection point as a percentage of the screen's width and height. If false, return Leap coordinates (millimeters from the Leap origin, which is located at the center of the top surface of the Leap device). If true and the clampRatio parameter is set to 1.0, coordinates will be of the form (0..1, 0..1, 0). Setting the clampRatio to a different value changes the range for normalized coordinates. For example, a clampRatio of 5.0 changes the range of values to be of the form (-2..3, -2..3, 0).
clampRatio	Adjusts the clamping border around this screen. By default this ratio is 1.0, and the border corresponds to the actual boundaries of the screen. Setting clampRatio to 0.5 would reduce the interaction area. Likewise, setting the ratio to 2.0 would increase the interaction area, adding 50% around each edge of the physical monitor. Projection points outside the interaction area are repositioned to the closest point on the clamping border before the vector is returned.

Returns

A Vector containing the coordinates of the projection between this screen and a ray projecting from the specified position onto the screen along its normal vector.

toString()

LEAP_EXPORT std::string Leap::Screen::toString

(

)

const

A string containing a brief, human readable description of the Screen object.

Returns

A description of the Screen as a string.

verticalAxis()

LEAP_EXPORT Vector Leap::Screen::verticalAxis

(

)

const

A Vector representing the vertical axis of this Screen within the Leap coordinate system.

The magnitude of this vector estimates the physical height of this Screen in millimeters. The direction of this vector is parallel to the left edge of the screen and points toward the top edge of the screen.

Together, horizontalAxis(), verticalAxis(), and bottomLeftCorner() describe the physical position, size and orientation of this screen.

Returns

A Vector representing the left, vertical edge of this Screen.

widthPixels()

LEAP_EXPORT int Leap::Screen::widthPixels

(

)

const

The horizontal resolution of this screen, in pixels.

Returns

The width of this Screen in pixels.

Related details

operator<<

LEAP_EXPORT friend std::ostream& operator<< ( std::ostream &  , const Screen &    )

friend

Writes a brief, human readable description of the Screen object.