Graphics

namespace ezgl

A library for creating a graphical user interface.

Typedefs

typedef cairo_surface_t surface

define ezgl::surface type used for drawing png bitmaps

Enums

enum t_coordinate_system

Available coordinate systems

Values:

enumerator WORLD

Default coordinate system; specified by the user as any desired range. Graphics drawn in world coordinates will be transformed to screen pixels by ezgl. Panning and zooming change the transformation from world to screen coordinates, so they automatically work for any graphics drawn in wrld coordinates.

enumerator SCREEN

Screen (pixel) coordinate system. Screen Coordinates are not transformed so the drawn objects do not pan or zoom.

enum class justification

Justification options used for text and surfaces

Values:

enumerator center

Center Justification: used for both vertical and horizontal justification

enumerator left

Left justification: used for horizontal justification

enumerator right

Right justification: used for horizontal justification

enumerator top

Top justification: used for vertical justification

enumerator bottom

Bottom justification: used for vertical justification

enum class font_slant : int

The slant of the font.

This enum is setup to match with the cairo graphics library and should not be changed.

Values:

enumerator normal

No slant.

enumerator italic

Slant is more calligraphic. Make sure the font you’re using has an italic design, otherwise it may look ugly.

enumerator oblique

Slanted to the right.

enum class font_weight : int

The weight of the font.

Values:

enumerator normal

No additional weight.

enumerator bold

Bold font weight.

enum class line_cap : int

The shape of a line’s start and end point.

Values:

enumerator butt

Start and stop the line exactly where it begins/ends.

enumerator round

Each end of the line has circles. This is useful to ensure polylines formed of multiple line segments do not have gaps in them.

enum class line_dash : int

The dash style of a line.

Values:

enumerator none

No dashes in the line (i.e., solid).

enumerator asymmetric_5_3

Dash to whitespace ratio is 5:3.

class renderer
#include <graphics.hpp>

Provides functions to draw primitives (e.g., lines, shapes) to a rendering context (the MainCanvas).

The various set_ functions are sticky; they remain in effect for all graphics drawing calls after them, until overrideen by a later set_ call.

The renderer modifies a cairo_t context based on draw calls. The renderer uses an ezgl::camera object to convert world coordinates into cairo’s expected coordinate system.

Public Functions

void set_coordinate_system(t_coordinate_system new_coordinate_system)

Change the current coordinate system

Parameters:

new_coordinate_system – The drawing coordinate system SCREEN or WORLD

void set_visible_world(rectangle new_world)

Set the visible bounds of the world

The function preserves the aspect ratio of the new world so that a single x-unit and a single y-unit map to the same distance on screen. It does this by expanding the new_world in either the x- or y-direction so it matches the MainCanvas aspect ratio.

Parameters:

new_world – The new visible bounds of the world. new_world.first is the lower left corner of the MainCanvas, and new_world.second is the upper right.

rectangle get_visible_world()

Get the current visible bounds of the world

Returns:

A rectangle where rectangle.first is the lower left MainCanvas corner and rectangle.second is the upper right

rectangle get_visible_screen()

Get the current visible bounds of the screen in pixel coordinates

Returns:

A rectangle where rectangle.first is the lower left MainCanvas corner and rectangle.second is the upper right

rectangle world_to_screen(const rectangle &box)

Get the screen coordinates (pixel locations) of the world coordinate rectangle box

Parameters:

box – A rectangle in world coordinates

Returns:

The corresponding rectangle in screen coordinates

void set_color(color new_color)

Change the color for subsequent draw calls.

Parameters:

new_color – The new color to use.

void set_color(color new_color, uint_fast8_t alpha)

Change the color for subsequent draw calls. Opaque drawing is about 2x faster than partially transparent.

Parameters:

  • new_color – The new color to use.

  • alpha – The transparency level. 0 is fully tranparent, 255 is opaque.

void set_color(uint_fast8_t red, uint_fast8_t green, uint_fast8_t blue, uint_fast8_t alpha = 255)

Change the color for subsequent draw calls. Opaque drawing is about 2x faster than partially transparent.

Parameters:

  • red – The amount of red to use, between 0 and 255.

  • green – The amount of green to use, between 0 and 255.

  • blue – The amount of blue to use, between 0 and 255.

  • alpha – (optional) The transparency level. 0 is fully transparent, 255 is opaque. Defaults to opaque is not specified.

void set_line_cap(line_cap cap)

Change how line endpoints will be rendered in subsequent draw calls.

Parameters:

cap – The line_cap style

void set_line_dash(line_dash dash)

Change the dash style of the line for subsequent draw calls.

Parameters:

dash – The line_dash style

void set_line_width(int width)

Set the line width.

Parameters:

width – The width in pixels. A value of 0 is still one pixel wide but about 100x faster to draw than other line widths as small accuracy shortcuts are allowed. Line widths are in pixels (i.e. screen coordinates) and do not scale as graphics are zoomed in or out.

void set_font_size(double new_size)

Change the font size.

Parameters:

new_size – The size text should be drawn at, in points. A point is 1/72 of an inch. Text sizes do not scale as graphics are zoomed in and out; they are always drawn at the chosen point size.

void format_font(std::string const &family, font_slant slant, font_weight weight)

Change the font.

Parameters:

  • family – The font family to use (e.g., serif). Use an empty string to request the default font.

  • slant – The slant to use (e.g., italic)

  • weight – The weight of the font (e.g., bold)

void format_font(std::string const &family, font_slant slant, font_weight weight, double new_size)

Change the font.

Parameters:

  • family – The font family to use (e.g., serif). Use an empty string to request the default font.

  • slant – The slant to use (e.g., italic)

  • weight – The weight of the font (e.g., bold)

  • new_size – The new size text should be drawn at.

void set_text_rotation(double degrees)

set the rotation_angle at which subsequent text drawing should render.

Parameters:

degrees – The angle by which the text should rotate, in degrees from the x-axis.

void set_horiz_justification(justification horiz_just)

set horizontal justification; used for text and surfaces.

Parameters:

horiz_just – Options: center, left and right justification.

void set_vert_justification(justification vert_just)

set vertical justification; used for text and surfaces.

Parameters:

vert_just – Options: center, top and bottom justification.

void draw_line(point2d start, point2d end)

Draw a line.

Parameters:

  • start – The start point of the line, in the current coordinate system

  • end – The end point of the line

void draw_rectangle(point2d start, point2d end)

Draw the outline a rectangle.

Parameters:

  • start – A corner point of the rectangle, in the current coordinate system

  • end – The diagonally opposite point of the rectangle

void draw_rectangle(point2d start, double width, double height)

Draw the outline of a rectangle.

Parameters:

  • start – The lower left corner of the rectangle, in the current coordinate system

  • width – How wide the rectangle is, in the current coordinate system

  • height – How high the rectangle is

void draw_rectangle(rectangle r)

Draw the outline of a rectangle

Parameters:

r – The rectangle

void fill_rectangle(point2d start, point2d end)

Draw a filled in rectangle.

Parameters:

  • start – One corner of the rectangle, in the current coordinate system

  • end – The diagonally opposite corner of the rectangle

void fill_rectangle(point2d start, double width, double height)

Draw a filled in rectangle.

Parameters:

  • start – The lower left corner of the rectangle, the current coordinate system

  • width – How wide the rectangle is, in the current coordinate system

  • height – How high the rectangle is

void fill_rectangle(rectangle r)

Draw a filled in rectangle.

Parameters:

r – The rectangle

void fill_poly(std::vector<point2d> const &points)

Draw a filled polygon The polygon can have an arbitrary shape and be convex or non-convex, but must be simple (no holes).

Parameters:

points – The points to draw, which must be in the current coordinate system (world or screen). The first and last points are connected to close the polygon. There must be at least 2 points.

void draw_elliptic_arc(point2d center, double radius_x, double radius_y, double start_angle, double extent_angle)

Draw the outline of an elliptic arc

Parameters:

  • center – The center of the arc, in the current coordinate system

  • radius_x – The x radius of the elliptic arc, in the current coordinate system

  • radius_y – The y radius of the elliptic arc.

  • start_angle – The starting angle of the arc, in degrees from the positive x axis

  • extent_angle – The extent angle of the arc, in degrees from the positive x axis

void draw_arc(point2d center, double radius, double start_angle, double extent_angle)

Draw the outline of an arc

Parameters:

  • center – The center of the arc, in the current coordinate system

  • radius – The radius of the arc, in the current coordinate system

  • start_angle – The starting angle of the arc, in degrees from the positive x axis

  • extent_angle – The extent angle of the arc, in degrees from the positive x axis

void fill_elliptic_arc(point2d center, double radius_x, double radius_y, double start_angle, double extent_angle)

Draw a filled in elliptic arc

Parameters:

  • center – The center of the arc, in pixels.

  • radius_x – The x radius of the elliptic arc, in the current coordinate sstem.

  • radius_y – The y radius of the elliptic arc, in the current coordinate system.

  • start_angle – The starting angle of the arc, in degrees from the positive x axis.

  • extent_angle – The extent angle of the arc, in degrees from the positive x axis.

void fill_arc(point2d center, double radius, double start_angle, double extent_angle)

Draw a filled in arc

Parameters:

  • center – The center of the arc, in the current coordinate system

  • radius – The radius of the arc, in the current coordinate system

  • start_angle – The starting angle of the arc, in degrees from the positive x axis

  • extent_angle – The extent angle of the arc, in degrees from the positive x axis

void draw_text(point2d point, std::string const &text)

Draw text justified at the chosen point, according to the current justification

Parameters:

  • point – The point where the text is drawn, in the current coordinate system

  • text – The text to draw

void draw_text(point2d point, std::string const &text, double bound_x, double bound_y)

Draw text if it fits in the specified bounds; otherwise not drawn.

Parameters:

  • point – The point where the text is drawn (justified according to the current justification), in the current coordinate system.

  • text – The text to draw

  • bound_x – The maximum allowed width of the text, in the current coordinate system.

  • bound_y – The maximum allowed height of the text, in the current coordinate system.

void draw_surface(surface *p_surface, point2d anchor_point, double scale_factor = 1)

Draw a surface

Parameters:

  • surface – The surface (bitmap) to draw

  • anchor_point – The anchor_point point of the drawn surface The surface will be justified at this point accordinate to the current justification.

  • scale_factor – (optional) The scaling factor of the drawn surface. If specified, the width and height of the surface are each scaled by scale_factor.

~renderer()

Destructor.

Public Static Functions

static surface *load_png(const char *file_path)

load a png image into a bitmap surface

Parameters:

file_path – The path to the png image.

Returns:

a pointer to the created surface. This should later be freed using free_surface()

static void free_surface(surface *surface)

Free a surface

Parameters:

surface – The surface to destroy

Protected Types

using transform_fn = std::function<point2d(point2d)>

A callback for transforming points from one coordinate system to another.

Protected Functions

renderer(cairo_t *cairo, transform_fn transform, camera *m_camera, cairo_surface_t *m_surface)

Constructor.

Parameters:

  • cairo – The cairo graphics state.

  • transform – The function to use to transform points to cairo’s coordinate system.

void update_renderer(cairo_t *cairo, cairo_surface_t *m_surface)

Update the renderer when the cairo surface/context changes

Parameters:

  • cairo – The new cairo graphics state

  • m_surface – The new cairo surface

Private Functions

void draw_rectangle_path(point2d start, point2d end, bool fill_flag)
void draw_arc_path(point2d center, double radius, double start_angle, double extent_angle, double stretch_factor, bool fill_flag)
bool rectangle_off_screen(rectangle rect)

Private Members

t_coordinate_system current_coordinate_system = WORLD
cairo_t *m_cairo
transform_fn m_transform
camera *m_camera
double rotation_angle = 0
justification horiz_justification = justification::center
justification vert_justification = justification::center
int current_line_width = 0
line_cap current_line_cap = line_cap::butt
line_dash current_line_dash = line_dash::none
color current_color = {0, 0, 0, 255}

Friends

friend class canvas