Used to create and track ports (GUI Only) More...

Public Member Functions
	closeGraphicsPort (Port port=MAIN_PORT)
	close given port, along with its window and restore screen mode if changed More...

Font	createFont (string fontName, number scalingFactor=1.0)
	get a font with optional scaling adjust More...

Port	createFullScreenPort (Rect rect, int screenNum=PRIMARY_SCREEN, boolean allowResChange=true, int bpp=0)
	create full screen drawing port with given dimensions on given screen, optionally changing depth More...

Port	createWindowPort (Rect rect, string windName="", int bpp=0)
	create windowed drawing port with given dimensions, title and depth More...

object	getCurrentScreenMode (int screenNum=PRIMARY_SCREEN)
	get width, height, depth and maxWindowRect for specified screen More...

number	getFPS ()
	get current frame rate More...

Port	getMainPort ()
	return the primary graphics port More...

Point	getMouse (int mouseNumber=0)
	get mouse position More...

object	getNthSupportedScreenMode (int n, int screenNum=PRIMARY_SCREEN)
	get the details of the Nth screen mode from the supported ones for a screen More...

number	getNumScreens ()
	get the total number of display screens available More...

number	getNumSupportedScreenModes (int screen=PRIMARY_SCREEN)
	get the total number of display modes available for a screen More...

number	getTargetFPS ()
	get the intended frame rate More...

boolean	inFullScreenMode ()
	return whether primary graphics port is fullscreen or not More...

	setScreenMode (int width, int height, int screenNum=PRIMARY_SCREEN, int bpp=0)
	changes specified screen to closest matching mode More...

GraphicsManager	setTargetFPS (number inTargetFPS)
	set the frames per second you would like the graphics system to display More...

boolean	switchToFullScreenMode (boolean allowResChange=false, Port port=MAIN_PORT)
	switch a port to full screen More...

boolean	switchToWindowMode (Port port=MAIN_PORT, string windName="")
	switch a port to be in a window More...

Related Functions
(Note that these are not member functions.)
	getGraphicsManager
	get the singleton instance of the GraphicsManager used by the pdg framework More...

	gfx
	the singleton instance of the GraphicsManager More...

Detailed Description

Used to create and track ports (GUI Only)

Note: API Stability: 2 - Unstable. The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable.

Full Screen

There are 3 primary ways to deal with fullscreen:

Easy: let the PDG Engine deal with everything, including switching screen resolution to give you what you ask for. Just call createFullScreenPort() with a desired port dimensions and it will just do the right thing.
Adaptable: don't allow the PDG engine to change display modes. Instead query the current screen mode and ask for that size (or something that fits within in). This will be more work for your display code since you will need to make all of your drawing calls handle different screen dimensions. This is often best for the end user and also works well with switching back and forth between full screen and running in a window.
Fine Tuned: you figure out exactly what you want and manage it yourself, querying the system for available screens, explicitly choosing which screen(s) you want to use and switching screen modes yourself before calling createFullScreenPort() with port dimensions, target screen and even pixel depth.

Running in a Window

Use createWindowPort() to create a window. The window will be movable and resizable, and you'll get eventType_PortResize events if it is resized by the user.

Display Rate

The Graphics system has the concept of a target display rate in frames per second, which is used to limit the frame rate, particularly important on mobile devices. This is independent of the animation and physics system. See getFPS(), getTargetFPS() and setTargetFPS().

Member Function Documentation

closeGraphicsPort ( Port port = MAIN_PORT )

close given port, along with its window and restore screen mode if changed

Parameters

port	the port to close, default to the main port if none passed

See Also: Port; createFullScreenPort; createWindowPort

Warning: closing the main port will quit the application, use setMainPort to change to a new port before closing an old one.

createFont	(	string	fontName,
		number	scalingFactor = `1.0`
	)

get a font with optional scaling adjust

Parameters

fontName	the name of the font (ie: "Arial" or "Times")
scalingFactor	an across-the-board amount to adjust the normal size of the font by

Returns: the Font requested

See Also: Font

createFullScreenPort	(	Rect	rect,
		int	screenNum = `PRIMARY_SCREEN`,
		boolean	allowResChange = `true`,
		int	bpp = `0`
	)

create full screen drawing port with given dimensions on given screen, optionally changing depth

Unless allowResChange is passed as false, the monitor resolution will be changed to match the closest allowable screen size for the given dimension. If no other port is open, this becomes the main port.

If no is screen specified, the primary screen will be used. If no depth is specified, the current depth of the specified screen will be used.

Parameters

rect	the dimensions of the drawing area
screenNum	which screen to work with (optional)
allowResChange	pass false to prevent monitor resolution from changing (optional)
bpp	the depth of the drawing buffer in bits per pixel (optional)

Returns: the newly created Port

See Also: getNumScreens; createWindowPort; closeGraphicsPort; switchToFullScreenMode; switchToWindowMode

createWindowPort	(	Rect	rect,
		string	windName = `""`,
		int	bpp = `0`
	)

create windowed drawing port with given dimensions, title and depth

Matches the depth of the screen if depth not given. If no other port is open, this becomes the main port.

Parameters

rect	the visible area of the window in screen coordinates
windName	the window title (optional)
bpp	the depth of the drawing buffer in bits per pixel (optional)

Returns: the newly created Port

See Also: Port; createFullScreenPort

getCurrentScreenMode ( int screenNum = PRIMARY_SCREEN )

get width, height, depth and maxWindowRect for specified screen

Parameters

screenNum the number of the screen, defaults to the primary screen if no screen number given

Returns: Object with width, height, depth and maxWindowRect members

See Also: setScreenMode; getNumScreens

getFPS ( )

get current frame rate

gets the current frame rate in frames per second that the rendering engine is producing. This should always be at or slightly below the target FPS.

Returns: current frame rate in frames per second

See Also: getTargetFPS; setTargetFPS

getMainPort ( )

return the primary graphics port

Returns: the primary Port

See Also: Port; createFullScreenPort; createWindowPort

getMouse ( int mouseNumber = 0 )

get mouse position

Gets the screen location of the given mouse or finger touch. For touch devices the number represents the order the fingers went down rather than specific numbered devices.

Parameters

mouseNumber the particular mouse; defaults to zero, the primary mouse or first touch

Returns: the Point location of the mouse or touch

Note: this relies on events from the OS, so you must be calling pdg.idle() or be in a pdg.run() loop to get mouse data.

getNthSupportedScreenMode	(	int	n,
		int	screenNum = `PRIMARY_SCREEN`
	)

get the details of the Nth screen mode from the supported ones for a screen

Parameters

n	the index into the list of supported screen modes, from 0 to number of support modes − 1
screenNum	the screen you are interested in, defaults to the primary screen if not passed

Returns: a screen mode object with width, height, depth members

Example**

PDG terminal v0.9.4 > pdg.gfx.getNthSupportedScreenMode(1); { width: 1440, height: 900, depth: 16 }

getNumScreens ( )

get the total number of display screens available

See Also: getCurrentScreenMode; createFullScreenPort; setScreenMode

getNumSupportedScreenModes ( int screen = PRIMARY_SCREEN )

get the total number of display modes available for a screen

Parameters

screen the screen number, defaults to the primary screen if not passed

Returns: the number of modes

See Also: getNthSupportedScreenMode; getCurrentScreenMode; setScreenMode; getNumScreens

getTargetFPS ( )

get the intended frame rate

Returns: the target frame rate in frames per second

See Also: setTargetFPS; getFPS

inFullScreenMode ( )

return whether primary graphics port is fullscreen or not

Returns: true if the main port exists and is in fullscreen mode, false otherwise

See Also: switchToFullScreenMode; switchToWindowMode; getMainPort; setScreenMode

setScreenMode	(	int	width,
		int	height,
		int	screenNum = `PRIMARY_SCREEN`,
		int	bpp = `0`
	)

changes specified screen to closest matching mode

Parameters

width	the desired width in pixels
height	the desired height in pixels
screenNum	the screen to change, defaults to the primary screen if not passed
bpp	the screen depth in bits per pixel, uses current screen depth if not passed

See Also: getCurrentScreenMode; getNumScreens

setTargetFPS ( number inTargetFPS )

set the frames per second you would like the graphics system to display

The graphics system will attempt to display that many frames per second on most systems. It will issue warnings in the logs if the frame rate falls below 80% of that rate.

Animations, Sprite movement, Network and other kinds of Events work independently of the display timer, so this will not affect collision detection even at lower frame rates.

Parameters

inTargetFPS the desired frame rate in Frames Per Second

See Also: getTargetFPS; getFPS

switchToFullScreenMode	(	boolean	allowResChange = `false`,
		Port	port = `MAIN_PORT`
	)

switch a port to full screen

Parameters

allowResChange	if true, the monitor resolution will be changed to match the window size; defaults to false
port	the port to change, defaults to the main port if not passed

Returns: true if mode switch succeeded, false if it did not

switchToWindowMode	(	Port	port = `MAIN_PORT`,
		string	windName = `""`
	)

switch a port to be in a window

If the monitor resolution was changed to go into full screen, it will be changed back to it's original value

Parameters

port	the port to change, defaults to the main port if not passed
windName	the name to give the window (optional)

Returns: true if mode switch succeeded, false if it did not

Friends And Related Function Documentation

getGraphicsManager

Returns: GraphicsManager singleton object

Public Member Functions

Related Functions

Detailed Description

Full Screen

Running in a Window

Display Rate

Member Function Documentation

Friends And Related Function Documentation

User Comments