This document tries to describe the inner workings of the 3D scene objects.

AddTo3DScene is the method of map objects whereby the map structure builds the 3d scene. The real work is done by methods such as TFace.AddTo3DScene in prog/QkMapPoly.pas [tig: what is the correct name for a subclass's implementation of a virtual method?]; we see that the workhorse line is:

CurrentMapView.Scene.AddPolyFace(P);

CurrentMapView is a global variable of type TPyMapView defined by this line of python/PyMapView.pas:

CurrentMapView : TPyMapView = TPyMapView(-1);

A TPyMapView is a subclass of TScrollBox, I presume the -1 is setting its owner to nothing [tig: check this]. For some reason, Scene is a property whose read method is FScene, whose value is a TSceneObject.

TSceneObject defined in 3dfx/EdSceneObject.pas, with subclasses:

3dfx\EdSoftware.pas(183): TSoftwareSceneObject = class(TSceneObject) 3dfx\EdGlide.pas(178): TGlideSceneObject = class(TSceneObject) 3dfx\EdOpenGL.pas(181): TGLSceneBase = class(TSceneObject) 3dfx\EdDirect3D.pas(78): TDirect3DSceneObject = class(TSceneObject)

Note: Line numbers will change as history is added to the front of the file.

The first is the class for the software, the second for Glide (3dfx) 3d textured views, the third for the OpenGL one, and the last is the start of an unfinished project to produce a Direct3D view; the appropriate constructors are called by python/PyMapView:TPyMapView.NeedScene.

There also are several files that are used by the renderers:

3dfx\Glide.pas (Used by Software and Glide) 3dfx\GL1.pas (Used by OpenGL) 3dfx\Direct3D9.pas (Used by Direct3D) 3dfx\Direct3D.pas (Used by Direct3D) 3dfx\DirectDraw.pas (Used by Direct3D) 3dfx\DX9.pas (Used by Direct3D) 3dfx\DXErr9.pas (Used by Direct3D) 3dfx\DXTypes.pas (Used by Direct3D)

EdSceneObject.pas: This is divided into two sections, one concerned with TSceneObject, the other with TTexture Manager. The interesting non-virtual method is BuildScene, which is very big - Armin seems to often have gone for extremely long functions, which are supposed to be bad style, so perhaps we could think about breaking this one up into intelligible bits?

An important type in 3d scene building is PSurface, defined in prog/QkMapPoly.pas, which defines a visible polyhedron face. It is a pointer to a TSurface, defined as follows:

TSurface = record Source: TTreeMap; F: TFace; NextF: PSurface; { linked list of PSurfaces for a given face } prvVertexCount: Integer; prvVertexTable: TFVertexTable; end;

Each face has a linked list of PSurfaces because of face-sharing. F is used to get info about the texture-name, etc., Source isn't used by this module. The PSurfaces are rebuilt by code in QkMapPoly.pas.

The AddSurfaceRef sub-procedure of BuildScene adds a surface to a master-list of surfaces, TSceneObject.FListSurfaces, accessible also as read-property ListSurfaces. Need to understand BuildScene to see what this does.

Questions about TSceneObject:

how does BuildScene work? what is SetColor do for? what is the purpose of ChangeQuality? It seems to be related to cutting the resolution in half in the software renderer.

If a 3d window is open, gets called every time anything happens to the views. This seems excessive, for example for a selection event very little gets changed.

1. some initializations: Held over from previous BuildScene: TextureManager Reinitialized: TexNames list FlistSurfaces - done via linked list freeing, maybe a slowdown factor? nVertexList and nVertexList2

2. scan the map objects and build the TexNames list, which gives information about surfaces indexed by the TexNames, and also add this information to the FlistSurfaces list.

Problem: the info specifies how much info is needed to store the vertexes of the faces using the texture, but no info about those vertexes seems to be recorded.

3. rebuild the old textures, note how many new ones needed. Q: what does building do?

4. free old textures no longer needed

5. load and build new textures

6. build a lot of stuff

7. for each face, load a lot of stuff into the appropriate surf3d element [some of it looks like texture coordinates]

8. ditto for models, sprites and beziers lots of rather repetitive-looking code.

9. and a bit of final cleanup.

More understanding of what goes on in steps 6-8 is needed here.