Vgagames: Graphic box functions:
================================

 

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