Vgagames: Initializing and ending functions:
============================================

 

Overview
--------

 - Before you use any of the vgagames functions you have to open
   a graphical screen with open_window(),
   the last call of a vgagames function should be close_window().

 - If you want to use any of the sound functions you have to start
   the sound server with init_sound();
   at last end the sound server with end_sound().

 - If you want to use tcp/ip network support you have to start
   the network server once with start_nettcp(),
   and to connect to it for each player with connect_nettcp().
   Disconnect from the network server with close_nettcp().



The functions
-------------

*** window ***


int open_window(const char * arg1,int arg2):
   switch to graphic mode in console graphic libraries, e.g. svgalib/libvgl
   or open a window in X window
   with 320x200 pixels for 256 colors.
   The width of the window is always SC_WIDTH = 320
   The height of the window is always SC_HEIGHT = 200

   Call this function as the first of any vgagames function.
   Close the window with close_window().

   For a better use of the graphical window there is created a
   backbuffer with the size of the window. All graphical output
   to the window is put to the backbuffer first, paying attention that
   pixels beyond the boundaries are not drawn. With flush_window() the
   backbuffer is copied to the window.
   So a graphic does not have to fit exactly into the window but may
   overlap at the window boundaries.

   Arguments:
    - arg1: for console graphic libraries: not important
            for X window: name of the window
    - arg2: for console graphic libraries: not important
            for X window: scaling factor
              The scaling factor is only important for X window.
              A window with 320x200 pixels could be very small,
              with the scaling factor you can enlarge it. This means not,
              that you had more pixels to address, but the size of one pixel
              is increased. You still have 320x200 pixels.
              There are following values:
                + 0: largest size for the actual screen
                + VGAWINDOW_1: original size (draws 1 pixel per pixel)
                + VGAWINDOW_2: scaling factor 2 (draws 4 pixel per pixel)
                + VGAWINDOW_3: scaling factor 3 (draws 9 pixel per pixel)
                + VGAWINDOW_FULL: full screen mode, can be added to
                                  the other values
                + VGAWINDOW_NOSWITCH: don't switch to another mode in X window,
                                      can be added to the other values
              A greater scaling factor slowers more down your game.
              When "WINDOW_RESIZABLE" is defined (#ifdef WINDOW_RESIZABLE),
              you can use arg2 to resize the window (currently only
              in X window).

   Return value: 0=ok
                 -1=error

   Note:  Using X window is not very recommended, because it slowers down
          your game.
          The first thing to make it faster is starting X window with
          256 colors:
            Use "startx -- -bpp 8" resp. "startx -- -depth 8"
          The second is to use a small scaling factor and a resolution
          of 640x480 or 800x600.
          If possible, vgagames tries to switch X window to a lower resolution,
          you may deny this with VGAWINDOW_NOSWITCH.

   Example:
     // X window: open window with scaling factor=1 and full screen
     // graphic library: open graphical screen
     if (open_window("MyWindow",VGAWINDOW_1+VGAWINDOW_FULL)==-1) {
       fprintf(stderr,"%s\n",errmsg);  // errmsg is the global error variable
       exit(1);
     }




void close_window():
   close graphic mode in console graphic libraries switching to text mode
   or closes the window in X window.
   Call this function as the last of any vgagames function.

   Example:
     close_window();



*** sound ***

(More about sound see Sound functions)


int init_sound(long arg1,int arg2):
   (This function you have to call only if you want to use sound)
   start sound server.
   Before exiting you must exit sound server with end_sound().

   Arguments:
    - arg1: samplefrequence to set
    - arg2: 0=set mono or 1=set stereo

   Return value: 0=ok
                 -1=error

   Note: the arguments samplefrequence and mono/stereo are values for
         initializing. Everytime you play a wave file these settings will
         be changed into the settings the wave file needs.
         Therefore it is important that all your wave files have the same
         settings (same samplefrequence, mono/stereo, 8 bit) to leave these
         settings unchanged.
         You should use only a samplefrequence of 11025 or 22050.
         All midi and mp3 files will use the actual settings.
         ==> Use for arg1 and arg2 the settings of your wave files.

   Note: in /usr/share/vgagames/wave.conf you can uncomment DEBUGFILE
         which will give out debug messages of the sound server to a file

   Example:
     if (init_sound(11025,0)==-1) {
       close_window();
       fprintf(stderr,"%s\n",errmsg);
       exit(1);
     }




void end_sound():
   stop playing any wave/midi/mp3 file and exit sound server

   Example:
     end_sound();



*** network ***

(More about network see Network functions)


int start_nettcp(int arg1,int arg2,unsigned short arg3):
   (This function you have to call only if you want to use multiplayer support)
   start tcp/ip network server for multiplayer game

   There must be one "master player", who has to start the network server.
   All other players only connect to it calling connect_nettcp(),
   including the master player.
   It is important that the master player first calls start_nettcp() before
   any other player tries to connect with connect_nettcp().

   The network server is waiting until all players are connected and
   will exit if 90 seconds are gone without any request of connection.
   When all players have been disconnected, the network server will exit.

   Arguments:
    - arg1: number of players (1 to 8)
    - arg2: number of virtual players included in arg1
    - arg3: portnumber listening to

   Return value: 0=ok
                 -1=error

   Note: The virtual players are players which are simulated by the master
         computer, but all clients think these are real players.
         In addition to the masters real player the master computer has to move
         the virtual players.
         The master computer also has to set all global player data
         (see connect_nettcp()).

   Example:
     int master,no_of_players,port;
     [ ... ]  // check whether you are master
     if (master) {
       puts("How many players? ");
       scanf("%d",&no_of_players);
       port=1235;
     }
     [ ... ]  // open window
     if (master) {
       // start server awaiting 'no_of_players' connections at port 1235
       // and without virtual players
       if (start_nettcp(no_of_players,0,port)==-1) { [...error...] }
     }




void * connect_nettcp(const char * arg1,unsigned short arg2, \
                         size_t arg3,int * arg4,int * arg5):
   (This function you have to call only if you want to use multiplayer support)
   Connect to network server started by master player calling start_nettcp(),
   and wait until all players are connected.

   Arguments:
     arg1: hostname or ip of network server
           or 'NULL'=get it via broadcast/multicast
     arg2: portnumber of network server
     arg3: size of data field (number of characters) (1 to 1024 valid)
     arg4: return address for player position
     arg5: return address for number of players

   Return value: address of network memory (network memory pointer)
                 or NULL=error

   Note: the network memory which connect_nettcp() returns contains information
         of every player. Each player may read all information of all players
         but write only his own information into it. With arg4 and arg5 the
         player is able to find his own data field in the network memory,
         e.g.: you set arg3 to 16 bytes and arg4 returns 2 and arg5 returns 5,
               then you are the second of 5 players, so your data field is
               at: 'network memory pointer' + 'arg3' * 'arg4'
               = 'network memory pointer'+32 bytes
               with a size of arg3 bytes (=16 bytes).

         For the master player the data fields which follow are the ones for
         the virtual players, if there are some, e.g.:
           the master player is the first player and there are 2 virtual
           players, then the data field of the master player is at:
             'network memory pointer' + 1 * 'arg4'
           and the data fields of the 2 virtual players are at:
             'network memory pointer' + 2 * 'arg4'
             'network memory pointer' + 3 * 'arg4'

         The first 'arg3' bytes are reserved for global player data
         (starting at 'network memory pointer').
         In these bytes you can exchange information not belonging to a
         certain player, e.g. for random events occuring. Only the master
         player can set these bytes.

         Your data field must contain only '(unsigned) char' values, because
         of the endian problem, don't use 'short/int/long' and don't use
         pointers.

         The first 'char' value in all data fields is reserved, it must be
         initialized to 1, which means that the player is connected;
         Therefore for each player and virtual player initialize it to 1
         at the beginning and set it to 0 if the (virtual) player is gone.
         When the real player disconnects, the byte is automatically set to 0;
         but when the master player disconnects, all still existing virtual
         players are disconnected too (and the global player data),
         therefore the master player has to be the last, who disconnects.

         For example a network with 5 bytes data field size (arg3=5)
         and 4 players with 1 virtual player would give following
         network memory:
           "ABCDE" "FGHIJ" "KLMNO" "PQRST" "UVWXY"
           where 'network memory pointer' points to "A",
           where global player data is from "A" to "E",
           where master player data field is from "F" to "J",
           where data field of the virtual player is from "K" to "O",
           where data field of player 1 or 2 is from "P" to "T",
           where data field of player 2 or 1 is from "U" to "Y".

   Example:
     void * pdata;  // address of network memory
     unsigned short port=1235;  // port
     int playerpos,no_of_players;

     char * nda;  // pointer for data field of each player
     const int ndalen=16;  // size of each data field

     [ ... ]
     // connect via broadcast/multicast
     pdata=connect_nettcp(NULL,port,ndalen,&playerpos,&no_of_players);
     if (pdata==NULL) { [...error...] }




void close_nettcp():
   disconnect player from network server

   Example:
     close_nettcp();


 

Home | Previous: General terms and compiling | Next: Window functions