Graphics output

Functions
void	graphics::drawRect (float center_x, float center_y, float width, float height, const Brush &brush)
void	graphics::drawLine (float x1, float y1, float x2, float y2, const Brush &brush)
void	graphics::drawDisk (float cx, float cy, float radius, const Brush &brush)
void	graphics::drawSector (float cx, float cy, float radius1, float radius2, float start_angle, float end_angle, const Brush &brush)
bool	graphics::setFont (std::string fontname)
void	graphics::drawText (float pos_x, float pos_y, float size, const std::string &text, const Brush &brush)
void	graphics::setOrientation (float angle)
void	graphics::setScale (float sx, float sy)
void	graphics::resetPose ()
std::vector< std::string >	graphics::preloadBitmaps (std::string dir)

Detailed Description

Function Documentation

drawDisk()

void graphics::drawDisk	(	float	cx,
		float	cy,
		float	radius,
		const Brush &	brush
	)

Draws a disk.

Draws a disk (or circle, if fill opacity is set to 0) of certain radius and centered at (cx, cy). The outline and fill attributes are specified in the brush parameter.

Parameters

cx	is the x coordinate of the center of the disk in canvas units.
cy	is the y coordinate of the center of the disk in canvas units.
radius	is the radius of the disk in canvas units.
brush	specifies the drawing attributes to use for the outline and fill of the shape.

See also

Brush

drawLine()

void graphics::drawLine	(	float	x1,
		float	y1,
		float	x2,
		float	y2,
		const Brush &	brush
	)

Draws a line segment.

Draws a linear segment between two points on the canvas. The outline attributes are specified in the brush parameter.

Parameters

x1	is the x coordinate of the first point in canvas units.
y1	is the y coordinate of the first point in canvas units.
x2	is the x coordinate of the second point in canvas units.
y2	is the y coordinate of the second point in canvas units.
brush	specifies the drawing attributes to use for the outline and fill of the shape.

See also

Brush

drawRect()

void graphics::drawRect	(	float	center_x,
		float	center_y,
		float	width,
		float	height,
		const Brush &	brush
	)

Draws a rectangle.

Draws a rectangle of size width X height, centered at (center_x, center_y). The shape outline and fill attributes are provided in the brush parameter.

Parameters

center_x	is the x coordinate of the rectangle center in canvas units.
center_y	is the y coordinate of the rectangle center in canvas units.
width	is the horizontal size of the rectangle center in canvas units.
height	is the vertical size of the rectangle center in canvas units.
brush	specifies the drawing attributes to use for the outline and fill of the shape.

See also

Brush

drawSector()

void graphics::drawSector	(	float	cx,
		float	cy,
		float	radius1,
		float	radius2,
		float	start_angle,
		float	end_angle,
		const Brush &	brush
	)

Draws a sector of a disk.

Draws a sector of a disk between an inner and outer radius and two angles. The outline and fill attributes are specified in the brush parameter.

// In the draw callback function:
graphics::Brush br;
br.fill_color[0] = 1.0f;
br.fill_color[1] = 0.1f;
br.fill_color[2] = 0.0f;
br.fill_secondary_color[0] = 0.0f;
br.fill_secondary_color[1] = 0.2f;
br.fill_secondary_color[2] = 1.f;
br.gradient = true;
br.gradient_dir_u = 1.0f;
br.gradient_dir_v = 0.0f;
 
graphics::drawSector(20, 20, 5, 10, 0, 90, br);

Parameters

cx	is the x coordinate of the center of the disk sector in canvas units.
cy	is the y coordinate of the center of the disk sector in canvas units.
radius1	is the inner radius of the disk sector in canvas units.
radius2	is the outer radius of the disk sector in canvas units.

drawText()

void graphics::drawText	(	float	pos_x,
		float	pos_y,
		float	size,
		const std::string &	text,
		const Brush &	brush
	)

Draws a string of text at a user-provided location on the canvas, using the current font.

The function displays the glyphs for the text provided, in a left-aligned manner. The coordinates passed to the function correspond to the lower left corner of the text box and the height of the glyphs is indicated by the size parameter. If there is no active font (or the setFont function failed), no text is drawn.

Parameters

pos_x	is the horizontal coordinate of the lower left corner of the text in canvas units.
pos_y	is the vertical coordinate of the lower left corner of the text in canvas units.
size	is the glyph height of the text to be drawn.
text	is the string of text to display.
brush	contains the drawing attributes. Only the fill parameters of the provided brush are used for drawing, including any gradient.

See also

setFont

preloadBitmaps()

std::vector<std::string> graphics::preloadBitmaps

(

std::string

dir

)

Loads all PNG bitmaps located in a directory specified by the argument dir at once.

Preloading image assets prior to actually requesting a draw call with a brush that uses them can significantly boost performance during the typical draw call when a bitmap is first used.

When a named image is used for a brush, the first time the library encounters the image asset with the specific unique name, it attempts to load the image, scale the bitmap to the closest power of two (if not already in the right resolution) and create the necessary internal representation for the underlying graphics API. For large assets, this process can take some time, noticeable as momentary freeze and general slowdown, depending on the size and number of images needed to be loaded. This of course happens only the first time a bitmap is used in the application, but can nevertheless degrade the user experience.

preloadBitmaps performs the above process in bulk, for all PNG bitmaps found in the provided directory. This can be done during the application initialization stage, before the actual main interaction loop begins. The function can be called multiple times for a different directory each time, to progressively load organized collections of bitmaps. preloadBitmaps returns a vector of the bitmaps successfully loaded, which can be used as a means to validate that all assets have been properly loaded. Another useful application of the function is to load multiple bitmaps without the need to know the specific names beforehand. For example, one can organize the frames of an animation sequence into a separate folder and load all the sequence at once, maintaining the animation bitmap names for reference and cycling over the animation sequence. Another different application example is the call of the function on a directory to discover and load all images contained there to be able to list and preview the images during runtime (e.g. in an image viewer application).

The preloadBitmaps function can be called at any time after the graphics initialization, i.e. after the call to createWindow.

Please note that since a bitmap is identified by its fully qualified path, bitmaps with the same filename residing in different directories are treated as two different assets. Also note that multiple attempts to preload the same bitmap will report the bitmap as successfully loaded in the return vector, but the actual bitmap loaded the first time will be used and will not be replaced by the loader in subsequent calls. This means that during runtime, even if one modifies the bitmap asset externally and explicitly calls preloadBitmaps (or any other bitmap loading via a new brush creation), the original bitmap loaded the first time will be used.

Parameters

dir	is the directory of the bitmaps to preload. Only PNG images will be loaded (extension is case-insensitive) and all other files in the directory will be ignored. The function is not called recursively for contained sub-directories.

Returns

a vector of the full path names to the individual bitmaps identified and successfully loaded. The path names will include the directory name given.

resetPose()

void graphics::resetPose

(

)

Restores both the orientation and scaling to their default values for subsequent draw calls.

setFont()

bool graphics::setFont

(

std::string

fontname

)

Sets the current font for text rendering.

Notifies the SGG engine to prepare and make current the font typeface in the filename supplied as argument. If the font is not already loaded into SGG, it loads the SGG and builds all necessary information for it. If the font name supplied does not correspond to a valid path to a TrueType typeface, the operation is silently aborted and no font is loaded or made active for text rendering. After loading the font, it is made current and all subsequent text drawing calls use this font for text rendering. If the font is already loaded into SGG, it is just made active for rendering. This operation does not incur any measurable overhead, as all resource allocation and convesion processes occur once, during the first call to load a specific font.

Parameters

fontname

is a valid path to the filename of the TrueType font (.ttf extension) to use.

Returns

true if the operation was successful, false otherwise.

See also

drawText

setOrientation()

void graphics::setOrientation

(

float

angle

)

Sets the current orientation that all subsequent draw calls will use for the displayed shapes.

SGG maintains a current orientation (default value 0.0f - no rotation) according to which it displays the shape of draw calls. Once set, the orientation is respected by all subsequent draw calls, until set to a new value or reset via a call to resetPose(). The rotation of the drawn shape in accordance with the orientation value occurs using a pivot point specific to the drawn shape. For rectangles, disks and sections, the pivot point is their center. For text, it is the lower left corner of the text bounds. Line segments are not rotated, since it is simpler to redefine their end-points.

Parameters

angle

is the angle of rotation for the shapes to draw in degrees. Positive angles correspond to counter-clockwise rotations.

setScale()

void graphics::setScale	(	float	sx,
		float	sy
	)

Sets the current scale that all subsequent draw calls will use for the displayed shapes.

SGG maintains a current scale (default value 1.0f - no scaling) according to which it displays the shape of draw calls. Once set, the scale is respected by all subsequent draw calls, until set to a new value or reset via a call to resetPose().

The scaling is defined by two scaling factors, one for each dimension of the shape. Setting an equal value for both parameters corresponds to a uniform scale (no distortion). Scaling factors greater than 1 mean shape magnification, while values less than 1 result in shrinking. Never set the scaling factor to 0.

The change of scale of the drawn shape along its X and Y dimension is performed prior to the rotation, using a pivot point specific to the drawn shape. For rectangles, disks and sections, the pivot point is their center. For text, it is the lower left corner of the text bounds. Line segments are not scaled, since it is simpler to redefine their end-points.

Parameters

sx	is the scale factor along the local X axis of the shape. 1 means no scaling.
sy	is the scale factor along the local Y axis of the shape. 1 means no scaling.