SRB2/doc/source.txt

1. Compile SRB2
2. Explanation of the code
 2.1 The memory model
 2.2 Hardware Texture model

1. Compile SRB2
=================

DOS
---

need:
- djgpp 2.03     (http://www.delorie.com/djgpp/)
- allegro 3.12   (http://alleg.sourceforge.net/index.html)
(
- libsocket 0.7.4 (beta 4) or better
   for use with Winsock 1.1 (example Windows 3.1)
  (http://www.phekda.freeserve.co.uk/richdawe/lsck/lsck.htm)
   OR
- Wattcp-32 v2.2 dev.rel 6 or better
   For use with a packet driver
  (http://www.bgnett.no/~giva/)
  (http://groups.yahoo.com/group/watt-32/)
  (http://groups.yahoo.com/group/watt-32/files/v2.2/)
)
- bcd 1.03 (inlcude in this package)
- gcc 2.95.2 is recommended
- nasm 0.98 (or better)     (http://nasm.sourceforge.net/)

compile:
make
make WATTCP=1 (to make a Wattcp-32 version)

debug:
when craching SRB2 will return eip
type make asm, then you will have a 8 megs srb2.s (a assembler file)
the you can find the faulting instruction and function

------------------------------------------------------------------------

Linux/SDL
-----

need:
- tested with gcc 2.95 and 3.X.
- SDL 1.2
- SDL_mixer 1.2
- ibogg and libvorbis (http://Xiph.org/)
- nasm 0.98 (or better)(http://nasm.sourceforge.net/) only with 2.95, else add CC30=1

compile
make LINUX=1

debug:
gdb ?

------------------------------------------------------------------------

Win32
-----

need :
- glide 3.x sdk (optional)  (http://www.3dfx.com)
- directx6 sdk (or higher)  (http://www.micosoft.com/directx)
- nasm 0.98 (or better)     (http://nasm.sourceforge.net/)
- use src\win32\wLegacy.dsp
- VC6 should also work with VC5, and VS.NET 200X

debug:
press on "step over" with the release version (there is some debug info
on it). Then change the eip in the regster window when you will type
enter the edi will go to the faulting instruction. don't forget that
you can follow the stack for calls.
You can also use trace with the debug version but add -win and -nomouse.

------------------------------------------------------------------------

Win32/minGW/SDL
-----

need:
- tested with gcc 2.95 and 3.X.
- can also use Dev-C++ 5.0 beta 9 (4.9.9.0) from http://www.bloodshed.net/dev/devcpp.html
- SDL 1.2
- SDL_mixer 1.2

compile
make minGW=1 SDL=1
or use src\SDL\Win32SDL.dev with Dev-C++ 4.9.9.0 or later

debug:
gdb ?

------------------------------------------------------------------------

WinCE/SDL WIP
-----

need:
- ActiveSync 3.8
 http://www.microsoft.com/windowsmobile/downloads/activesync38.mspx

- ActiveSync 3.7.1, if 3.8 isn't available for your language
 http://www.microsoft.com/windowsmobile/downloads/activesync37.mspx

- eMbedded Visual Tools 3.0 - 2002 Edition
 http://www.microsoft.com/downloads/details.aspx?FamilyID=f663bf48-31ee-4cbe-aac5-0affd5fb27dd

- Pocket PC 2000 SDK
 http://www.microsoft.com/downloads/details.aspx?FamilyID=bb3f4d7b-de2a-4e1a-a175-26a68c301ac4

- Pocket PC 2002 SDK (eMVT 3.0 2002 Ed. comes with this)
 http://www.microsoft.com/downloads/details.aspx?FamilyID=2dbee84a-bd94-4167-b817-2b2e548b2e92

- Pocket PC 2002 SDK Emulator Images (eMVT 3.0 2002 Ed. comes with this)
 http://www.microsoft.com/downloads/details.aspx?FamilyID=25f4de97-ae80-477a-9df1-496b85b3d3e3

- eMbedded Visual C++ 4.0
 http://www.microsoft.com/downloads/details.aspx?familyid=1DACDB3D-50D1-41B2-A107-FA75AE960856

- eMbedded Visual C++ 4.0 SP3 (Win CE 4.0-4.2)
 http://www.microsoft.com/downloads/details.aspx?FamilyID=5bb36f3e-5b3d-419a-9610-2fe53815ae3b

  OR

- eMbedded Visual C++ 4.0 SP4 (No SH3 support,Win CE 4.0-5.0 support)
 http://www.microsoft.com/downloads/details.aspx?FamilyID=4a4ed1f4-91d3-4dbe-986e-a812984318e5

- eMbedded Visual C++ 4.0 Update 5625 (SP4 only)
 http://www.microsoft.com/downloads/details.aspx?FamilyID=aa282a6d-6f57-436d-8c10-0ec02d94f5b1

- Windows CE: Standard Software Development Kit
 http://www.microsoft.com/downloads/details.aspx?familyid=a08f6991-16b0-4019-a174-0c40e6d25fe7

- SDK for Windows Mobile 2003-based Pocket PCs
 http://www.microsoft.com/downloads/details.aspx?FamilyId=9996B314-0364-4623-9EDE-0B5FBB133652

- Emulator Images for Windows Mobile 2003 Second Edition software for Pocket PC
 http://www.microsoft.com/downloads/details.aspx?familyid=5C53E3B5-F2A2-47D7-A41D-825FD68EBB6C

- Microsoft Device Emulator 1.0 Community Preview
 http://beta.microsoft.com Use Guest ID "MSDEVICE" to access the Community Preview website

- Windows CE Utilities for Visual Studio .NET 2003 Add-on Pack 1.1
  (if you also have VS 2003 installed, you need this to install Win CE 5.0 SDK, else no need)
 http://www.microsoft.com/downloads/details.aspx?FamilyId=7EC99CA6-2095-4086-B0CC-7C6C39B28762

- Windows CE 5.0: Standard Software Development Kit (eMC++ 4 SP4 only)
 http://www.microsoft.com/downloads/details.aspx?FamilyID=fa1a3d66-3f61-4ddc-9510-ae450e2318c3

- SDL 1.27 (use patch and zip in tools\SDL1.2.7_CE)

compile
use src\SDL\WinCE\SRB2CE.vcw

debug:
?


2. Explanation of the code
==========================

 2.1 The memory model (original) (z_zone.c) (by BP)
 --------------------

 SRB2 allocate a heap of 6/32/48 megs at begining and provide a Z_Malloc function
 to allocate in this heap.

   Z_Malloc( int size,int tag,void* user )

    size is the size in byte
    tag can be : PU_STATIC   allocated static (like malloc do)
                             call Z_Free to free it
                 PU_LEVEL    same as static but the zone is "tagged" with the
                             tag PU_LEVEL, when calling
                             Z_FreeTag (PU_LEVEL, PU_LEVEL) all zone tagged
                             with PU_LEVEL are freed (at the end of the level)
                 PU_CACHE    this one _can_ be freed automatiquely by one other
                             call to Z_Malloc. the *user point to a pointer
                             to this zone so when freed automatiquely the
                             pointer is set to NULL so eatch time you use it
                             you must check if the pointer is not NULL and
                             reload it.

 (...)

 2.2 Hardware Texture model (by BP)
 --------------------------

 Eatch texture/patch/flats/pic in SRB2 are converted to hardware texture at
 runtime (the GlideMipmap_s structure (hw_data.h)). I will call hardware
 texture a gr_texture so there is no confusion.

 To remind you :
  - Texture are set of patch and are associate to linedefs (walls) can be
    upper, lower or middle texture. It can have hole on it.
  - patch are sprites (the doom patch are run of vertical lines)
  - flats are used for floors and ceiling of sectors and have size of 64x64
    it can't have hole on it
  - pic are new legacy format for picture, it can only handle plain texture
    like flats it is now used for hud in full screen for the main picture
    of legacy and for coronas (the format was extended to handle 32 bit color
    or intensity + alpha, not all are implemented at this time)

 Since patch, flat and pic are basic structure represented by only one lump in
 the wad, the wad loader allocate for eatch lump a GlideMipmap_s (cache3Dfx)
 and init data field to NULL. Since the data structure is allocated in
 PU_3DFXCACHE (like PU_CACHE) the data will be initilised when needed
 (hw_cache.c).

 The GlideMipmap_s structures for textures are initialized on
 HWR_PrepLevelCache (hw_cache.c) it is called in P_SetupLevel (load level)
 the number of textures is computed with TEXTURE1, TEXTURE2 lumps since this
 can be changed in runtime in SRB2 (load a wad while runing) it must be
 reallocated. Well, at this time it is realloceted at eatch level start. We
 can do better, since numtextures change only when a wad is loaded.

 The 3dfx driver use glide3, it load gr_texture in gr_texture memory of the
 card in fifo order when there is no more place it remove the first gr_texture,
 the downloaded field of GlideMipmap_s go to false and when needed it is
 reloaded in gr_texture memory. In OpenGl, since OpenGl keep texture in there
 own memory and handle gr_texture memory of the card we no more need to
 redownload it but if we not free time to time gr_texture memory in opengl,
 it will get alot of memory, so the gr_texture memory is cleared at eatch
 new level (same time of texture reallocation). Opengl and 3dfx link the
 loaded gr_texture with the nextmipmap field of GlideMipmap_s so before clear
 textures of the heap we MUST free gr_texture memory of OpenGl or 3dfx !

 SRB2 can also draw patch with a differant colormap (thanks to Hurdler).
 When needed it create the same gr_texture but just with a differant colormap.
 This one is linked with the original in the GlideMipmap_s with the
 nextcolormap field.

 So when a polygone with a gr_texture must be drawn, first we check if the
 gr_textures is not allready loaded in hadware memory (downloaded field) if
 not then we check if gr_texture data is there (not grabbed by z_malloc
 function) if not we must recompute it eatch type of gr_texture (texture,
 patch, flat, pic have there own methode) the we can send the gr_texture
 to 3dfx or OpenGl.