

4DX Rendering Engine

        Thank you for purchasing the 4DX Evaluation kit. This kit is designed
        to help you determine if purchasing the 4DX library is right for you.
        This kit is a complete working version of the 4DX library. With it,
        you can compile, link and run your own applications. However, this is
        only an evaluation  kit. You may not distribute, in any way, any
        application made with this library. The amount of the eval kit will
        be deducted from the price of  the distribution kit, should you decide
        to purchase the library.

        Please note that technical support can only be provided by email.
        Please post technical support questions to my compuserve account
        at 74774,2475. For support through the internet, the address is
        74774.2475@compuserve.com.

4DX FAQ

        What is the 4DX library?

        The 4DX library is a rendering engine for creating 3D games.
        It is not a complete game system. The 4DX library uses a series
        of arrays of Sectors, Vertexes, Linedefs, and Actors to render
        a static scene. It is up to your code to make a game from this
        library.

        What is required to compile 4DX?

        4DX is a C++ Library and requires Watcom C++ v 10.0.
        4DX will NOT work with straight C. 4DX is fully 32bit.
        The DOS library runs under Dos4gw, and the Windows library
        runs under Windows NT, Windows 95, or Windows 3.11 with Win32s.
        If you want your game to run under Windows 3.11, you MUST ship
        it with Win32s!

        What are the requirements to run 4DX?

        Currently, the DOS version of 4DX requires 4MB of ram to run.
        However, this does not leave much space for graphics and sound.
        The Windows version of 4DX requires 8MB of ram, and Win32s.

        What is Win32s?

        Win32s is a 32 bit windows subsystem that allows Windows 3.1 to run
        32 bit Windows NT programs, as long as they only call supported
        functions. When compiling your 4DX application, you will compile
        and link for Windows NT.

        What is a Sector?

        A sector is a two dimensional enclosed area. Looking at an overhead
        map, each sector is a polygon. Each sector can have different lighting
        attributes, and heights associated with it. The sector is the basic
        unit of differentiating areas within the engine.

        What is a Linedef?

        The sides of sectors are made up of linedefs. Each line in the
        sector is a linedef. Each linedef has a texture associated with
        its upper portion and its lower portion.

        What is an Actor?

        An actor is an object that is rendered from a frameinfo. An actor
        can be a monster, or an item like a barrel. An actor has a only
        one x,y coordinate, and is always projected flat, towards the
        viewpoint.

        What is a FrameInfo?

        A frameinfo structure defines a series of bitmaps describing to
        the renderer how to draw an actor. There is not an interface to
        add frameinfo's. Your program must provide a frameinfo array.
        please see the example code.

        What is a Texture?

        A texture is used to put a picture on a wall. This picture is composed
        of one or more patches.

        What is a Patch?

        A patch is a picture unit. for instance, a brick wall texture might
        contain only 1 patch, the patch of the wall itself. To turn this
        texture into a wall with a switch, we can add a patch that contains
        only the switch.

        What are the limitations?

        256 textures. 1024 sectors.  1024 actors. The image data is only
        limited by the amount of ram.




        How do I add sound effects?

        You provide a function called "PlaySound" that the renderer calls
        when a sound needs to be played. Typically, you would then insert
        the appropriate sound type into some kind of array, that you would
        then process.

        How do I Keep score?

        Thats up to you!



Using the Renderer

        Step1: Initialize the renderer
        Step2: Build Tables for View
        Step3: Load Image Data
        Step4: Add Map Data

        After these steps are performed, Call BuildViewBySector to
        generate the view into the buffer pointed to by scrimage.


         ----------------------------------------------------------------------
         Example:

         // This example creates a simple map that contains only one room.

         Init4DX();             // Initialize renderer
         BuildTables(320,200);  // Build tables for view

         // Add the textures (code not included)
         // Add the flats    (code not included)

         // Add the vertexes.
         AddVertex(100,100);
         AddVertex(400,100);
         AddVertex(400,400);
         AddVertex(100,400);
         AddVertex(600,400);
         AddVertex(600,600);

         // Add the sector definition(s)
         NewSector (0,1,1,0,128,0,0);

         // Add the lines to the sector(s)
         AddLine(0,1,BOUND,1,0,0);
         AddLine(1,2,BOUND,1,0,0);
         AddLine(2,3,BOUND,1,0,0);
         AddLine(3,0,BOUND,1,0,0);

         // Add the actor(s)
         AddActor(200,200,0,0,ACTOR_SHOOTABLE,40,40);

         // generate a view from actor 0
         for(int i=0;i<100;i++)
            {
            BuildViewBySector(0,0);
            }

         ----------------------------------------------------------------------
         Example:

         // Making a two sector map.
         // Add the Sectors
         // Note: Please see example source for loading images.

         NewSector(0,1,1,0,128,0,0);
         NewSector(1,1,1,20,96,0,0);

         // Add Vertexes
         AddVertex(100,100);
         AddVertex(400,100);
         AddVertex(400,400);
         AddVertex(100,400);
         AddVertex(600,400);
         AddVertex(600,600);

         // Add lines for first sector (0)
         AddLine(0,1),BOUND,1,0,0);
         AddLine(1,2),BOUND,1,0,1);  // this line connects to sector 1.
         AddLine(2,3),BOUND,1,0,0);
         AddLine(3,0),BOUND,1,0,0);

         // Add lines for second sector (1)
         // Notice we did not add the connecting line twice.
         AddLine(1,4,BOUND,1,1,1);
         AddLine(4,5,BOUND,1,1,1);
         AddLine(5,2,BOUND,1,1,1);

         // Add the actor(s)
         AddActor(200,200,0,0,ACTOR_SHOOTABLE,40,40);

         // generate a view from actor 0
         for(int i=0;i<100;i++)
            {
            BuildViewBySector(0,0);
            }

Functions:

        Initialization Functions:
        -------------------------

        Function:    	Init4DX
        Parameters:  	None
        Returns:     	None
        Description: 	Performs one time initialization. Must be called before
                        any other 4DX functions.

        Function:    	BuildTables
        Parameters:  	Width (int), Height (int)
        Returns:     	None
        Description: 	Creates the appropriate tables for a view that is
                        Width wide, by Height high. Can be called multiple times
                        to change view size.




 Texture Functions:
        ------------------
        Function:    	AssignBitmap
        Parameters:  	index (int), address (unsigned char *),
                        width (int), height (int).
        Returns:     	None
        Description: 	Adds a bitmap to the bitmap array. This bitmap can later
                        be used as the texture source for an object.

        Function:    	AssignTexture
        Parameters:  	index (int), width (int), height (int)
        Returns:     	None
        Description: 	Adds a virtual texture to the texture array. Index is the
                        number of the texture (0-255). This function does not
                     	actually allocate any space for the texture itself.
                        Patches MUST be added to the texture before it can be
                        used! Textures MUST be powers of 2 wide (ie,16,32,64,128,256 etc).

        Function:    	AddPatch
        Parameters:  	index (int), address(unsigned char *),
                        width (int), height (int), xoffset (int), yoffset (int)
        Returns:     	None
        Description:    Adds a patch at ADDRESS to texture number INDEX.
                        Texture must be added before a patch can be added to the
                        texture.Width and height are the dimensions of the patch to
                        add to the texture. xoffset and yoffset are the position to
	                    	place the patch within the texture. NOTE: Clipping is not
           	          	performed on patches. The patch MUST fit entirely within
                        the texture.

        Function:    	AssignFlat
        Parameters:  	index (int), address (unsigned char *), mask (int)
        Returns:     	None
        Description: 	Adds a flat to the flat array. Flats are used for floors
                        ceilings, countertops, etc. INDEX is the number of the
                        flat. Each row of flat data MUST be 256 byte aligned.
                        Please see "LoadFlats" for an example on how to do this.
                        MASK is the AND mask for this, and is required. Normally,
                        the formula is as follows.

                        int mask = ((bmw-1)<<8)|(bmw-1);
                        Please note that a flat must be square, and must be a
                        power of 2 wide, ie, 16,32,64,128, or 256.

        Map Creation Functions:

        Function:    	NewSector
        Parameters:  	int sector   	sector number
                        int top        flat on the floor of this sector
                        int bottom     flat on the cieling of this sector
                        int floorht    the height of the floor
                        int ceilht     the height of the ceiling
                        int offset     the players offset inside this sector
                                       (ie, positive = floating, negative = sunken)
                        int flags      SECTOR_SELFILLUMINATING
                                       SECTOR_SKY
                                       SECTOR_SNOW
                                       SECTOR_RAIN
                                       SECTOR_BOB
                        int x_top      floor movement x direction
                        int y_top      floor movement y direction
                        int x_bottom   ceiling movement x direction
                        int y_bottom   ceiling movement y direction
                        int ltlevel    light level of this sector
        Returns:     	None
        Description: 	Adds

        Function:    	AddActor.
        Parameters:  	int x        	x position on map.
                        int y          y position on map.
                        int angle      angle actor is facing.
                        int flags      ACTOR_PICKUP
                                       ACTOR_WALKOVER
                                       ACTOR_USABLE
                                       ACTOR_CONSUMABLE
                                       ACTOR_AUTOINC
                                       ACTOR_SHOOTABLE
                                       ACTOR_ACTIVE
                        int maxhp      Maximum health of actor.
                        int curhp      Current health of actor.
                        int range      distance that actor can hit from.
                        int damage     damage that actor can do.
                        int dambase    least damage from a hit.
                        int active     whether this actor is active.
        Returns:     	None
        Description: 	Adds an actor to the actor database. Must be done after
                        sector has been added.

        Function:    	AddVertex
        Parameters:  	int x
                        int y
        Returns:     	Vertex Number
        Description: 	Adds a vertex to the vertex database. Vertexes for a
                        line must be added before the line is added.

        Function:    	AddLine
        Parameters:     int fv      index of from vert
                        int tv      index of to vert
                        int flags   BOUND         - there is nothing beyond wall
                                    TRIP_CROSS    - crossing the line "trips"
                                                    something
                                    TRIP_ACTIVATE - pressing space bar or
                                                    mouse button trips something
                                    LINE_EXTENDC  - instead of drawing a top
                                                    wall extend the cieling down
                                    LINE_NOMAP    - don't display on map ever
                                    LINE_SEEN     - this line has been seen
                                    LINE_SKIPCEIL - Dont draw ceiling
                                                    connecting to wall
                                    LINE_MASK     - Color 0 is masked.
                                                    wall cannot be BOUNDED, and
                                                    connecting sector MUST be same
                                                    floor and ceiling height.
                                    LINE_TRANS    - Line is translucent - only
                                                    used with LINE_MASK. Instead of
                                                    being drawn, solid colors are
                                                    translucent over background.
                        int bitmap     Texture number from texture array of bottom
                                       segment. Also whole wall if BOUND
                        int sec        Sector number that this wall is in
                        int tosector   Sector number that this wall faces. if wall
                                       is BOUND, then must be same as SEC

                        int trpflags   TRIP_CHANGEFLOOR    Floor of sector in
                                                           trip1 changes TO trip2.
                                       TRIP_CHANGECIELING  Ceiling of sector in
                                                           trip3 changes TO trip4.
                                       TRIP_ONCE           Only trips one time.
                                       TRIP_TELEPORT       Teleport to location.
                                                      trip1 = x
                                                      trip2 = y
                                                      trip3 = height
                                                      trip4 = facing angle
                                       TRIP_FLIP      exchanges bitmap and bitmap2
                                                      and topbm and topbm2.
                                                      useful for switches.

                                       TRIP_ROTATESECTOR   rotate a sector around x,y
                                                      trip1 = sector
                                                      trip2 = degrees
                                                      trip3 = x
                                                      trip4 = y
                                  		TRIP_UNROTATESECTOR
                                                      See above, except that sector
                                                    	moves back to original position

                        int bitmap2    exchanges with bitmap when line is flipped.
                        int topbm      Bitmap on ceiling segment.
                        int topbm2     exchanges with topbm when line is flipped.
        Returns:     	None
        Description: 	Adds a line to a sector. A sector must be fully enclosed
                        by lines, and lines must be entered CLOCKWISE.

        Function:    	NewLine
        Parameters:  	See above.
        Returns:     	None
        Description: 	Use Addline unless you haven't added your vertexes yet.
                        This function is the same as addline except for passing
                        actual x1,y1,x2,y2 coordinates for the line. vertexes will
                        be created for you. Newline is only included for backward
                        compatability.

        Function:    	DupeLine
        Parameters:  	linedef *aLine     the line to duplicate
                        int      tosector  the sector to place the duplicate in.
        Returns:     	None
        Description: 	This function welds two sectors together by inserting a
                        duplicate line in a lines facing sector.


 Runtime Functions:

        Function:    	BuildViewBySector
        Parameters:  	int actor   actor to generate POV from
                        int bob     skew the view up or down by this amount
        Returns:     	None
        Description: 	Generates a view into buffer at the point of view of
                        the actor.

        Function:    	CheckEvents
        Parameters:  	None
        Returns:     	None
        Description: 	Must be called once per frame to make sure events happen

        Function:    	CheckMissiles
        Parameters:  	None
        Returns:     	None
        Description: 	Must be called once per frame to move missiles

        Function:    	CheckActors
        Parameters:  	None
        Returns:     	None
        Description: 	Must be called once per frame so that gravity acts on actors.

        CallBack Functions:
        -------------------
        Note: Your program must provide these functions.

        Function:    	HandleMessage
        Parameters:  	int msg
                        int info
        Returns:     	None
        Description: 	If msg = MSG_HPCHANGE, then your characters hit points
                        have been changed.
                        if msg = MSG_HITITEM, then your character has ran over
                        an item (item number = info)

        Function:    	PlaySound
        Parameters:  	int soundnum
                        int volume
        Returns:     	None
        Description: 	Play sound number soundnum at level volume.


        Useful Objects:
        ---------------

        ActorBox 	aBox
        Function:    	FindBox
        Parameteres: 	int x
                        int y
        Returns      	int ActorIndex
        Description: 	Use this object to determine if a point on a screen
                        is over any actors. For example if the mouse was clicked
                        at 160,100,
                        actr = aBox->FindBox(160,100);
                        if actr is greater than 0, then an actor was clicked on,
                        and you can take the appropriate action.
