Porting viDOOM

This document is provided in case anyone wishes to port viDOOM to a new platform. Below is an indication of what OS dependent routines must be provided and what configuration needs to be done. It is requested that any ports are also released as Free Software.

• Makefile configuration
• INI File
• Files
• Main entry point
• Graphics and input
• Platform GUI
• File interface
• Memory allocation
• External command execution
• String functions
• Installation script
• Documentation

Makefile configuration

makefile

Set the variable MAKEPLAT to the name of your platform, eg.

MAKEPLAT=OS

You will then need to create a matching file the make sub directory called OS.cfg. Also all the OS dependent C source should go into a sub directory defined in the following make config file by the PLATFORM variable. See the Files section for an overview of these files.

make config file

The following values need to be set in the file make/OS.cfg:

INI File

If your port requires or wants configuration to be set at tun-time from the INI file, it is best to place it a system-dependent section called the same as the OS value you set MAKEPLAT to for this platform, e.g.

[OS]
degreelessness mode=off

Files

The following files are the minimum that must be provided by the platform:

Main entry point

main.c

The OS dependent code must provide it's own main (this is to allow for various non-standard environments where main() is not the standard entry point). The entry point must do any OS dependent initialisations then invoke the following entry point to start up viDOOM:

int viDOOM(int argv, char *argv[])

If the OS uses main() as an entry point the following example could be enough:

int main(int argc,char *argv[])
{
    return (viDOOM(argc,argv));
}

Graphics and input

gfx.c

This provides the low-level graphics access and interfaces to keyboard and mouse. The GFX object is expected to work on a weak, semi-event driven basis for keyboard/mouse access. The following are the basic assumptions about the GFX interface:

• A true, or hicolor, display.
• A Fixed font.
• Default origin is in the top left of the display, with X positive along and Y positive down.
• A buffered display. The screen contents should not change until GFX_redraw() is called. If not honoured viDOOM should still work up to a point, but it's use of the XOR mode may not be apparent to the user.
• Colours are represented using an int, with 8 bits each for the red, green and blue component. The int used to define the colour, when viewed in hex, would look like 0xRRGGBB. e.g.
  • 0xFF0000 - Red
  • 0x00FF00 - Green
  • 0x0000FF - Blue
  • 0xFFFFFF - White
  • 0x808080 - 50% grey
  • 0x000000 - Black

The following types are defined and used by the GFX object :

typedef void *GFX_IMAGE; 

typedef struct
    {
    int           w;
    int           h;
    int           pal[256];
    unsigned char *data;
    } GFX_BITMAP; 

typedef struct
    {
    int    type;
    int    shift;
    int    ctrl;
    int    alt;
    char   ascii;
    int    code;
    } GFXKey;

typedef struct GFXMouse
    {
    int    type;
    int    shift;
    int    ctrl;
    int    alt;
    int    x;
    int    y;
    int    b;
    } GFXMouse;

typedef union GFXEvent
    {
    int      type;
    GFXKey   key;
    GFXMouse mouse;
    } GFXEvent;

The following interfaces must be supplied by the GFX object:

void GFX_init(void)

Initialises the GFX object. No other GFX interfaces are called prior to this, with the possible (though current not used) exception of GFX_exit().

void GFX_close(void)

Called when viDOOM is terminating. Note that other (none system dependent) processing may go on between calling this and then invoking exit() or return().

GFX_IMAGE GFX_create_image(GFX_BITMAP *bm)

Should create a GFX_IMAGE from the passed bitmap bm.

void GFX_destroy_image(GFX_IMAGE img)

Release the bitmap object pointed to by img.

void GFX_draw_image(GFX_IMAGE img, int x, int y)

Draws img with it's top-left co-ordinate represented by x,y. This function should implement any necessary clipping when drawing the bitmap.

void GFX_fill_screen(GFX_IMAGE img)

Should fill the screen with the image, scaled if necessary. Note that this call is just used for the main menu backdrop, so if it cannot be honoured no harm will be done.

void GFX_open(int width, int height)

Opens the display (or window or whatever) with the specified width and height. Note that failures in here should terminate the program.

void GFX_clear(int col)

This clears the display to the passed colour col.

void GFX_redraw(void)

This redraws the contents of the screen. All drawing operations should not update the actual screen till this is called (i.e. the display should be buffered).

void GFX_line(int x1, int y1, int x2, int y2, int col)

Draw a line from x1,y1 to x2,y2 in colour col.

void GFX_plot(int x, int y, int col)

Plot the point x,y in colour col.

void GFX_circle(int x, int y, int r, int col)
void GFX_fcircle(int x, int y, int r, int col)

Draw a circle centred on x,y with a radius r and in colour col. The fcircle version should draw a filled circle.

void GFX_rect(int x, int y, int w, int h, int col)
void GFX_frect(int x, int y, int w, int h, int col)

Draw a rectangle with one corner at x,y and the other corner at (x+w),(y+h) in colour col. Note that zero length and negative width and heights must be allowed. The frect version should draw a filled rectangle.

void GFX_set_XOR_mode(void)
void GFX_clear_XOR_mode(void)

This should set and clear XOR mode. Normally all GFX operations should set the pixels to the colour specified, but when XOR mode is enabled the pixel values should be XORed into place.

void GFX_print(int x, int y, int col, char *fmt, ...)

Print the printf style arguments (fmt and ...) with their top left corner at x,y in colour col. Note that text should rendered transparently.

int GFX_fh(void)
int GFX_fw(void)

Return the height (GFX_fh) and width (GFX_fw) of the fixed width font used for display purposes.

int GFX_mouse_buttons(void)

Returns the number of mouse buttons. This is just used as check on initialisation as viDOOM expects at least 2 mouse buttons.

int GFX_mouse(int *x, int *y)

Return the current point position in x and y. If any of the passed pointers are NULL that variable should be ignored.

void GFX_waitkey(GFXKEy *key)

Waits for a key to be pressed and returns the key press in key. If key is NULL simply wait for a key press.

int GFX_key(GFXKey *key)

Returns TRUE if a key has been pressed and returns the keypress in key. Returns FALSE if there is no outstanding keypresses, in which case the contents of key are undefined.

void GFX_bounce(void)

Waits for all keys and mouse buttons to be released. On a real event-driven system could be ignored, or flush any outstanding events.

void GFX_await_input(GFXEvent *ev)

Waits for either a keypress or a mouse button to be pressed and fills in ev accordingly.

void GFX_await_input_full(GFXEvent *ev)

Waits for either a keypress, a mouse button to be pressed or the mouse to be moved and fills in ev accordingly.

void GFX_exit(int code, char *fmt, ...)

This call should do any necessary tidying of the display (switching from graphics mode, closing windows, whatever) then display the printf style arguments (fmt and ...) and the exit with the passed return code.

void GFX_save_screen(char *path)

This call need not be supported. It just allows screen grabs to be captured when viDOOM is compiled with debug information. If supported it should just save a bitmap in the file pointed to by path.

Platform GUI

platgui.c

This provides access to the platform's GUI routines.

The following types are defined and used by the PLATGUI object :

typedef struct
    {
    char      *text;
    GFX_IMAGE img;
    int       client_index;
    } PLAT_IMG_PICKLIST;

typedef struct
    {
    char   *text;
    int    client_index;
    } PLAT_PICKLIST;

typedef struct PLATMENU
    {
    char  *text;
    int   client_index;
    struct PLATMENU *child;
    } PLAT_MENU;

typedef struct
    {
    char   *text;
    int    group;
    int    val;
    } PLAT_MULTI;

typedef struct
    {
    char   *text;
    int    client_index;
    } PLAT_RADIO;

typedef struct
    {
    int     no;
    int     current;
    char    **text;
    } PLAT_DIAL_PL;

typedef struct
    {
    char   *text;
    int    type;
    union  /* Data */
        {
        int          i;
        char         s[PLAT_DIAL_MAXSTRLEN+1];
        double       d;
        PLAT_DIAL_PL pl;
        } data;
    } PLAT_DIALOG;

Note that along with the types, the following predefined values are set (these are read from the INI file). Note that they should be considered to be unset until immediately prior to viDOOM's call to GUI_setscreen():

Functions

The following interfaces are defined by the PLATGUI object. Note that all these calls are assumed to not destroy screen contents (ie. the screen should be restored after displaying the GUI object):

void GUI_setscreen(int width, int height)

Once the display has been opened with GFX_open() then this is called to inform the platform's GUI routines of the display size.

int GUI_yesno(char *question)

Display an alert with question in it and Yes and No buttons. Returns TRUE if Yes is pressed and FALSE if No is pressed.

int GUI_yesno_all(char *question)

Works like GUI_yesno(), but displays to extra options - "Yes to All" and "No to All". If either of these options are selected then further calls to this function should return TRUE/FALSE accordingly, until GUI_start_yesno__all() is called.

int GUI_start_yesno_all(void);

Resets GUI_yesno_all().

int GUI_alert(char *title, char *text, char *button_text)

Display an alert with a title of title, containing text as the message and with a single button labelled button_text. Note that text is split into multiple lines by the pipe (|) character.

int GUI_menu(char *title, int x, int y, PLAT_MENU menu[], int defval)

Displays a menu with title title at position x,y. The displayed items are taken from menu. The return is the client_index field from the selected menu item, or from the selected option in a child menu, or defval if the menu is cancelled.

char *GUI_fsel(char *title, char *default_path, char filter)

Allows a file to be selected. The file selector should have title for it's title and start selecting from the default_path. If filter is NULL then all files should be displayed, otherwise only files ending in filter.

The return is NULL if the selector is cancelled. Otherwise a pointer is returned containing the fully qualified path of the selected file. This pointer must be dynamically allocated and will be freed using FRelease().

int GUI_picklist(char *title, char *opts[])

Displays a picklist with title title. The options are taken from the array of character pointers opts. The return value is the index of the selected item in opts if selected, or -1 if the picklist is cancelled.

int GUI_client_picklist(char *title, PLAT_PICKLIST opts[], int defval)

Displays a picklist with title title. The text items to display are taken from opts. The return is the client_index field from the selected picklist item, or defval if the picklist is cancelled.

int GUI_image_picklist(char *title, PLAT_IMG_PICKLIST opts[], int defval)

Displays a picklist with title title. The text items and associated image to display are taken from opts. The return is the client_index field from the selected picklist item, or defval if the picklist is cancelled.

int GUI_radio_box(char *title, PLAT_RADIO opts[], int current, int defval)

Displays a dialog containing radio buttons with title title. The text to display is taken from opts. The selected object when the the radio box is first displayed is the option who's client_index field matches current (or the first item if there is no match). The return is the client_index field from the selected radio button, or defval if the radio box is cancelled.

int GUI_multi_box(char *title, PLAT_MULTI opts[])

Display a mutli-selection radio box. The items are described opts. The return is TRUE if the dialog is accepted, otherwise FALSE.

int GUI_dialog(char *title, int no, PLAT_DIALOG dial[])

Displays a dialog with the title title. The fields for the dialog are extracted from dial, for which there is expected to be no elements. The return is TRUE if the dialog is accepted, or FALSE if it is cancelled. On being cancelled the contents of the data union within the dial elements is undefined.

void GUI_file_view(char *title, char *file)

Displays the contents of a text file, allowing the user to move around and view the file. What form this takes is no concern at all to viDOOM.

If is assumed this can view both DOS format (lines terminated with CR and LF) and UNIX format text files (lines terminated with LF).

char *GUI_text_edit(char *title, char *text)

Allows simple text editting. The form this display takes is of noconcern to viDOOM (if applicable it would be more than OK to start an external text editor). text is a pointer to the original text, which is one long string with line breaks denoted by the '\n' character.

The return is a newly allocated copy of the edited text is the text is OKed, or NULL if the text is cancelled. In either case, the original string pointed to by text should be as it was.

File interface

file.c

This provides access to various file system functions and also provides some filename manipulation routines. The following interfaces should be provided:

char *Pwd(void)

This call should return the current working directory. The return should be static.

void Cd(char *path)

This call should change the current working directory to path.

char *Dirname(char *path)

This call should return the directory part of path if any. The return should be static.

char *Basename(char *path)

This call should return the filename part of path. The return should be static, or a pointer into the path parameter.

int FileExists(char *path)

This call should return TRUE if the file pointed to by path exists.

int FilenamesEqual(char *path1, char *path2)

This call should return TRUE if the file pointed to by path1 and path2 are the same file. At it's most basic (e.g. like in the DOS port) it can simply makes sure that directory separators are in the same form and then does strcasecmp() on the paths.

Memory allocation

mem.c

This provides memory allocation. While memory allocation can generally be done portably using malloc() providing this library just covers for any possible OS dependent twist. Also these routines are expected to handle errors internally. In all the interfaces file and line parameters are included so that errors can be reported more accurately.

The following interfaces should be provided:

void *FGrab (char *file, int line, int len)

This call should allocate len bytes and return a pointer to it. A len of zero is valid. Memory should be initialised to zero. Failure to allocate the memory should terminate the program.

void *FReGrab (char *file, int line, void *ptr, int len)

This call should re-allocate the memory pointed to by ptr and return a new memory area of len bytes. The original data pointed to by ptr should be copied to the new memory area. Failure to allocate the memory should terminate the program.

char *FStrdup (char *file, int line, char *str)

This call should allocate enough bytes to copy the nul terminated str to it. The returned pointer should point to the new copy of str. Failure to allocate the memory should terminate the program.

void *FCopy (char *file, int line, void *ptr, int len)

This call should allocate len bytes and copy len bytes from ptr into the new area. The newly allocated memory should be returned. Failure to allocate the memory should terminate the program.

void FRelease (char *file, int line, void *ptr)

This call should release the memory pointed to by ptr, which will have been allocated by FGrab, FReGrab, FStrdup or FCopy.

External command execution

runcmd.c

Provides a mechanism to run an external command. The following interfaces should be provided:

int RunCommand(char *argv[], char *path)

Run a command. The output from the command (if there is any) should NOT disturb the screen contents. The call should return TRUE if the call succeeds, FALSE otherwise.

The argv list is an array of pointers to various sections of the command and it's arguments, terminated with a NULL pointer. Note that arguments may contain more than one argument in each line - the actual command is described simply by concatenating all the pointers together, eg.

argv[0]="bsp"
argv[1]="file.wad"
argv[2]="-o file.wad"
argv[3]=NULL

The path argument is a place to copy the path to a file where the output from the command has been stored. If this is not supported then the empty string should be assigned to it. viDOOM will remove() the file after it has read it.

Portable String routines

vstring.c

Provides common string functions that are not actually part of the ANSI standard. While these can easily be portably written, they are provided as functions in case local implementations supply them (which will probably more effecient):

int StrCaseCmp(char *a, char *b)

Performs in exactly the same way as the ANSI strcmp() function, save for the fact that the case of the strings being compared is ignored.

int StrNCaseCmp(char *a, char *b)

Performs in exactly the same way as the ANSI strncmp() function, save for the fact that the case of the strings being compared is ignored.

Installation script

Each platform should provide a makefile called install. This is invoked from the top level makefile like this:

cd $(PLATFORM) ; $(MAKEINSTALL)

Note that the install makefile will be invoked with the PLATFORM directory as the current working directory.

The following files must be copied (where $SRC represents the source build directory and $INSTALLDIR the install directory):

Note that, obviously, any OS specific files should also be copied.

Documentation

If you release a port of viDOOM to any platform please update doc/bugs.htm with a contact address for problems on that platform. Also include a link to a system specific HTML document detailing how the GUI works and any know bugs, from doc/sys.htm.

For an example look at the DJGPP documentation. As you can see, it doesn't have to be too big.

Back to index

$Id$