libgraph --- Implementing Turbo C's graphics on GNU/Linux

<<Previous
Next>>
Introduction & Usage
Developer Section


 List of Functions & Enumerations


This section contains the graphics related functions of this library i.e. those that are normally defined in graphics.h

initgraph closegraph detectgraph
setgraphmode getgraphmode restorecrtmode
getmaxx getmaxy cleardevice
putpixel getpixel setcolor
setbkcolor getbkcolor getcolor
moveto getx gety
moverel setfontcolor getfontcolor
line lineto linerel
circle arc pieslice
rectangle drawpoly fillpoly
ellipse fillellipse floodfill
bar bar3d getmaxcolor
outtext outtextxy getmaxmode
getdrivername getmodename getmoderange
getarccoords sector textheight
textwidth


to function list...
NAME : initgraph, closegraph

SYNOPSIS :

void initgraph( int *graphdriver, int *graphmode, char *pathtodriver );
void closegraph( void );

DESCRIPTION :

The function initgraph is called to start the graphics mode i.e. open the graphics drawing window. All functions operate within this window. initgraph *MUST* be called before drawing functions are called.

The arguments graphdriver and graphmode are the driver and mode values given in the Constants section below. The last argument path to driver is provided only for compatibility with TC and is ignored by initgraph. It may be NULL or any random string. It does not make any difference.

closegraph( ) is used to shutdown the graphics system and close the graphics window. Once it is called the graphics window will have to be reopened with another call to initgraph if needed. Closegraph is called by default when your program quits but it is better to call it explicitly before main returns.

initgraph returns the graphics mode initialized in graphmode.

Note: For user-specified modes and sizes see this.

Example:

int gd=DETECT, gm=VGAMAX;
initgraph(&gd, &gm, 0);
......    /*Call to various drawing functions.*/
closegraph();

RETURN VALUE : None


to function list...
NAME :detectgraph

SYNOPSIS :

void detectgraph(int *graphdriver, int *graphmode);

DESCRIPTION :

detectgraph initializes the graphics system to the highest mode available. The mode selected is returned in graphmode.

RETURN VALUE : None


to function list...
NAME : setgraphmode, getgraphmode

SYNOPSIS :

void setgraphmode(int mode);
int getgraphmode(void);

DESCRIPTION :

getgraphmode returns the current graphics mode. Your program must make a successful call to initgraph or setgraphmode BEFORE calling getgraphmode.

setgraphmode selects a graphics mode different than the default one set by initgraph. It clears the screen and resets all graphics settings to their defaults. mode must be a valid mode for the current device driver.

The enumeration graphics_modes, defined in GRAPHICS.H, gives names for the predefined graphics modes.

You can use setgraphmode in conjunction with restorecrtmode to switch back and forth between text and graphics modes.

RETURN VALUE :

getgraphmode returns the graphics mode set by initgraph or setgraphmode.
setgraphmode does not return.


to function list...
NAME : restorecrtmode

SYNOPSIS :

void restorecrtmode ( void );

DESCRIPTION :

restorecrtmode shuts down the graphics window. Unlike the original implementation the action of restorecrtmode( ) here is equivalent to closegraph( ) and the two can be used interchangeably.

RETURN VALUE : None


to function list...
NAME : getmaxx, getmaxy

SYNOPSIS :

int getmaxx( void );
int getmaxy( void );

DESCRIPTION :

getmaxx returns the maximum x value (screen-relative) for the current graphics driver and mode.

getmaxy returns the maximum y value (screen-relative) for the current graphics driver and mode.

For example, on VGA800 (800x600) mode, getmaxx returns 799 and getmaxy returns 599.

RETURN VALUE :

getmaxx: maximum x screen coordinate
getmaxy: maximum y screen coordinate


to function list...
NAME : cleardevice

SYNOPSIS :

void cleardevice( void );

DESCRIPTION :

cleardevice erases the entire graphics screen and moves the current position as given by (getx( ), gety( )) to (0,0). This function is the graphics equivalent of clear or clrscr.

(Erasing consists of filling with the current background color.)

RETURN VALUE : None


to function list...
NAME : putpixel, getpixel

SYNOPSIS :

int getpixel( int x, int y );
void putpixel( int x, int y, int color );

DESCRIPTION :

getpixel gets the color of the pixel located at (x,y).

putpixel plots a point in the color defined by color in graphics.h at (x,y).

RETURN VALUE :

getpixel returns the color of the given pixel
putpixel does not return


to function list...
NAME : setcolor, getcolor

SYNOPSIS :

void setcolor( int color );
int getcolor( void );

DESCRIPTION :

getcolor returns the current drawing color.

setcolor sets the current drawing color to color, which can range from 0 to getmaxcolor.

To select a drawing color with setcolor, you can pass either the color number or the equivalent color name.

The drawing color is the value that pixels are set to when the program draws lines, etc.

Example :

setcolor(RED);
line(0, 0, getmaxx( ), getmaxy( ));

Note : The default drawing color is WHITE.

RETURN VALUE :

getcolor returns the current drawing color.
setcolor does not return


to function list...
NAME : setbkcolor, getbkcolor

SYNOPSIS :

void setbkcolor( int color );
int getbkcolor( void );

DESCRIPTION :

getbkcolor returns the current background color.

setbkcolor sets the background to the color specified by color.

color is either a number or symbolic name specifying the color to set.

Example :

setbkcolor(BLUE);

Note : The default background color is BLACK.

RETURN VALUE :

getbkcolor returns the current background color.
setbkcolor does not return.


to function list...
NAME :getx, gety

SYNOPSIS :

int getx( void );
int gety( void );

DESCRIPTION :

getx returns the x-coordinate of the current graphics position(CP).

gety returns the y-coordinate of the current graphics position(CP).

RETURN VALUE :

getx: x-coordinate of current position
gety: y-coordinate of current position


to function list...
NAME : moveto, moverel

SYNOPSIS :

void moveto( int x, int y );
void moverel( int dx, int dy );

DESCRIPTION :

moveto moves the current position CP to viewport position (x, y).

moverel moves the current position CP dx pixels in the x direction and dy pixels in the y direction.

RETURN VALUE : None


to function list...
NAME : setfontcolor, getfontcolor

SYNOPSIS :

void setfontcolor( int color );
int getfontcolor( void );

DESCRIPTION :

setfontcolor sets the current font color to color.

getfontcolor gets the current font drawing color.

These functions are libgraph extensions, i.e. they are not available in the original graphics.h. They affect all text written on the graphics window wether by outtext or by printf.

Note : The default fontcolor is WHITE.

RETURN VALUE :

getfontcolor returns the current font-color.
setfontcolor does not return.


to function list...
NAME :line, lineto, linerel

SYNOPSIS :

void line( int x1, int y1, int x2, int y2 );
void lineto( int x, int y);
void linerel( int dx, int dy );

DESCRIPTION :

line draws a line from (x1, y1) to (x2, y2) using the current color. It does not update the current position (CP).

lineto draws a line from the CP to (x, y), then moves the CP to (x, y).

linerel draws a line from the CP to a point that is a relative distance (dx, dy) from the CP, then advances the CP by (dx, dy).

RETURN VALUE : None


to function list...
NAME : circle

SYNOPSIS :

void circle( int x, int y, int rad );

DESCRIPTION :

circle draws a circle in the current drawing color using ( x, y ) as center and rad as radius.

RETURN VALUE : None


to function list...
NAME : arc, pieslice

SYNOPSIS :

void arc( int x, int y, int stangle, int endangle, int radius );
void pieslice( int x, int y, int stangle, int endangle, int radius );

DESCRIPTION :

arc draws a circular arc using the current drawing color.
* See also getarccoords.

pieslice draws and fills a pie-slice in the current drawing color.

Arguments :

(x, y) -- Center point of arc or pieslice.
stangle -- start angle in degrees(as measured on the standard circle).
endangle -- end angle in degrees(as measured on the standard circle).
radius -- radius of arc or pieslice.

The arc or pieslice travels from stangle to endangle. If stangle = 0 and endangle = 360 the call to arc or pieslice draws a complete circle.

RETURN VALUE : None


to function list...
NAME : rectangle

SYNOPSIS :

void rectangle( int left, int top, int right, int bottom );

DESCRIPTION :

rectangle draws a rectangle in the current drawing color.

(left,top) is the upper left corner of the rectangle, and (right,bottom) is its lower right corner.

RETURN VALUE : None


to function list...
NAME : drawpoly, fillpoly

SYNOPSIS :

void drawpoly( int numpoints, int *polypoints );
void fillpoly( int numpoints, int *polypoints );

DESCRIPTION :

drawpoly draws a polygon using the current drawing color.

fillpoly draws the outline of a polygon using the current color, then fills the polygon using the current color.

Arguments :

numpoints -- Specifies number of points
*polypoints -- Points to a sequence of (numpoints x 2) integers Each pair of integers gives the x and y coordinates of a point on the polygon.

To draw a closed figure with N vertices, you must pass N+1 coordinates to drawpoly, where the Nth coordinate == the 0th coordinate.

RETURN VALUE : None


to function list...
NAME : ellipse

SYNOPSIS :

ellipse( int x, int y, int stangle, int endangle, int xradius, int yradius );

DESCRIPTION :

ellipse draws an elliptical arc in the current drawing color.

Arguments :

(x,y) -- Center of ellipse
xradius -- Horizontal axis
yradius -- Vertical axis
stangle -- Starting angle
endangle -- Ending angle

The ellipse travels from stangle to endangle. If stangle = 0 and endangle = 360, the call to ellipse draws a complete ellipse.

RETURN VALUE : None


to function list...
NAME : fillellipse, sector

SYNOPSIS :

void fillellipse( int x, int y, int xradius, int yradius );
void sector(int x, int y, int stangle, int endangle, int xradius, int yradius);

DESCRIPTION :

fillellipse draws an ellipse, then fills the ellipse with the current fill color.

sector draws an elliptical pie slice in the current drawing color, then fills it using the color.

Arguments :

(x,y) -- Center of ellipse
xradius -- Horizontal axis
yradius -- Vertical axis
stangle -- Starting angle
endangle -- Ending angle

The sector travels from stangle to endangle. If stangle = 0 and endangle = 360, the call to sector draws a complete filled ellipse similar to fillellipse.

RETURN VALUE : None


to function list...
NAME : floodfill

SYNOPSIS :

void floodfill( int x, int y, int boundarycolor );

DESCRIPTION :

floodfill fills an enclosed area on bitmap devices.

The area bounded by the color border is flooded with the current fill color.

(x,y) is a "seed point".
If the seed is within an enclosed area, the inside will be filled.
If the seed is outside the enclosed area, the exterior will be filled.

Note : fillpoly is recommended over floodfill whenever possible for perfomance reasons.

RETURN VALUE : None


to function list...
NAME :bar

SYNOPSIS :

void bar( int left, int top, int right, int bottom );

DESCRIPTION :

bar draws a filled-in, rectangular, two-dimensional bar.

The bar is filled using the current fill color.

(left,top) is the upper left corner of the bar, and (right,bottom) is its lower right corner.

RETURN VALUE : None


to function list...
NAME :bar3d

SYNOPSIS :

void bar3d( int left, int top, int right, int bottom, int depth, int topflag );

DESCRIPTION :

bar3d draws a three-dimensional rectangular bar, then fills it using the current fill color.

Arguments :

depth -- Bar's depth in pixels
topflag -- top is put on the bar(3d-dimensional)
(left, top) -- Rectangle's upper left corner
(right, bottom) -- Rectangle's lower right corner

RETURN VALUE : None


to function list...
NAME : getmaxcolor

SYNOPSIS :

int getmaxcolor( void );

DESCRIPTION :

getmaxcolor returns the highest valid color value that can be passed to setcolor for the current graphics driver and mode.

In the current implementation of libgraph this function always returns 15.

RETURN VALUE :

Returns the highest available color value.


to function list...
NAME :outtext, outtextxy

SYNOPSIS :

void outtext( char *textstring );
void outtextxy( int x, int y, char *textstring );

DESCRIPTION :

outtext and outtextxy display a text string, using the current font-color.

outtext outputs textstring at the current position (CP) and updates this position by the length of the text.

outtexxy displays textstring in the viewport at the position (x, y) and does not affect CP.

If a string is printed with the default font using outtext or outtextxy, any part of the string that extends outside the current viewport is automatically wrapped around. If the text scrolls off the page the function waits for a spacebar key before scrolling to the new page.

The scrolling action can be avoided by using textheight/textwidth for precise placement of the text string.

outtext and outtextxy are for use in graphics mode; they will not work in text mode.

RETURN VALUE : None


to function list...
NAME :getmaxmode, getmoderange

SYNOPSIS :

int getmaxmode( void );
void getmoderange( int graphdriver, int *lomode, int *himode );

DESCRIPTION :

getmaxmode lets you find out the maximum mode number for the currently loaded driver, directly from the driver.

The minimum mode is 0. In the current implementation of libgraph this function always returns VGA1024.

getmoderange gets the range of valid graphics modes for the given graphics driver.

Arguments :

graphdriver -- If graphdriver = -1, getmoderange gets the currently loaded driver modes. If graphdriver specifies an invalid graphics driver, both *lomode and *himode are set to -1.
lomode -- Points to location where lowest permissible mode value is returned.
himode -- Points to location where highest permissible mode value is returned.

RETURN VALUE :

getmaxmode returns the maximum mode number for the current driver.
getmoderange does not return.


to function list...
NAME :getdrivername, getmodename

SYNOPSIS :

char *getdrivername( void );
char *getmodename( int mode_number );

DESCRIPTION :

After a call to initgraph, getdrivername returns the name of the driver that is currently loaded.

getmodename accepts a graphics mode number as input and returns a string containing the name of the corresponding graphics mode.

The return values are useful for building menus or displaying status. The space required to store the string is malloced and should be freed when not required.

RETURN VALUE :

getdrivername returns a pointer to a string with the name of the currently loaded graphics driver.
getmodename returns a pointer to a string contining the name of the graphics mode.


to function list...
NAME :getarccoords

SYNOPSIS :

void getarccoords( struct arccoordstype *arccoords );

DESCRIPTION :

getarccoords puts information about the last call to arc in the arccoordstype structure *arccoords.

Arguments :
The arccoordstype structure is defined as follows :

struct arccoordstype {
int x, y; /* center point of arc*/
int xstart, ystart; /* start position */
int xend, yend; /* end position */
};

These values are useful if you need to make a line meet the end of an arc.

RETURN VALUE : None


to function list...
NAME :textheight, textwidth

SYNOPSIS :

int textheight ( char *textstring );
int textwidth ( char *textstring );

DESCRIPTION :

textheight returns the height in pixels of the text according to the size of the font loaded currently.

textwidth returns the width in pixels of the given text according to the size of the font currently loaded.

These functions are useful for line-spacing and precision placement of text while using functions like outtextxy. Since we are currently using only one font the size returned by textheight is fixed while that of textwidth is actually calculated for the given string.

NOTE: textwidth adds 5 to the actual value for good measure to prevent overlap or accidental scrolling off the current line.

RETURN VALUE :

textheight returns the height in pixels of the given text string.
textwidth returns the width in pixels of the given text string.



to function list...
NAME :

SYNOPSIS :

DESCRIPTION :

RETURN VALUE :



** Note : (for dummies) You are supposed to use the Constants field while passing to funtions. So you don't need to remember the values.

VGA Drivers :
Constants Values Remarks
DETECT 0 Autodetect -- defaults to VGA 640x480x8
USER 1 User specified modes *libgraph Extension* more ...
VGA 9 This is the default and only driver available
(2 rows)

VGA Modes :

Constants Values Resolution BPP Remarks
VGALO 0 640x200 8 windowed
VGAMED 1 640x350 8 windowed
VGAHI 2 640x480 8 windowed
VGAMAX 3 800 x600 8 windowed
VGA640 4 640x480 8 fullscreen*
VGA800 5 800x600 8 fullscreen*
VGA1024 6 1024x768 8 fullscreen*
USERMODE 7 User specified@ 8 windowed
(7 rows)

# NOTE: 800x600, 1024x768, User-specified are special extension not provided in TC.

* NOTE: The fullscreen modes may cause virtual resolution in X if the mode selected does not match your X-resolution. This is seen specifically when the VESA driver for XFree86 4.x is used. If this is not the case with you, use them by all means. Also note that you cannot kill( or xkill ) your application while in fullscreen modes. You have to rely on CTRL-C to come out of infinite loops.

@ NOTE: For user-specified modes use driver=USER and a 6 digit integer (3-digits: x-resolution + 3-digits: y-resolution) for mode.
example: gd = USER, gm = 500300; /* 500 x 300 mode */

Colors :(defined in graphics.h)

The same color constants are used for setfgcolor, setbkcolor and setfontcolor

constant value foreground background fontcolor
BLACK 0 Yes Yes Yes
BLUE 1 Yes Yes Yes
GREEN 2 Yes Yes Yes
CYAN 3 Yes Yes Yes
RED 4 Yes Yes Yes
MAGENTA 5 Yes Yes Yes
BROWN 6 Yes Yes Yes
LIGHTGRAY 7 Yes Yes Yes
DARKGRAY 8 Yes Yes Yes
LIGHTBLUE 9 Yes Yes Yes
LIGHTGREEN 10 Yes Yes Yes
LIGHTCYAN 11 Yes Yes Yes
LIGHTRED 12 Yes Yes Yes
LIGHTMAGENTA 13 Yes Yes Yes
YELLOW 14 Yes Yes Yes
WHITE 15 Yes Yes Yes
(16 rows)


These functions are not directly related to graphics but are generally used in Turbo C while doing graphics related programming.

Functions like getch, delay(millisec), and kbhit are useful even otherwise and can be used in normal text mode. Even if you are not doing graphics programming you can use them just by including graphics.h and linking with libgraph.

kbhit getch getche
delay printf("", ...) scanf("", ...)
getchar putchar gets

to function list...
NAME : kbhit

SYNOPSIS :

int kbhit(void);

DESCRIPTION :

kbhit checks to see if a keystroke is currently available.

Any available keystroke can be retrieved using getchar or getch.

Example:
while(!kbhit())
{
.....
.....
.....
}

Note: In text mode use getchar (not getch) to use retrieve the keystroke since getch flushes the input buffer before reading.

RETURN VALUE :
On success (if a keystroke is available) it returns the keystroke.
If a keystroke is not available it returns 0.


to function list...
NAME : getch, getche

SYNOPSIS :

int getch(void);
int getche(void);

DESCRIPTION :

getch gets a character from console, and does not echo it to the screen.

getche gets a character from console, and echoes it to the screen.

RETURN VALUE :
Both functions return the character read from the keyboard.


to function list...
NAME : delay

SYNOPSIS :

int delay(float milliseconds);

DESCRIPTION :

This function provides accurate time delays using the nanosleep function to give sub-millisecond granularity. Hence the milliseconds argument is a float and not an int.

RETURN VALUE :
Number of milliseconds delayed (truncated).


to function list...
NAME : printf, scanf

SYNOPSIS :

int printf(const char *format, ...);
int scanf(const char *format, ...);

DESCRIPTION :

These are the normal scanf, printf functions hacked to work in graphics mode (i.e. in the libgraph window).

Remember that no other input-output functions save those listed here(namely printf, scanf, getch, getchar, putchar, ...) will work in graphics mode. All other functions act on the stdin, stdout which is the console from where you are running this program.

NOTE: In graphics mode scanf has a maximum input-buffer of 256 characters ( as set by the SCAN_BUF constant in grtext.h ) and cannot perform more than 10 %-conversions in a single call.

NOTE: If you enter invalid input (namely characters where numbers are expected) scanf will go into an infinite loop. You must use Control-C to quit the program and try-again ( the program would have seg-faulted anyway ).

RETURN VALUE :
Same as normal printf, scanf.


to function list...
NAME : getchar, putchar

SYNOPSIS :

int getchar(void);
int putchar(int character);

DESCRIPTION :
These are the normal getchar, putchar functions hacked to work in graphics mode (i.e. in the libgraph window).

Remember that no other input-output functions save those listed here(namely printf, scanf, getch, getchar, putchar, ...) will work in graphics mode. All other functions act on the stdin, stdout which is the console from where you are running the program.

RETURN VALUE :
Same as normal getchar, putchar.


to function list...
NAME : gets

SYNOPSIS :

**************************

DESCRIPTION :

gets() function is *NOT* provided in this library. This entry is a WARNING and REMINDER to people not to use gets. People migrating from Windows, DOS tend to use this function frequently.

For more on why not to use gets type "man gets" at the console and read the BUGS section.

RETURN VALUE :
segmentation fault, program crash


to function list...
NAME :

SYNOPSIS :

DESCRIPTION :

RETURN VALUE :



<<Previous <Home> Next>>
Introduction & Usage Top Developer Section