Overview -------- With these functions you are able to draw graphical figures. You can use the graphic box functions and drawing functions with graphics or with the backbuffer (window). The manipulating functions are only available for graphics. With all drawing and manipulating functions you may exceed the graphic boundaries without generating an error (e.g. copy a large graphic into a small one). The functions ------------- *** graphic box *** grafik * create_grafik(int arg1,int arg2): create an empty graphic box. This function is an alternative to load_grafik()/text_to_grafik(). Arguments: - arg1: width of the box in pixels - arg2: height of the box in pixels Return value: not NULL=allocated graphic NULL=error Example: grafik * gr1; // create graphic of width=20 and height=30 pixels gr1=create_grafik(20,30); if (gr1==NULL) { [...error...] } grafik * load_grafik(const char * arg1): load a graphic from a file, it is the same as create_grafik(), but with setting the graphic box with the pixel colors in the file. This function is an alternative to create_grafik()/text_to_grafik(). Arguments: - arg1: filename of the graphic file Return value: not NULL=loaded graphic NULL=error Note: To be a valid graphic file it must be - a ppm file format - a windows bitmap (.bmp) file (uncompressed format) - a vgagames graphic file A vgagames graphic file has following format: byte 1-2: "VG" byte 3-7: width of the graphic as text string byte 8-12: height of the graphic as text string byte 13-780: colormap of this graphic file (256 * 3 bytes: byte 1=red value \ byte 2=green value -} of one color byte 3=blue value / ) The values are from 0 to 63. byte 781-?: pixels of graphic box, each byte is an index to the colormap (0 = 1. color, 1 = 2. color, ..., 255 = 256. color) When loading a graphic from a file its colormap is compared against the actually loaded colormap to find for each pixel the best color which is actually available. The darkest color of the files colormap is used as transparent pixel (RGB_BLACK). The darkest pixel color next RGB_BLACK (RGB_DARK) can be used as a nearly black color without being transparent. (When drawing a graphic, you may define, that transparent pixels won't be put out; but you must not, then they will be put out). You can use the program "vgag-bitmap" to convert a windows bitmap file or a ppm graphic file into a vgagames graphic file or to get the colormap of the file. Example: grafik * gr1,* gr2; // load graphic from a windows bitmap file gr1=load_grafik("/path/mygraphic.bmp"); if (gr1==NULL) { [...error...] } // load graphic from a vgagames graphic file gr2=load_grafik("/path/background.vga"); if (gr2==NULL) { [...error...] } grafik * text_to_grafik(int arg1,int arg2,int arg3,int arg4,const char * arg5): create a graphic containing text. Newlines are used for line breaks. This function is an alternative to create_grafik()/load_grafik(). Arguments: - arg1: text color index - arg2: background color index - arg3: number of pixels between text lines - arg4: 0=text left adjusted 1=text centered 2=text right adjusted - arg5: text Return value: not NULL=created graphic with text NULL=error Note: The graphic box has just the size to contain the text. Each newline in the text is not printed but interpreted as a line break, the same with the string "\n". Example: grafik * grf; char buf[256]; strcpy(buf,"This is line 1\nAnd that is line 2"); // create a box with white text and black background, lines centered grf=text_to_grafik(RGB_WHITE,RGB_BLACK,2,1,buf); if (grf==NULL) { [...error...] } [ ... ] free_grafik(grf); int GRAFIK_WIDTH(grafik * arg1) int GRAFIK_HEIGHT(grafik * arg1): Macros to get width (GRAFIK_WIDTH()) and height (GRAFIK_HEIGHT()) of a graphic box Arguments: - arg1: graphic box or NULL=backbuffer Return value: width of graphic (GRAFIK_WIDTH()) or height of graphic (GRAFIK_HEIGHT()) Note: with arg1=NULL the width or height is always 320x200. Example: grafik * gr1; int w,h; if ((gr1=create_grafik(20,30))==NULL) { [...error...] } w=GRAFIK_WIDTH(gr1); // w=20 h=GRAFIK_HEIGHT(gr1); // h=30 [ ... ] w=GRAFIK_WIDTH(NULL); // w=320 (SC_WIDTH) h=GRAFIK_HEIGHT(NULL); // h=200 (SC_HEIGHT) void copy_grafik(grafik * arg1,int arg2,int arg3,grafik * arg4,int arg5,int arg6,int arg7,int arg8,int arg9): Copy a (part of a) graphic to another graphic in transparent mode or full mode. Arguments: - arg1: destination graphic box or NULL=backbuffer - arg2: position x at destination graphic - arg3: position y at destination graphic - arg4: source graphic box or NULL=backbuffer - arg5: position x at source graphic - arg6: position y at source graphic - arg7: width to copy at source graphic or 0=whole width of the graphic - arg8: height to copy at source graphic or 0=whole height of the graphic - arg9: RGB_FULL=copy as full graphic this means, all pixels are drawn RGB_TRANS=copy as transparent graphic, this means, all but transparent (=black) pixels (RGB_BLACK) are drawn, usefull if the graphic is put onto another graphic Example: grafik * gr1; int w,h; // load graphic if ((gr1=load_grafik("/path/mygraphic1.vga"))==NULL) { [...error...] } // put graphic to backbuffer at destination position 10,15 copy_graphic(NULL,10,15,gr1,0,0,0,0,RGB_FULL); // put graphic to backbuffer at destination position 10,15, but only // the half of width and height and begin at source position w/4,h/4 w=GRAFIK_WIDTH(gr1); h=GRAFIK_HEIGHT(gr1); copy_graphic(NULL,10,15,gr1,w/4,h/4,w/2,h/2,RGB_FULL); int save_grafik_as_ppm(grafik * arg1,const char * arg2) / int save_grafik_as_ppm3(grafik * arg1,const char * arg2): save graphic box as ppm file - e.g. for screenshot Arguments: - arg1: graphic box or NULL=backbuffer - arg2: filename to save graphic as ppm Return value: 0=OK -1=error Example: // screenshot save_grafik_as_ppm(NULL,"/mypath/mygraph.ppm"); /* save as "raw" P6 */ save_grafik_as_ppm3(NULL,"/mypath/mygraph.ppm"); /* save as "plain" P3 */ void free_grafik(grafik * arg1): Free a graphic, created with create_grafik() or load_grafik() and free memory. You cannot longer use this graphic. Arguments: - arg1: graphic box Example: grafik * gr1; if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } [ ... ] free_grafik(gr1); *** drawing *** (all functions use a color index to specify the color. The color index is a value from 0 to 255, representing a color value (r,g,b) of your actual colormap) void draw_pixel(grafik * arg1,int arg2,int arg3,int arg4): draw a pixel into a graphic box Arguments: - arg1: graphic box or NULL=backbuffer - arg2: destination x - arg3: destination y - arg4: color index or RGB_WHITE for white or RGB_BLACK for black or RGB_DARK for darkest pixel color next black Example: grafik * gr1; if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } // draw to graphic box at 0,0 with color index 238 draw_pixel(gr1,0,0,238); // draw to backbuffer (window) at 0,0 with color index 238 draw_pixel(NULL,0,0,238); void draw_line(grafik * arg1,int arg2,int arg3,int arg4,int arg5,int arg6): draw a line into a graphic box from arg2,arg3 to arg4,arg5 Arguments: - arg1: graphic box or NULL=backbuffer - arg2: begin destination x - arg3: begin destination y - arg4: end destination x - arg5: end destination y - arg6: color index or RGB_WHITE for white or RGB_BLACK for black or RGB_DARK for darkest pixel color next black Example: grafik * gr1; if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } // draw from 0,0 to 10,20 draw_line(gr1,0,0,10,20,238); /* color index 238 */ draw_line(NULL,0,0,10,20,238); /* color index 238 */ void draw_circle(grafik * arg1,int arg2,int arg3,int arg4,int arg5,int arg6): draw a circle into a graphic box centered at arg2,arg3 Arguments: - arg1: graphic box or NULL=backbuffer - arg2: middle of circle destination x - arg3: middle of circle destination y - arg4: radius in pixels - arg5: color index or RGB_WHITE for white or RGB_BLACK for black or RGB_DARK for darkest pixel color next black - arg6: 0=circle not filled 1=circle filled Example: grafik * gr1; if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } // draw middle at 100,100 with radius 20, not filled draw_circle(gr1,100,100,20,238,0); /* color index 238 */ draw_circle(NULL,100,100,20,238,0); /* color index 238 */ void draw_fillbox(grafik * arg1,int arg2,int arg3,int arg4,int arg5,int arg6): draw a filled rectangle into a graphic box Arguments: - arg1: graphic box or NULL=backbuffer - arg2: left upper corner destination x - arg3: left upper corner destination y - arg4: width of rectangle - arg5: height of rectangle - arg6: color index or RGB_WHITE for white or RGB_BLACK for black or RGB_DARK for darkest pixel color next black Example: grafik * gr1; if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } // draw filled rectangle from 0,0 to 9,9 draw_fillbox(gr1,0,0,10,10,238); /* color index 238 */ draw_fillbox(NULL,0,0,10,10,238); /* color index 238 */ void draw_text(grafik * arg1,int arg2,int arg3,int arg4,const char * arg5,int arg6,int arg7): draw text of the selected font (see set_font()) into a graphic box. The default font has 8x8 pixels per character, the font "font10x17" has 10x17 pixels per character, if you create your own fonts, each character may have up to 64x64 pixels. Arguments: - arg1: graphic box or NULL=backbuffer - arg2: color index or RGB_WHITE for white or RGB_BLACK for black or RGB_DARK for darkest pixel color next black - arg3: destination x of the first character left upper corner - arg4: destination y of the first character left upper corner - arg5: textstring - arg6: number of characters (string length of textstring) - arg7: RGB_FULL for full text or RGB_TRANS for transparent text Example: grafik * gr1; if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } // draw text from 0,0 // if it uses the default font, the "T" begins at 0,0 and ends at 7,7 // then the "e" begins at 8,0 and ends at 15,7 and so on draw_text(gr1,238,0,0,"Text",4,RGB_FULL); /* color index 238 */ draw_text(NULL,238,0,0,"Text",4,RGB_FULL); /* color index 238 */ void set_font(unsigned char * arg1,int arg2,int arg3): set font used by draw_text(). There are two fonts: - default font (8x8 pixels) - "font10x17" (10x17 pixels) but you may create your own fonts and include them into your game source file. Refer to file "font10x17.h". Arguments: - arg1: graphic box or NULL=backbuffer - arg2: width of font size - arg3: height of font size Example: set_font(NULL,0,0); // set default font (8x8 pixels) set_font(font10x17,10,17); // set font "font10x17" (10x17 pixels) int get_pixel(grafik * arg1,int arg2,int arg3): get pixel color index of one pixel from a graphic box. Arguments: - arg1: graphic box or NULL=backbuffer - arg2: destination x of the pixel coordinate - arg3: destination y of the pixel coordinate Return value: color index of pixel at arg2,arg3 Example: grafik * gr1; int color; if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } draw_line(gr1,0,0,10,20,238); // color index 238 color=get_pixel(gr1,0,0); // color=238 color=get_pixel(NULL,0,0); void CLEAR_BOX(grafik * arg1,int arg2): Macro to clear graphic box (fill it with pixels of color arg2) Arguments: - arg1: graphic box or NULL=backbuffer - arg2: color index, e.g. RGB_BLACK Example: grafik * gr1; if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } CLEAR_BOX(gr1,RGB_BLACK); CLEAR_BOX(NULL,RGB_BLACK); // clears backbuffer *** manipulating *** grafik * rotate_grafik(grafik * arg1,grafik * arg2,int arg3,int * arg4,int * arg5,int * arg6,int * arg7): rotate a graphic at certain degrees. Arguments: - arg1: destination graphic box In here the rotated source graphic is put. The size of the destination graphic is not very important: the rotated pixels will be put from the left upper corner (position 0,0); if it is too small, the rest is cut. - arg2: source graphic - arg3: degrees to rotate the source graphic clockwise (-360 to 360) - arg4: value argument and return argument: - value argument: x start position of source graphic to rotate - return argument: address for relative x coordinate to put destination graphic out: add the value of arg4 to your origin x coordinate - arg5: value argument and return argument: - value argument: y start position of source graphic to rotate - return argument: address for relative y coordinate to put destination graphic out: add the value of arg5 to your origin y coordinate - arg6: value argument and return argument: - value argument: width of source graphic to rotate or 0=whole width of source graphic - return argument: address for the rotated width in arg1 This is not the width of the box, but only the width of the rotated graphic in the box - arg7: value argument and return argument: - value argument: height of source graphic to rotate or 0=whole height of source graphic - return argument: address for the rotated height in arg1 This is not the height of the box, but only the height of the rotated graphic in the box Return value: pointer to arg1 or NULL=error Example: // put a graphic to window and rotate it at 90 degrees grafik * gr1,* gr2; int w,h,x,y; // load a graphic file if ((gr1=load_grafik("/path/mygraphic.vga",0))==NULL) { [...error...] } // get size of the graphic box w=GRAFIK_WIDTH(gr1); h=GRAFIK_HEIGHT(gr1); // create second graphic with largest size of the first graphic if ((gr2=create_grafik((w>h?w:h)+1,(h>w?h:w)+1))==NULL) { [...error...] } // put first graphic to backbuffer at 0,0 copy_grafik(NULL,0,0,gr1,0,0,0,0,RGB_FULL); flush_window(); CLEAR_BOX(NULL,RGB_BLACK); // rotate first graphic at 90 degrees clockwise // and put it into second graphic x=y=w=h=0; // set values: whole source graphic if (rotate_grafik(gr2,gr1,90,&x,&y,&w,&h)==NULL) { [...error...] } // put second graphic to backbuffer at 0,0 // but because the rotating could have changed the graphic coordinates // there are given back x and y to correct it and a new w and h, // so the graphic is rotated around its same middle copy_grafik(NULL,0+x,0+y,gr2,0,0,w,h,RGB_FULL); flush_window(); grafik * zoom_grafik(grafik * arg1,grafik * arg2,float arg3,float arg4,int * arg5,int * arg6,int * arg7,int * arg8): zoom a graphic greater or smaller Arguments: - arg1: destination graphic In here the zoomed source graphic is put. The size of the destination graphic is not very important: the zoomed pixels will be put from the left upper corner (position 0,0); if it is too small, the rest is cut. - arg2: source graphic - arg3: horizontal zooming factor (x direction), where 1.0 is original size - arg4: vertical zooming factor (y direction), where 1.0 is original size - arg5: value argument and return argument: - value argument: x start position of source graphic to zoom - return argument: address for relative x coordinate to put destination graphic out: add the value of arg5 to your origin x coordinate - arg6: value argument and return argument: - value argument: y start position of source graphic to zoom - return argument: address for relative y coordinate to put destination graphic out: add the value of arg6 to your origin y coordinate - arg7: value argument and return argument: - value argument: width of source graphic to zoom or 0=whole width of source graphic - return argument: address for the zoomed width in arg1 This is not the width of the box, but only the width of the zoomed graphic in the box - arg8: value argument and return argument: - value argument: height of source graphic to zoom or 0=whole height of source graphic - return argument: address for the zoomed height in arg1 This is not the height of the box, but only the height of the zoomed graphic in the box Return value: pointer to arg1 or NULL=error Example: // put a graphic to window and zoom it in x direction to a half grafik * gr1,* gr2; int w,h,x,y; // load a graphic file if ((gr1=load_grafik("/path/mygraphic.vga"))==NULL) { [...error...] } // get size of the graphic box w=GRAFIK_WIDTH(gr1); h=GRAFIK_HEIGHT(gr1); // create second graphic box with size of the graphic if ((gr2=create_grafik(w,h))==NULL) { [...error...] } // put first graphic to backbuffer at 0,0 copy_grafik(NULL,0,0,gr1,0,0,0,0,RGB_FULL); flush_window(); CLEAR_BOX(NULL,RGB_BLACK); // zoom first graphic half (x direction) and put it into second graphic x=y=w=h=0; // set values: whole source graphic if (zoom_grafik(gr2,gr1,.5,1.,&x,&y,&w,&h)==NULL) { [...error...] } // put second graphic to backbuffer at 0,0 // but because the zooming could have changed the graphic coordinates // there are given back x and y to correct it and a new w and h, // so the graphic is zoomed around its same middle copy_grafik(NULL,0+x,0+y,gr2,0,0,w,h,RGB_FULL); flush_window();
Home | Previous: Window functions | Next: Sprite functions