Universiti Teknologi PETRONAS

Appendix D: Graphics Library

Introduction

This appendix describes gfx , a simple graphics library that gives the ability for C programmers
to draw or generate simple graphics. This library is meant to be a simple and easy set of
functions to be used so that programmers can delve directly into the interesting parts of
programming. The gfx library requires that the programmer understand how to invoke basic C
functions with scalar arguments.

This simplified library is sufficient to explore vector graphics, draw fractal shapes and simple
video games. Its capabilities would not cover all graphics functionality. If more advanced
graphics functionality is required, other libraries are available such as OpenGL for precise 3-D
graphics, Qt for windowed applications and SDL for video games.

This library runs on Linux machines using the X11 Window System where the necessary X11
libraries need to be installed using the following steps:

sudo apt-get libx11-dev

sudo apt-get install libx11-dev

If the previous installation steps were unsuccessful, the necessary libraries can be installed with
the following steps:

sudo apt-get update

sudo apt-get install autoconf
sudo apt-get install libssl-dev
sudo apt-get install libx11-dev
sudo apt-get install patch

1
Department of Electrical & Electronic Engineering

Getting started

Copy the following files and place them in a sub-directory of your choice:

gfx.c – this is the source file of the library, do not change the contents
gfx.h – this is the header file, do not change the contents
example.c – an example source file, changes are allowed in this file.

To compile the program that uses the gfx library, the following command has be used.

gcc example.c gfx.c –o example.o –lX11 –lm

This method of compilation compiles the example.c file together with gfx.c and the adds the
X11 and math libraries to generate an executable file of example.o .

The content of the example.c file is as follows :

#include <stdio.h>
#include "gfx.h" 1
int main()
{
int ysize = 300;
int xsize = 600; 2

char c;

// Open a new window for drawing.

gfx_open(xsize,ysize,"Example Graphics Program");

// Set the current drawing color to green.

gfx_color(0,255,0);
3
// Draw a triangle on the screen.
gfx_line(100,100,200,100);
gfx_line(200,100,150,150);
gfx_line(150,150,100,100); 4
while(1)
{
// Wait for the user to press a character.
c = gfx_wait();
printf("%c \n",c); 5
// Quit if it is the letter q.
if(c=='q') break;
}

return 0;
}

2
 Universiti Teknologi PETRONAS

Important highlights in the sample code:

1 - #include “gfx.h”

- Includes the functionality of the gfx library and its related functions.

2 - gfx_open (xsize, ysize, “Example Graphics Program”);

- This opens a graphics window at the beginning of the program, where the size of the
window in terms of width and height, are given in number of pixels. Also included is
the title or name of the window.

3 – gfx_color (0,255,0);
- This sets the current color of items to be drawn . For example, in this instance the
color set is green.

4 – gfx_line (100, 100, 200, 100);

- This function draws a line from location or coordinates (100, 100 ) to (200,100).

5 – gfx_wait();

- This line waits or halts the system while waiting for the appropriate input from user
either a keyboard entry or a mouse button response.
- Where in this instance, if the keyboard entry is the letter ‘q’ the program would then
exit from the loop and terminate the program.

3
Department of Electrical & Electronic Engineering

This is a list of available functions in gfx.c

Function void gfx_open(int width, int height, const char *title);

Description

This function creates a new graphics windows on the screen. Where the size of the
window is determined by width, which is the width of the window in pixels, and
height , is the height of the window in pixels. *title is the name of the
window in the title bar

Example gfx_open(800, 600, “Example Graphics Program”);

Function void gfx_line(int x1, int y1, int x2, int y2);
Description

This function draws a line from coordinate (x1,y1) to (x2,y2)

Example gfx_line(200,200,400,500);

4
 Universiti Teknologi PETRONAS

Function void gfx_color( int red, int green, int blue);

Description This function sets the current color for drawing. The color model uses the RGB color
model where all colors are a mixture of red, blue and green components. The valid
values for red, green and blue are between 0 and 255.
Example gfx_color(255,0,0); //red color
gfx_color(0,255,0) // green color
gfx_color(0,0,255) // blue color
gfx_color(255,255,0) // yellow color
gfx_color(255,255,255) // white color
gfx_color(100,100,100) // gray color
gfx_color(0,0,0) // black color

5
Department of Electrical & Electronic Engineering

Function void gfx_clear();

Description This is instruction clears the window to current background color which is black by
default.
Example gfx_clear();

Function void gfx_clear_color(int red, int green, int blue);

Description This instruction changes the background color. The new background color takes
effect the next time the gfx_clear() instruction is called.
Example gfx_clear_color(150,100,120);

6
 Universiti Teknologi PETRONAS

Function char gfx_wait();

Description This function waits until the user presses a key or a mouse button. If the mouse
button is pressed, an integer 1,2 or 3 is returned depending on the button pressed.
If a key is pressed, the key character is returned. This instruction causes the whole
program to pause until a key or button is pressed.
Example c= gfx_wait();

Function int gfx_event_waiting();

Description This function returns a TRUE condition if an event (key or button is pressed) has
occurred, otherwise it would return a FALSE. To capture the key or button pressed,
a gfx_wait has to be done immediately to capture the input value.
Example if (gfx_event_waiting())
c=gfx_waiting();

Function int gfx_xpos(); int gfx_ypos();

Description These functions return the X and Y positions respectively, of the mouse pointer.
Example xcoor= gfx_xpos(); ycoor=gfx_ypos();

Function void gfx_flush();

Description This instruction flushes all output to the graphics window or it forces all drawing
commands to take effect on the graphics window.

Function void gfx_point( int x, int y);

Description This instruction draws a pixel at coordinates (x,y)
Example gfx_point(100,100);

Function void gfx_rectangle (int x, int y, int width, int

height);
Description This function draws a rectangle with the top left corner of the rectangle at
coordinate (x,y). The dimensions of the rectangle are specified by the width and
height parameters.
Example gfx_color( 255,0,0);
gfx_rectangle(50,50,100,100);
gfx_color( 0, 255,0);
gfx_rectangle(200,100,150,50);
gfx_color( 0,0, 255);
gfx_rectangle(400,200,200,20);

7
Department of Electrical & Electronic Engineering

Function void gfx_circle (int x, int y , int radius);

Description This function draws a circle with the center of the circle designated by (x,y). The
radius of the circle is specified by the radius parameter.
Example gfx_color( 255,0,0);
gfx_circle(50,50,100);
gfx_color( 0, 255,0);
gfx_circle(200,100,200);
gfx_color( 0,0, 255);
gfx_circle(400,200,350);

8
 Universiti Teknologi PETRONAS

Function void gfx_fillrectangle (int x, int y, int width, int

height);
Description This function creates or fills a rectangle area where the top left corner of the
rectangle at coordinate (x,y). The dimensions of the rectangle are specified by the
width and height parameters.
Example
gfx_color( 255,0,0);
gfx_fillrectangle(50,50,100,100);
gfx_color( 0, 255,0);
gfx_fillrectangle(200,100,150,50);
gfx_color( 0,0, 255);
gfx_fillrectangle(400,200,200,20);

9
Department of Electrical & Electronic Engineering

Function void gfx_fillcircle ( int x, int y , int radius);

Description This function creates or fills a circle area with the center of the circle designated by
(x,y). The radius of the circle is specified by the radius parameter.
Example
gfx_color( 255,0,0);
gfx_circle(50,50,100);
gfx_color( 0, 255,0);
gfx_circle(200,100,200);
gfx_color( 0,0, 255);
gfx_circle(400,200,350);

10
 Universiti Teknologi PETRONAS

/* Program D1 */
#include <stdio.h>
#include "gfx.h"

int main()
{
int ysize = 300;
int xsize = 600;

char c;

// Open a new window for drawing.

gfx_open(xsize,ysize,"Example Graphics Program");

// Set the current drawing color to green.

gfx_color(0,255,0);

// Draw a triangle on the screen.

gfx_line(100,100,200,100);
gfx_line(200,100,150,150);
gfx_line(150,150,100,100);

while(1) {
// Wait for the user to press a character.
c = gfx_wait();
if(c=='q') break;
}

return 0;
}

Activity D1.

Load the editor with Program D1, compile it. Once the program is compiled and executed. Sketch
the output of the program.

11
Department of Electrical & Electronic Engineering

Exercise D1

Make modifications to Program D1 to be able to create a graphical output as follows :

List the modifications of the program

12
 Universiti Teknologi PETRONAS

Exercise D2

Using the gfx_point function, create a graphical display that attempts to display an image of
randomized points as illustrated as follows:

13
Department of Electrical & Electronic Engineering

Returning Data from Function / Getting Response from Mouse

Apart from drawing graphics, additional functionality is available which is listed as follows:

Function void gfx_wait();

Description

This function pauses the whole program and waits until the user presses a key or a
mouse button. If the user has pressed a mouse button, an integer 1, 2 or 3 will be
returned. If an integer value of 1 is returned, which indicates the left mouse button
was pressed. If 2 is returned, the middle button is pressed and if 3 is returned, the
right mouse button is pressed. If the user has pressed a key on the keyboard, the
character value is returned.

Example char c;
…
c=gfx_wait();

Function void gfx_event_waiting();

Description

This function functions differently compared to the gfx_wait(), which pauses the
whole program. This program allows the program to continuously run which
waiting for the user to respond using the keyboard or the mouse. This function
returns a TRUE event (when a key or mouse button is pressed) and a FALSE
immediately. If gfx_event_waiting(), returns a TRUE, a gfx_wait() is used
immediately to retrieve the event or data without waiting.

Example char c;
…
if (gfx_event_waiting())
{
c=gfx_wait();}

Function int gfx_xpos();

Description int gfx_ypos();

This function returns the X and Y coordinates of the mouse pointer when the last
key or mouse button was pressed.

Example char c;
…
if (gfx_event_waiting())
{ c=gfx_wait();
printf(“Coordinates %d %d \n”,gfx_xpos(),gfx_ypos());
}

14
 Universiti Teknologi PETRONAS

/* Program D2 */
#include <stdio.h>
#include "gfx.h"

int main()
{
int ysize = 300;
int xsize = 600;

char c;

// Open a new window for drawing.

gfx_open(xsize,ysize,"Example Graphics Program");

while(1) {
// Wait for the user to press a character.
c = gfx_wait();
if (c==0x01)
{
printf("1 - left button ");
}
else if (c==0x02)
{
printf("2 - middle button ");
}
else if (c==0x03)
{
printf("3 - right button ");
}
else
printf("%c \n",c);

printf("Mouse pos xpos is %d and ypos is %d \n", gfx_xpos(),gfx_ypos());

if(c=='q') break; // Quit if it is the letter q.

return 0;
}

Activity D2.

Load the editor with Program D2, compile it. Once the program is compiled and executed. Record
the output of the program while trying different mouse buttons until the ‘q’ key is pressed.

15
Department of Electrical & Electronic Engineering

Display Text

Apart from graphics, text can also be displayed on the graphics window using the following function:

Function void gfx_text( char *test, int x , int y);

Description

This function prints a text that stored in a string and displayed at location x , y .

Example char *teststring=”Test”;

…
gfx_text(test1, 400, 300); //displays text “Test” at
location (400,300)

//Program D3
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
//#include <string.h>
#include "gfx.h"

int main()
{
int r,g,b,x,y=0,flag=0,movex=2,movey=2;
int ysize = 600;
int xsize = 800;

char *test1="Test 1";

char test2[20]="Test STring 2";

char c;

srand(time(NULL));
// Open a new window for drawing.
gfx_open(xsize,ysize,"Example Text");

gfx_color(255,255,255); // white color

// Set the current drawing color to green.

for (x=5;x<800;x=x+10)
{
y=y+25;
if(y>=600 )
{
y=0;
}

gfx_text(test1, x,y);
gfx_flush();
usleep(250000);
gfx_flush();

}
}

16
 Universiti Teknologi PETRONAS

Activity D3.

Load the editor with Program D3, compile it. Once the program is compiled and executed. Record
the output of the program.

17