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