Window initialization and handling

Functions
void	graphics::createWindow (int width, int height, std::string title)
void	graphics::setWindowBackground (Brush style)
void	graphics::destroyWindow ()
void	graphics::startMessageLoop ()
void	graphics::stopMessageLoop ()
void	graphics::setCanvasSize (float w, float h)
void	graphics::setCanvasScaleMode (scale_mode_t sm)
void	graphics::setFullScreen (bool fs)
float	graphics::windowToCanvasX (float x, bool clamped=true)
float	graphics::windowToCanvasY (float y, bool clamped=true)
void	graphics::setUserData (const void *user_data)
void *	graphics::getUserData ()

Detailed Description

Function Documentation

createWindow()

void graphics::createWindow	(	int	width,
		int	height,
		std::string	title
	)

Creates and shows a framed window with a title of specific dimensions.

This should be the first function call to the SGG API. Internally, it performs library initialization and graphics canvas allocation and displays the window.

Parameters

width	is the window canvas width in pixel units.
height	is the window canvas height in pixel units.
title	is the title displayed on the window frame.

destroyWindow()

void graphics::destroyWindow

(

)

Destroys the application window and clears all internal resources.

This is typically the last SGG API call, before closing the application.

getUserData()

void* graphics::getUserData

(

)

Returns the user-submitted pointer that was previously set with setUserData().

If the memory pointed to by the provided pointer is freed, the user should also be careful and use setUserData(nullptr) to avoid accessing invalid memory later.

Returns

Returns the pointer that was previously submitted through setUserData(). The returned value is of type void*. The user is expected to know which the correct type is to cast it to. If no pointer was previously set, the function returns a nullptr.

See also

setUserData

setCanvasScaleMode()

void graphics::setCanvasScaleMode

(

scale_mode_t

sm

)

Defines how the canvas scales to adapt to the actual window size.

SGG supports 3 different modes of scaling the canvas to fit the window. The 3 modes are defined in the scale_mode_t enumeration.

Parameters

sm	is the scaling mode and is one of the following:

graphics::CANVAS_SCALE_WINDOW: The canvas size used for drawing corresponds to the current window size in pixel units. Custom canvas size provide via the setCanvasSize is ignored. Upon window size change, the canvas is adapted to be equal to the window client area resolution. This mode is useful if the graphics drawn must correspond to the specific image resolution of the window and should not be dynamically scaled.

graphics::CANVAS_SCALE_STRETCH: The canvas is stretched to fill the entire window. When the aspect ratio of tyhe canvas as specified by the user does not match the window aspect ratio, the drawn contents will appear distorted (stretched or compressed).

graphics::CANVAS_SCALE_FIT: The canvas is scaled to maximally fit the window but its aspect ratio is not affected. This means that if there is an aspect ration mismatch between the canvas and the window, the canvas will leave equal gaps along the axis of mismatch (centered). The window background outside the canvas will be painted with the user-defined background color. The drawn contents of the canvas will be clipped at the borders of the canvas and will not cross over to the elastic guard space.

See also

setWindowBackground

setCanvasSize

setCanvasSize()

void graphics::setCanvasSize	(	float	w,
		float	h
	)

Defines the extents of the drawing canvas in the custom units used by the application.

The function explicitly sets the desired width and height of the drawing canvas in the measurement units used by the developer of the application, irrespectively of the actual window size and resolution. The contents of the drawing canvas are scaled to fit the window according to the modes available via the setCanvasScaleMode function. For example, the developer may define that the drawing canvas should be 30 X 20 application units (e.g. cm). The drawing canvas will be then scaled to correspond to the actual window client area, properly adapted to fill the window resolution.

Please note that the canvas aspect ratio needs not correspond with the window aspect ratio. The fitting is determined by the setCanvasScaleMode function, as mentioned above.

Parameters

w	is the canvas width in custom units.
h	is the canvas height in custom units.

setFullScreen()

void graphics::setFullScreen

(

bool

fs

)

Puts the application window in full screen mode.

This function must immediately follow the window creation, otherwise it may result in an unexpected behavior.

Parameters

fs	should be set to either true for full screen or false for windowed mode.

setUserData()

void graphics::setUserData

(

const void *

user_data

)

Specifies a user-provided pointer to be stored within the SGG Engine.

Typically, at the start of the application the user creates a class that holds the application's state. A pointer to this class can be passed to setUserData(). At any later point in the application's lifecycle, the stored pointer can be retrieved using getUserData(). This is very useful for retreiving application data during callbacks for update, draw and resize.

Parameters

user_data

is the pointer that the user wants to store within the SGG engine. This pointer can later be retrieved using getUserData().

See also

getUserData

Potential usage:

void resize(int new_w, int new_h)
{
    ...
    Game* the_game = (Game*)graphics::getUserData();
    ...
}
 
void update(float ms)
{
    ...
    Game* the_game = (Game*)graphics::getUserData();
    ...
}
 
void draw()
{
    ...
    Game* the_game = (Game*)graphics::getUserData();
    ...
}
 
struct Game {
    int data_a;
    int data_b;
    ...
    ...
};
 
int main()
{
    ...
    Game* the_game = new Game();
 
    graphics::createWindow(960, 540, "Night of the Living Arkanoid");
    graphics::setUserData(the_game);
    ...
    return 0;
}

setWindowBackground()

void graphics::setWindowBackground

(

Brush

style

)

Sets the color to fill the background of the main window, including the area outside the drawing canvas extents.

The function can be called at any time (after creating a window). Typical use:

graphics::Brush br;
br.fill_color[0] = 0.2f;
br.fill_color[1] = 0.3f;
br.fill_color[2] = 0.6f;
graphics::setWindowBackground(br);

Parameters

style

is the graphics::Brush structure defining the background color. Only the fill_color field is used.

startMessageLoop()

void graphics::startMessageLoop

(

)

Starts the message pump loop of the application window.

The function processes all window and user interface events and is alos responsible for internally calling the draw callback defined by the user to refresh the visual content of the window. The user also defines and provides an optional but typically present application state update function, where all input processing is performed along with time-dependent updates of the application logic.

The function should be called after all application initialization is done, including the setup of any callback functions to invoke upon the draw, state update and resizing events. The function only returns when the application window signals a quit event or the ESC key is pressed.

Typical usage:

graphics::createWindow(960, 540, "Night of the Living Arkanoid");
graphics::setDrawFunction(draw);  // draw is a user-defined function 
                                  // that issues calls to the library's draw functions 
                                  // to paint the window canvas. 
graphics::setUpdateFunction(update);  // update is a user-defined function to perform all 
                                      // user input polling and application state updates.
 
... // application initialization code.
 
graphics::startMessageLoop();
graphics::destroyWindow();

stopMessageLoop()

void graphics::stopMessageLoop

(

)

Terminates the message processing loop of the engine and returns control to the caller of startMessageLoop().

windowToCanvasX()

float graphics::windowToCanvasX	(	float	x,
		bool	clamped = true
	)

Converts the horizontal window coordinate of a point to the corresponding canvas coordinate.

This function is useful for translating window coordinates (e.g. from the MouseState reported position) to the canvas space.

Parameters

x	is the window x coordinate to convert.
clamped	specifies whether the coordinates reported are clamped to the extents of the canvas.

Returns

the horizontal coordinate in canvas units.

See also

windowToCanvasY

windowToCanvasY()

float graphics::windowToCanvasY	(	float	y,
		bool	clamped = true
	)

Converts the vertical window coordinate of a point to the corresponding canvas coordinate.

This function is useful for translating window coordinates (e.g. from the MouseState reported position) to the canvas space.

Parameters

y	is the window y coordinate to convert.
clamped	specifies whether the coordinates reported are clamped to the extents of the canvas.

Returns

the vertical coordinate in canvas units.

See also

windowToCanvasX