Writing a PowerVR SGL replacement for a PCX1/PCX2 game

What to know

PowerVR's first chips (PCX1, PCX2) were driven through VideoLogic's SGL. Unlike Glide, SGL is a retained scene graph: the game builds display lists of transforms, materials, meshes, lights and cameras, edits a few transforms each frame and calls sgl_render. A stand-in keeps the graph and draws it with any API at any size. POD's PowerVR build runs through GameFrame's wrappers/sgl (Rust, 32-bit Windows, OpenGL). What mattered, each observed or measured there:

• Look for the SDK on the game's disc. Games shipped the PowerVR driver package, with sgl.h and sglwin32.h in it (POD: POWERVR/310C3.ZIP). The headers give every signature (all __cdecl, undecorated names) and the error codes; nothing needs fetching.
• sglhw.ini. The driver's installer writes it into the Windows folder. A game may read values from it and divide by them (POD reads the region size, 0 without the file, and divides). The stand-in writes the installer's values when the file is missing.
• The address callback. With sgl_use_address_mode the game names a function SGL calls for the memory to render each frame into. The game's callback also finishes the frame before it: draws its 2D overlay (the dashboard), shows it, and locks the next back buffer. Call it at the first sgl_render of a frame, fill the viewport in that memory with a marker, draw the scene with OpenGL, and put every non-marker pixel of the picture the game then shows on top. That needs the picture: a small hook in the DirectDraw stand-in passes it on. The callback's parameter block is packed (pointer, 16-bit stride, 8-bit depth).
• Materials inside meshes. Material calls made right after sgl_create_mesh belong to the mesh's faces; made elsewhere they are entries of the current list. Lists made with preserve_state give the transform, material and lights back when they end.
• Names. Calls with generate_name false return 0 (sgl_no_err), not a name.
• The immediate mode. SGL's other half (sgltri_*) takes faces already projected to the screen, in Direct3D's D3DTLVERTEX layout (SGLVERTEX), under an SGLCONTEXT of 0x90 bytes. Hardwar (1998) uses it. Draw the faces through the same pipeline. A vertex at screen (x, y) with 1/w becomes the camera-space point (x w, -y w, w) under a camera that maps it straight back, with the nearest w as the near plane. PowerVR's own SGLMID4.dll answers what the header leaves open. A face clockwise on the screen faces the camera. Faces of less than 1/32 pixel are dropped. Flat shading takes the first vertex's colour. The fog density (0 to 31) is a power-of-two register on a depth of 0.01 / w. Translucency is one 4-bit level per face. The driver sorts translucent passes, one per call and facing, farthest first; it never sorts single faces. It never reads SGLTT_VERTEXFOG.
• A test without the game. A small Windows program that makes the same calls on a known scene (a textured cube under a 2D bar) checks the projection, lighting, textures and the overlay where the game itself cannot run (wrappers/sgl/test/sgltest.c, and sgltritest.c for the immediate mode).

Still guesses

The projection from the camera rectangle, the fog formula, the default material and how a light volume adds light are inferred from the headers' names and the game's arguments; each is marked Deviation: in the stand-in until a picture of the original settles it.