#include <CUDisplay.h>

Public Types
enum	Aspect : unsigned int { Aspect::SQUARE = 0, Aspect::PORTRAIT_3_4 = 1, Aspect::PORTRAIT_2_3 = 2, Aspect::PORTRAIT_10_16 = 3, Aspect::PORTRAIT_3_5 = 4, Aspect::PORTRAIT_9_16 = 5, Aspect::PORTRAIT_600_1024 = 6, Aspect::PORTRAIT_IPAD_PRO = 7, Aspect::LANDSCAPE_4_3 = 8, Aspect::LANDSCAPE_3_2 = 9, Aspect::LANDSCAPE_16_10 = 10, Aspect::LANDSCAPE_5_3 = 11, Aspect::LANDSCAPE_16_9 = 12, Aspect::LANDSCAPE_1024_600 = 13, Aspect::LANDSCAPE_IPAD_PRO = 14, Aspect::UKNOWN = 15 }

Public Member Functions
const Rect &	getBounds () const

Rect	getPixelBounds () const

const Rect &	getUsableBounds () const

const Vec2 &	getPixelDensity () const

Aspect	getAspect () const

bool	isLandscape () const

bool	isPortrait () const

float	getAspectRatio () const

const std::string	getAspectName () const

int	widthForHeight (int height) const

int	heightForWidth (int width) const

Static Public Member Functions
static bool	start ()

static void	stop ()

static Display *	get ()

static Aspect	getAspect (float ratio)

static float	getAspectRatio (Aspect aspect)

static const std::string	getAspectName (Aspect aspect)

static int	widthForHeight (int height, Aspect aspect)

static int	heightForWidth (int width, Aspect aspect)

Protected Member Functions
	Display ()

bool	init ()

void	dispose ()

	~Display ()

Protected Attributes
Aspect	_aspect

Rect	_bounds

Rect	_usable

Vec2	_scale

Static Protected Attributes
static Display *	_thedisplay

Detailed Description

This class is a singleton representing the native display.

The static methods of this class start() and stop() the SDL video system. Without it, you cannot draw anything. This should be the first and last methods called in any application. The Application class does this for you automatically.

The singleton display object also has several methods to get the (current) screen resolution and aspect ratio. The most important of these two is the the aspect ratio. Aspect ratio is one of the most unportable parts of cross-platform development. Everything else can be scaled to the screen, but the aspect ratio is fixed from the very beginning.

If the device has multiple displays, this singleton will only refer to the main display.

Member Enumeration Documentation

enum cugl::Display::Aspect : unsigned int

strong

The display aspect ratio.

This enum includes support for almost every shipping aspect rations. For information on your device, see

 http://mydevice.io/devices/

Enumerator
SQUARE	Aspect ratio of 1:1 This is the aspect ratio of many early Blackberry devices.
PORTRAIT_3_4	Portrait aspect ratio of 3:4 This is the portrait aspect ratio of most Apple iPad's except for the iPad Pro.
PORTRAIT_2_3	Portrait aspect ratio of 2:3 This is the portrait aspect ratio of older iPhones (before the 4s) and Microsoft Surface 3.
PORTRAIT_10_16	Portrait aspect ratio of 10:16 This is the portrait aspect ratio of 8" and 10" Samsung tablets.
PORTRAIT_3_5	Portrait aspect ratio of 3:5 This is the portrait aspect ratio of Samsung Galaxy S tablets.
PORTRAIT_9_16	Portrait aspect ratio of 9:16 This is the portrait aspect ratio of almost all modern smart phones. This includes newer iPhones and Samsung phones.
PORTRAIT_600_1024	Portrait aspect ratio of 600:1024 This is an unusual portrait aspect ratio for the Kindle Fire tablet and the Samsung Galaxy 7.
PORTRAIT_IPAD_PRO	Portrait aspect ratio of 512:683 This is a unique portrait aspect ratio for the Apple iPad Pro.
LANDSCAPE_4_3	Landscape aspect ratio of 4:L This is the landscape aspect ratio of most Apple iPad's except for the iPad Pro. It is also the standard definition TV aspect ratio.
LANDSCAPE_3_2	Landscape aspect ratio of 3:2 This is the landscape aspect ratio of older iPhones (before the 4s) and Microsoft Surface 3.
LANDSCAPE_16_10	Landscape aspect ratio of 16:10 This is the landscape aspect ratio of 8" and 10" Samsung tablets. It is also the aspect ratio of Apple desktop and notebook displays.
LANDSCAPE_5_3	Landscape aspect ratio of 5:3 This is the landscape aspect ratio of Samsung Galaxy S tablets.
LANDSCAPE_16_9	Landscape aspect ratio of 16:9 This is the landscape aspect ratio of almost all modern smart phones. This includes newer iPhones and Samsung phones. It is also the high definition TV aspect ratio.
LANDSCAPE_1024_600	Landscape aspect ratio of 1024:600 This is an unusual landscape aspect ratio for the Kindle Fire tablet and the Samsung Galaxy 7.
LANDSCAPE_IPAD_PRO	Landscape aspect ratio of 683:512 This is a unique landscape aspect ratio for the Apple iPad Pro.
UKNOWN	The landscape aspect ratio is unknown This is an error value for type safety. It evaluates to an aspect ration of 0.

Constructor & Destructor Documentation

cugl::Display::Display ( )

protected

Creates a new, unitialized Display.

All of the values are set to 0 (except _aspect, which is 16:9). You must initialize the Display to access its values

WARNING: This class is a singleton. You should never access this constructor directly. Use the start() method instead.

cugl::Display::~Display ( )

inlineprotected

Deletes this object, releasing all resources.

This method quits the SDL video system, effectively exitting shutting down the entire program.

WARNING: This class is a singleton. You should never access this destructor directly. Use the stop() method instead.

Member Function Documentation

void cugl::Display::dispose ( )

protected

Uninitializes this object, releasing all resources.

This method quits the SDL video system, effectively exitting shutting down the entire program.

WARNING: This class is a singleton. You should never access this method directly. Use the stop() method instead.

static Display* cugl::Display::get ( )

inlinestatic

Returns the singleton instance for the display

You must call this static method first to get information about your specific display. This method will return nullptr until start() is called first.

Returns: the singleton instance for the display

Aspect cugl::Display::getAspect ( ) const

inline

Returns the aspect of this monitor.

The aspect is returned as an enum, not a ratio. Round off error might cause devices with very similar aspect ratios to have slightly different ratio values. Therefore, the enum is a way of normalizing device aspects.

If you would like to know the actual ratio, use the method getAspectRatio() instead. In addition, there are methods for computing width from height and vice versa.

Device aspects are relatively standardized. For information on your device, see

 http://mydevice.io/devices/

Returns: the aspect of this monitor.

static Aspect cugl::Display::getAspect ( float ratio )

static

Returns the aspect for the given aspect ratio.

It is safest to represent aspects as an enum, not a ratio. Round off error might cause devices with very similar aspect ratios to have slightly different ratio values. Therefore, the enum is a way of normalizing device aspects.

Device aspects are relatively standardized. For information on your device, see

 http://mydevice.io/devices/

This method is guaranteed to match every aspect ratio on that page. If the aspect ratio is not on that page, it will return UNKNOWN.

Parameters

ratio The aspect ratio in the form width/height

Returns: the aspect for the given aspect ratio.

const std::string cugl::Display::getAspectName ( ) const

inline

Returns a string representation of the device aspect ratio

This value is useful for debugging. The first part of the string, before the space, is guaranteed to be in the format x:y

Returns: a string representation of the aspect ratio

static const std::string cugl::Display::getAspectName ( Aspect aspect )

static

Returns a string representation of the given aspect

This value is useful for debugging. The first part of the string, before the space, is guaranteed to be in the format x:y

Parameters

aspect The device aspect value

Returns: a string representation of the given aspect

float cugl::Display::getAspectRatio ( ) const

inline

Returns the device aspect ratio

The value is computed width/height.

Returns: the device aspect ratio

static float cugl::Display::getAspectRatio ( Aspect aspect )

static

Returns the aspect ratio for the given aspect.

The value is computed width/height. If the aspect is UNKNOWN, it will return 0.

Parameters

aspect The device aspect value

Returns: the aspect ratio for the given aspect.

const Rect& cugl::Display::getBounds ( ) const

inline

Returns the full screen resolution for this display

This method returns the bounds for the current resolution, not the maximum resolution. You should never change the resolution of a display. Allow the user to have their preferred resolution. Instead, you should adjust your camera to scale the viewport.

The value returned represents points, not pixels. If you are using a traditional display, these are the same. However, on Retina displays and other high DPI monitors, these may be different. Regardless, you should always work with points, not pixels, when computing the screen size. In particular, this is what you should assign the OpenGL viewport when using fullscreen.

Rect cugl::Display::getPixelBounds ( ) const

inline

Returns the full screen resolution for this display

This method returns the bounds for the current resolution, not the maximum resolution. You should never change the resolution of a display. Allow the user to have their preferred resolution. Instead, you should adjust your camera to scale the viewport.

The value returned represents the value pixels, not points. This is to help align the results with input devices on Retina displays and other high DPI monitors.

const Vec2& cugl::Display::getPixelDensity ( ) const

inline

Returns the number of pixels for each point.

A point is a logical screen pixel. If you are using a traditional display, points and pixels are the same. However, on Retina displays and other high dpi monitors, they may be different. In particular, the number of pixels per point is a scaling factor times the point.

You should never need to use these scaling factor for anything, as it is not useful for determining anything other than whether a high DPI display is present. It does not necessarily refer to physical pixel on the screen. In some cases (OS X Retina displays), it refers to the pixel density of the backing framebuffer, which may be different from the physical framebuffer.

Returns: the number of pixels for each point.

const Rect& cugl::Display::getUsableBounds ( ) const

inline

Returns the usable full screen resolution for this display

Usable is a subjective term defined by the operating system. In general, it means the full screen minus any space used by important user interface elements, like a status bar (iPhone), menu bar (OS X), or task bar (Windows).

This method computes the bounds for the current resolution, not the maximum resolution. You should never change the resolution of a display. Allow the user to have their preferred resolution. Instead, you should adjust your camera to scale the viewport.

The value returned represents points, not pixels. If you are using a traditional display, these are the same. However, on Retina displays and other high DPI monitors, these may be different. Regardless, you should always work with points, not pixels, when computing the screen size.

int cugl::Display::heightForWidth ( int width ) const

inline

Returns the closest height value for the device aspect ratio.

This value is used when you want to scale a viewpoint to match the display. The value returned is rounded up to the nearest int, assuming that you want the viewport in points.

Parameters

width The width in points

Returns: the closest height value for the device aspect ratio.

static int cugl::Display::heightForWidth	(	int	width,
		Aspect	aspect
	)

inlinestatic

Returns the closest height value for the given aspect

This value is used when you want to scale a viewpoint to match the display. The value returned is rounded up to the nearest int, assuming that you want the viewport in points.

Parameters

width	The width in points
aspect	The device aspect value

Returns: the closest height value for the given aspect

bool cugl::Display::init ( )

protected

Initializes the display with the current screen information.

This method gathers the native resolution bounds and pixel density using platform-specific tools.

WARNING: This class is a singleton. You should never access this initializer directly. Use the start() method instead.

Returns: true if initialization was successful.

bool cugl::Display::isLandscape ( ) const

inline

Returns true if this device has a landscape orientation

Returns: true if this device has a landscape orientation

bool cugl::Display::isPortrait ( ) const

inline

Returns true if this device has a portrait orientation

Returns: true if this device has a portrait orientation

static bool cugl::Display::start ( )

static

Starts up the SDL display and video system.

This static method needs to be the first line of any application, though it is handled automatically in the Application class.

Once this method is called, the get() method will no longer return a null value.

static void cugl::Display::stop ( )

static

Shuts down the SDL display and video system.

This static method needs to be the last line of any application, though it is handled automatically in the Application class.

Once this method is called, the get() method will return nullptr. More importantly, no SDL function calls will work anymore.

int cugl::Display::widthForHeight ( int height ) const

inline

Returns the closest width value for the device aspect ratio.

This value is used when you want to scale a viewpoint to match the display. The value returned is rounded up to the nearest int, assuming that you want the viewport in points.

Parameters

height The height in points

Returns: the closest width value for the device aspect ratio.

static int cugl::Display::widthForHeight	(	int	height,
		Aspect	aspect
	)

inlinestatic

Returns the closest width value for the given aspect

This value is used when you want to scale a viewpoint to match the display. The value returned is rounded up to the nearest int, assuming that you want the viewport in points.

Parameters

height	The height in points
aspect	The device aspect value

Returns: the closest width value for the given aspect

Member Data Documentation

Aspect cugl::Display::_aspect

protected

The aspect ratio (coded as the enum)

Rect cugl::Display::_bounds

protected

The full screen resolution of this device

Vec2 cugl::Display::_scale

protected

The pixel density of the device

Display* cugl::Display::_thedisplay

staticprotected

The display singleton

Rect cugl::Display::_usable

protected

The full screen resolution minus menu bars and other features

The documentation for this class was generated from the following file:

base/CUDisplay.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation