***************************************************************************** EXTERNAL FUNCTIONS ***************************************************************************** All the functions described here are just examples of how to have VPE working on a particular system. You may choose to use these functions, you may throw them away. You can do whatever you like with any function unless it is said that the function is called from VPE. In that case you have to have this function. ************************************ Memory functions (called by VPE) ************************************ These functions are used by VPE to allocate and free memory. Usually they just use standard malloc/free functions. But you can put calls to your heap-manager in here. ============================================================================= void *MemAlloc(long int Size); ----------------------------------------------------------------------------- Description: Allocates memory Parameters: Size - Number of bytes to allocate Return: Ptr to the allocated buffer. NULL otherwise. ============================================================================= ============================================================================= void *MemZAlloc(long int Size); ----------------------------------------------------------------------------- Description: Allocates memory and zeroes it Parameters: Size - Number of bytes to allocate and clear Return: Ptr to the allocated and cleared buffer. NULL otherwise. ============================================================================= ============================================================================= void MemFree(void *Ptr); ----------------------------------------------------------------------------- Description: Frees previaously allocated memory Parameters: Ptr - Pointer to the buffer to free Return: None ============================================================================= ************************************* File IO functions (called by VPE) ************************************* These functions are used by VPE loaders and can be customized eg to allow loading from a resource file. BUT they must have the same names and calling conventions as described below. Note that VPE reads only once from a file. For example LoadZone() reads the whole zone file into a buffer and then processes it. ============================================================================= long int FileSize(char *Name); ----------------------------------------------------------------------------- Description: Get filesize in bytes Parameters: Name - Name of the file to check Return: Size of the file in bytes (<=0 - Error) ============================================================================= ============================================================================= long int FileRead(char *Name, long int Start, long int Length, void *Buffer); ----------------------------------------------------------------------------- Description: Reads part of the file into memory Parameters: Name - File name Start - Position to start reading from Length - Bytes to read Buffer - Data buffer Return: Number of bytes read (<=0 - Error) ============================================================================= ********************** Graphics Functions ********************** If you want VPE to render something to the output device you have to provide the following functions. SetPalette(), DrawBuffer(), DrawSceen() MUST have the form and name described below. If your application supports several output devices (eg VGA and SVGA) you can have a simple switch/case statement in the routines to handle all the cases at run-time. ============================================================================= void InitGraph(void); ----------------------------------------------------------------------------- Description: Initialize gfx system. Parameters: None Return: None ============================================================================= ============================================================================= void ShutGraph(void); ----------------------------------------------------------------------------- Description: Shuts down the gfx system Parameters: None Return: None ============================================================================= ============================================================================= int GetGraphWidth(void); ----------------------------------------------------------------------------- Description: Get width of the output device Parameters: None Return: Width of the output device ============================================================================= ============================================================================= int GetGraphHeight(void); ----------------------------------------------------------------------------- Description: Get height of the output device Parameters: None Return: Height of the output device ============================================================================= ============================================================================= void SetPalette(BYTE *PalBuffer); ----------------------------------------------------------------------------- Description: Set palette for the output device. Called from inside VPE. Parameters: PalBuffer - Palette data Return: None ============================================================================= ============================================================================= void DrawBuffer(struct View *pView); ----------------------------------------------------------------------------- Description: Blits view buffer to the output device. Called from inside the engine. Parameters: pView - pointer to View to blit Return: None ============================================================================= ============================================================================= void DrawScreen(void); ----------------------------------------------------------------------------- Description: Fills the screen with background color/picture before the rendering. It also called when a View is resized. Called from inside VPE. Parameters: None Return: None ============================================================================= *************************************** Input Functions (called externally) *************************************** The input system provides all the input. You are free to rename all the functions, change their looks etc. VPE does not call any of them. ============================================================================= void InitInput(void); ----------------------------------------------------------------------------- Description: Initialize input system. Parameters: None Return: None ============================================================================= ============================================================================= void ConfigInput(int Width, int Height, int TX, int TY); ----------------------------------------------------------------------------- Description: Configure the input system Parameters: Width - Output device width (for mouse) Height - Output device height (for mouse) TX - Mouse threshold along X axis TY - Mouse threshold along Y-axis Return: None ============================================================================= ============================================================================= void ShutInput(void); ----------------------------------------------------------------------------- Description: Shuts the input system Parameters: None Return: None ============================================================================= ============================================================================= void GetInput(void); ----------------------------------------------------------------------------- Description: Processes all the input received from the input system. Here you specify how to react to the input. Parameters: None Return: None ============================================================================= ******************* Timer Functions ******************* The timer functions are important. They help VPE to keep track of the time. So that all speed calculations are time dependent (units per second) instead of being frame dependent (units per frame). The engine can work with any timer function. There are two things to remember: First you must tell VPE at what rate the timer operates (VPE_SetRate()). And second ReadTimer() must have the same form as described below. These functions are just an example. You can throw them away and use something else. ============================================================================= void InitTimer(int Rate); ----------------------------------------------------------------------------- Description: Initialize timer system. Do not forget to call VPE_SetRate() to set the same rate (Rate)! Parameters: Rate - At what rate the internal counter operates. Return: None ============================================================================= ============================================================================= void ShutTimer(void); ----------------------------------------------------------------------------- Description: Shut down timer system Parameters: None Return: None ============================================================================= ============================================================================= unsigned long ReadTimer(void); ----------------------------------------------------------------------------- Description: This function returns number of ticks elapsed since InitTimer(). It is called from inside VPE. Parameters: None Return: Current value of internal Counter ============================================================================= ************************************************* Optional: Sound Functions (called externally) ************************************************* Sound support is not an integral part of VPE. These functions are basicly a wrapper for a sound library. This is just a basic set, you can create more. The easiest way to add sound effects at right places is to call PlaySound() from your Effects (for info about them look at other docs). PlaySong() can be called from somewhere in the main loop. Or you can have different songs assigned to different Regions. If player walks over a Region with a special effect a new music will start to play. ============================================================================= void InitSound(void); ----------------------------------------------------------------------------- Description: Initialize sound system Parameters: None Return: None ============================================================================= ============================================================================= void ShutSound(void); ----------------------------------------------------------------------------- Description: Shut down sound system Parameters: None Return: None ============================================================================= ============================================================================= void PlaySong(int Song, int Volume); ----------------------------------------------------------------------------- Description: Start playing music Parameters: Song - Music filename id Volume - Music volume (0-255) Return: None ============================================================================= ============================================================================= int PlaySound(int Sound, int Volume); ----------------------------------------------------------------------------- Description: Plays sound effect Parameters: Sound - Sound filename id Volume - Sound effect volume (0-255) Return: Channel (-1 - sound is not playing) ============================================================================= ============================================================================= int PlaySound3D(int Sound, FIXED x, FIXED y); ----------------------------------------------------------------------------- Description: Plays 3D sound effect. Volume is determined by the distance to the sound source. Panning - by direction to the source. Parameters: Sound - Sound filename id x,y - Sound source's coordinates in VPE zone. Return: Channel (-1 - sound is not playing) ============================================================================= ********************************************************* Optional: Network/modem functions (called externally) ********************************************************* TO BE ADDED LATER