#include <CUDisplay.h>

Public Types
enum	Orientation : unsigned int { Orientation::FIXED = 0, Orientation::LANDSCAPE = 1, Orientation::PORTRAIT = 2, Orientation::LANDSCAPE_REVERSED = 3, Orientation::UPSIDE_DOWN = 4, Orientation::FACE_UP = 5, Orientation::FACE_DOWN = 6, Orientation::UNKNOWN = 7 }

typedef std::function< void(Orientation previous, Orientation current, bool display)>	Listener

Public Member Functions
std::string	getTitle () const

void	setTitle (const std::string &title)

void	setTitle (const char *title)

void	show ()

void	hide ()

Rect	getBounds () const

Rect	getPixelBounds () const

Rect	getSafeBounds (bool display=true)

Vec2	getPixelDensity () const

bool	isLandscape () const

bool	isPortrait () const

bool	hasNotch () const

Orientation	getInitialOrientation () const

Orientation	getDisplayOrientation () const

Orientation	getDeviceOrientation () const

Orientation	getDefaultOrientation () const

bool	hasOrientationListener () const

const Listener	getOrientationListener () const

void	setOrientationListener (Listener listener)

bool	removeOrientationListener ()

void	refresh ()

void	restoreRenderTarget ()

void	queryRenderTarget ()

Static Public Member Functions
static bool	start (std::string title, Rect bounds, Uint32 flags)

static void	stop ()

static Display *	get ()

Static Public Attributes
static Uint32	INIT_FULLSCREEN

static Uint32	INIT_HIGH_DPI

static Uint32	INIT_MULTISAMPLED

static Uint32	INIT_CENTERED

Protected Member Functions
	Display ()

bool	init (std::string title, Rect bounds, Uint32 flags)

void	dispose ()

	~Display ()

Protected Attributes
std::string	_title

SDL_Window *	_window

SDL_GLContext	_glContext

int	_framebuffer

int	_rendbuffer

Rect	_bounds

Rect	_usable

Vec2	_scale

bool	_notched

Listener	_orientationListener

Orientation	_initialOrientation

Orientation	_displayOrientation

Orientation	_deviceOrientation

Orientation	_defaultOrientation

Static Protected Attributes
static Display *	_thedisplay

Friends
class	Application

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 primary purpose of the display object is to initialize (and dispose) the OpenGL context. Any start-up features for OpenGL should go in this class. That are set via static attributes (like Application#setFullscreen(bool) that are read by the method start(). Setting these attributes after the display has started will have no effect (though this may be a feature for later releases).

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.

The singleton display also has information about the display and device orientation for mobile devices. In fact, is is possible to assign a listener to the object to respond to changes in device orientation.

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

Member Typedef Documentation

◆ Listener

cugl::Display::Listener

This type represents a listener for an orientation change.

In CUGL, listeners are implemented as a set of callback functions, not as objects. For simplicity, Displays only have a single listener that handles both display and device changes (see getDisplayOrientation() and getDeviceOrientation().) If you wish for more than one listener, then your listener should handle its own dispatch.

Since the device orientation will always change when the display orientation does, this callback can easily safely handle both. The boolean parameter in the callback indicates whether or not a display orientation change has happened as well.

Unlike other events, this callback will be invoked at the end of an animation frame, after the screen has been drawn. So it will be processed before any input events waiting for the next frame.

The function type is equivalent to

 std::function<void(Orientation previous, Orientation current, bool display)>

Parameters

previous	The previous device orientation (before the change)
current	The current device orientation (after the change)
display	Whether the display orientation has changed as well

Member Enumeration Documentation

◆ Orientation

enum cugl::Display::Orientation : unsigned int

strong

The possible device/display orientations.

We use the same orientations for device and display even though these may not always agree (such as when the user has locked the display)

Enumerator
FIXED	The orientation that of a fixed display. This is the orientation for desktops and laptops. This orientation will never change.
LANDSCAPE	Landscape orientation with the right side up. One notched devices, this will put the notch to the left. On devices with a home button, the button will be to the right.
PORTRAIT	Standard portrait orientation One notched devices, this will put the notch to the top. On devices with a home button, the button will be to the bottom.
LANDSCAPE_REVERSED	Landscape orientation with the left side up. One notched devices, this will put the notch to the right. On devices with a home button, the button will be to the left.
UPSIDE_DOWN	Reversed portrait orientation One notched devices, this will put the notch to the bottom. On devices with a home button, the button will be to the top. Many devices (e.g. iPhones) do not allow this mode as it interferes with the camera and incoming calls.
FACE_UP	The device is face up. This is a device-only orientation, not a display orientation. Some devices will not report this orientation.
FACE_DOWN	The device is face down. This is a device-only orientation, not a display orientation. Some devices will not report this orientation.
UNKNOWN	The orientation is unknown. This is rarely ever reported, and may mean an issue with the accelerometer in the case of a mobile device.

Constructor & Destructor Documentation

◆ Display()

cugl::Display::Display ( )

protected

Creates a new, unitialized Display.

All of the values are set to 0 or UNKNOWN, depending on their type. 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.

◆ ~Display()

cugl::Display::~Display ( )

inlineprotected

Deletes this object, releasing all resources.

This method quits the SDL video system and disposes the OpenGL context, effectively exitting and 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

◆ dispose()

void cugl::Display::dispose ( )

protected

Uninitializes this object, releasing all resources.

This method quits the SDL video system and disposes the OpenGL context, effectively exitting and shutting down the entire program.

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

◆ get()

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

◆ getBounds()

Rect cugl::Display::getBounds ( ) const

inline

Returns the full screen resolution for this display in points.

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.

Returns: the full screen resolution for this display in points.

◆ getDefaultOrientation()

Orientation cugl::Display::getDefaultOrientation ( ) const

inline

Returns the default orientation of this device.

The default orientation corresponds to the intended orientiation that this mobile device should be held. For devices with home buttons, this home button is always expected at the bottom. For the vast majority of devices, this means the intended orientation is Portrait. However, some Samsung tablets have the home button oriented for Landscape.

This is important because the accelerometer axis is oriented relative to the default orientation. So a default landscape device will have a different accelerometer orientation than a portrait device.

If this display is not a mobile device, it will always return Orientation::FIXED.

Returns: the default orientation of this device.

◆ getDeviceOrientation()

Orientation cugl::Display::getDeviceOrientation ( ) const

inline

Returns the current device orientation.

The device orientation is the orientation of a mobile device, as held by the user. It may or may not agree with the display orientation, which is how the screen is drawn. For example, if the screen is locked to landscape orientation, it is still possible for the device to have portrait orientation when it is held on its side.

This method is useful when you want to switch game modes for a different orientation (e.g. Powerpuff Girls Flipped Out).

If this display is not a mobile device, this method will always return Orientation::FIXED.

Returns: the current device orientation.

◆ getDisplayOrientation()

Orientation cugl::Display::getDisplayOrientation ( ) const

inline

Returns the current display orientation.

This value is the current display orientation. The display orientation is the orientation of the coordinate space for drawing on a mobile device. In other words, the origin is at the bottom left of the screen in this device orientation.

This display orientation may or may not agree with the device orientation. In particular, it will not agree if the display orientation is locked (to say portrait or landscape only). However, this is the orientation that is important for drawing to the screen. To get the device orientation, call getDeviceOrientation().

If this display is not a mobile device, this method will always return Orientation::FIXED.

Returns: the current display orientation.

◆ getInitialOrientation()

Orientation cugl::Display::getInitialOrientation ( ) const

inline

Returns the initial display orientation.

This value is the display orientation at startup. The display orientation is the orientation of the coordinate space for drawing on a mobile device. In other words, the origin is at the bottom left of the screen in this device orientation.

This display orientation may or may not agree with the device orientation. In particular, it will not agree if the display orientation is locked (to say portrait or landscape only). However, this is the orientation that is important for drawing to the screen. To get the device orientation, call getDeviceOrientation().

If this display is not a mobile device, this method will always return Orientation::FIXED.

Returns: the initial display orientation.

◆ getOrientationListener()

const Listener cugl::Display::getOrientationListener ( ) const

inline

Returns the listener for the display orientation.

This listener handles changes in either the device orientation (see getDeviceOrientation() or the display orientation (see getDeviceOrientation(). Since the device orientation will always change when the display orientation does, this callback can easily safely handle both. The boolean parameter in the callback indicates whether or not a display orientation change has happened as well.

Unlike other events, this listener will be invoked at the end of an animation frame, after the screen has been drawn. So it will be processed before any input events waiting for the next frame.

The display may only have one orientation listener at a time. If there is no listener, this method returns nullptr.

Returns: the orientation listener (if any) for this display

◆ getPixelBounds()

Rect cugl::Display::getPixelBounds ( ) const

inline

Returns the full screen resolution for this display in pixels.

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.

Returns: the full screen resolution for this display in pixels.

◆ getPixelDensity()

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.

◆ getSafeBounds()

Rect cugl::Display::getSafeBounds ( bool display = true )

Returns the usable full screen resolution for this display in points.

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), or a notch (iPhone X). In the case of the latter, you can specify whether you want to use the display orientation or the device orientation.

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.

Parameters

display Whether to use the display (as opposed to the device) orientation

Returns: the usable full screen resolution for this display in points.

◆ getTitle()

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

inline

Returns the title of this display

On a desktop, this title will be displayed at the top of the window.

Returns: the title of this display

◆ hasNotch()

bool cugl::Display::hasNotch ( ) const

inline

Returns true if this device has a notch.

Notched devices are edgeless smartphones or tablets that include at dedicated area in the screen for a camera. Examples include the iPhone X.

If a device is notched you should call getSafeBounds() before laying out UI elements. It is acceptable to animate and draw backgrounds behind the notch, but it is not acceptable to place UI elements outside of these bounds.

Returns: true if this device has a notch.

◆ hasOrientationListener()

bool cugl::Display::hasOrientationListener ( ) const

inline

Returns true if this display has an orientation listener

This listener handles changes in either the device orientation (see getDeviceOrientation() or the display orientation (see getDeviceOrientation(). Since the device orientation will always change when the display orientation does, this callback can easily safely handle both. The boolean parameter in the callback indicates whether or not a display orientation change has happened as well.

Unlike other events, this listener will be invoked at the end of an animation frame, after the screen has been drawn. So it will be processed before any input events waiting for the next frame.

The display may only have one orientation listener at a time.

Returns: true if this display has an orientation listener

◆ hide()

void cugl::Display::hide ( )

Hides the window for this display (assuming it was visible).

This method does nothing if the window was not visible.

◆ init()

bool cugl::Display::init	(	std::string	title,
		Rect	bounds,
		Uint32	flags
	)

protected

Initializes the display with the current screen information.

This method creates a display with the given title and bounds. As part of this initialization, it will create the OpenGL context, using the flags provided. The bounds are ignored if the display is fullscreen. In that case, it will use the bounds of the display.

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

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

Parameters

title	The window/display title
bounds	The window/display bounds
flags	The initialization flags

Returns: true if initialization was successful.

◆ isLandscape()

bool cugl::Display::isLandscape ( ) const

Returns true if this device has a landscape orientation

Returns: true if this device has a landscape orientation

◆ isPortrait()

bool cugl::Display::isPortrait ( ) const

Returns true if this device has a portrait orientation

Returns: true if this device has a portrait orientation

◆ queryRenderTarget()

void cugl::Display::queryRenderTarget ( )

Queries the identity of the default frame/render buffer.

This is necessary when you are using a RenderTarget and want to restore control the frame buffer. It is necessary because 0 is NOT necessarily the correct id of the default framebuffer (particularly on iOS).

◆ refresh()

void cugl::Display::refresh ( )

Refreshes the display.

This method will swap the OpenGL framebuffers, drawing the screen.

It will also reassess the orientation state and call the listener as necessary

◆ removeOrientationListener()

bool cugl::Display::removeOrientationListener ( )

Removes the display orientation listener for this display.

This listener handles changes in either the device orientation (see getDeviceOrientation() or the display orientation (see getDeviceOrientation(). Since the device orientation will always change when the display orientation does, this callback can easily safely handle both. The boolean parameter in the callback indicates whether or not a display orientation change has happened as well.

Unlike other events, this listener will be invoked at the end of an animation frame, after the screen has been drawn. So it will be processed before any input events waiting for the next frame.

A display may only have one orientation listener at a time. If this display does not have an orientation listener, this method will fail.

Returns: true if the listener was succesfully removed

◆ restoreRenderTarget()

void cugl::Display::restoreRenderTarget ( )

Restores the default frame/render buffer.

This is necessary when you are using a RenderTarget and want to restore control the frame buffer. It is necessary because 0 is NOT necessarily the correct id of the default framebuffer (particularly on iOS).

◆ setOrientationListener()

void cugl::Display::setOrientationListener ( Listener listener )

inline

Sets the orientation listener for this display.

This listener handles changes in either the device orientation (see getDeviceOrientation() or the display orientation (see getDeviceOrientation(). Since the device orientation will always change when the display orientation does, this callback can easily safely handle both. The boolean parameter in the callback indicates whether or not a display orientation change has happened as well.

A display may only have one orientation listener at a time. If this display already has an orientation listener, this method will replace it for the once specified.

Unlike other events, this listener will be invoked at the end of an animation frame, after the screen has been drawn. So it will be processed before any input events waiting for the next frame.

Parameters

listener The listener to use

◆ setTitle() [1/2]

void cugl::Display::setTitle ( const char * title )

Sets the title of this display

On a desktop, the title will be displayed at the top of the window.

Parameters

title The title of this display

◆ setTitle() [2/2]

void cugl::Display::setTitle ( const std::string & title )

inline

Sets the title of this display

On a desktop, the title will be displayed at the top of the window.

Parameters

title The title of this display

◆ show()

void cugl::Display::show ( )

Shows the window for this display (assuming it was hidden).

This method does nothing if the window was not hidden.

◆ start()

static bool cugl::Display::start	(	std::string	title,
		Rect	bounds,
		Uint32	flags
	)

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.

This method creates the display with the given title and bounds. As part of this initialization, it will create the OpenGL context, using the flags provided. The bounds are ignored if the display is fullscreen. In that case, it will use the bounds of the display.

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

Parameters

title	The window/display title
bounds	The window/display bounds
flags	The initialization flags

Returns: true if the display was successfully initialized

◆ stop()

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. It will dipose of the display and the OpenGL context.

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

Friends And Related Function Documentation

◆ Application

friend class Application

friend

This is called by the application loop

Member Data Documentation

◆ _bounds

Rect cugl::Display::_bounds

protected

The full screen resolution of this device

◆ _defaultOrientation

Orientation cugl::Display::_defaultOrientation

protected

The value of the default orientation

◆ _deviceOrientation

Orientation cugl::Display::_deviceOrientation

protected

The value of the device orientation

◆ _displayOrientation

Orientation cugl::Display::_displayOrientation

protected

The value of the display orientation

◆ _framebuffer

int cugl::Display::_framebuffer

protected

The default framebuffer associated with the display

◆ _glContext

SDL_GLContext cugl::Display::_glContext

protected

The associated OpenGL drawing context

◆ _initialOrientation

Orientation cugl::Display::_initialOrientation

protected

The value of the initial orientation

◆ _notched

bool cugl::Display::_notched

protected

Whether this device has a notch in it

◆ _orientationListener

Listener cugl::Display::_orientationListener

protected

A listener for the orientation

◆ _rendbuffer

int cugl::Display::_rendbuffer

protected

The default renderbuffer associated with the display

◆ _scale

Vec2 cugl::Display::_scale

protected

The pixel density of the device

◆ _thedisplay

Display* cugl::Display::_thedisplay

staticprotected

The display singleton

◆ _title

std::string cugl::Display::_title

protected

The title (Window name) of the display

◆ _usable

Rect cugl::Display::_usable

protected

The full screen resolution minus menu bars and other features

◆ _window

SDL_Window* cugl::Display::_window

protected

The SDL window, which provides the OpenGL drawing context

◆ INIT_CENTERED

Uint32 cugl::Display::INIT_CENTERED

static

Whether this display should be centered (on windowed screens)

◆ INIT_FULLSCREEN

Uint32 cugl::Display::INIT_FULLSCREEN

static

Whether this display should use the fullscreen

◆ INIT_HIGH_DPI

Uint32 cugl::Display::INIT_HIGH_DPI

static

Whether this display should support a High DPI screen

◆ INIT_MULTISAMPLED

Uint32 cugl::Display::INIT_MULTISAMPLED

static

Whether this display should be multisampled

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

include/cugl/base/CUDisplay.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ Listener

Member Enumeration Documentation

◆ Orientation

Constructor & Destructor Documentation

◆ Display()

◆ ~Display()

Member Function Documentation

◆ dispose()

◆ get()

◆ getBounds()

◆ getDefaultOrientation()

◆ getDeviceOrientation()

◆ getDisplayOrientation()

◆ getInitialOrientation()

◆ getOrientationListener()

◆ getPixelBounds()

◆ getPixelDensity()

◆ getSafeBounds()

◆ getTitle()

◆ hasNotch()

◆ hasOrientationListener()

◆ hide()

◆ init()

◆ isLandscape()

◆ isPortrait()

◆ queryRenderTarget()

◆ refresh()

◆ removeOrientationListener()

◆ restoreRenderTarget()

◆ setOrientationListener()

◆ setTitle() [1/2]

◆ setTitle() [2/2]

◆ show()

◆ start()

◆ stop()

Friends And Related Function Documentation

◆ Application

Member Data Documentation

◆ _bounds

◆ _defaultOrientation

◆ _deviceOrientation

◆ _displayOrientation

◆ _framebuffer

◆ _glContext

◆ _initialOrientation

◆ _notched

◆ _orientationListener

◆ _rendbuffer

◆ _scale

◆ _thedisplay

◆ _title

◆ _usable

◆ _window

◆ INIT_CENTERED

◆ INIT_FULLSCREEN

◆ INIT_HIGH_DPI

◆ INIT_MULTISAMPLED