PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Related Functions | List of all members
GraphicsManager Class Reference

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:

  1. 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.
  2. 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.
  3. 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
portthe 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
fontNamethe name of the font (ie: "Arial" or "Times")
scalingFactoran 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
rectthe dimensions of the drawing area
screenNumwhich screen to work with (optional)
allowResChangepass false to prevent monitor resolution from changing (optional)
bppthe 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
rectthe visible area of the window in screen coordinates
windNamethe window title (optional)
bppthe 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
screenNumthe 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
mouseNumberthe 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
nthe index into the list of supported screen modes, from 0 to number of support modes − 1
screenNumthe 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
screenthe 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
widththe desired width in pixels
heightthe desired height in pixels
screenNumthe screen to change, defaults to the primary screen if not passed
bppthe 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
inTargetFPSthe 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
allowResChangeif true, the monitor resolution will be changed to match the window size; defaults to false
portthe 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
portthe port to change, defaults to the main port if not passed
windNamethe name to give the window (optional)
Returns
true if mode switch succeeded, false if it did not

Friends And Related Function Documentation

getGraphicsManager
related

get the singleton instance of the GraphicsManager used by the pdg framework

Returns
GraphicsManager singleton object

User Comments