Prettier API docs, Source page updated

Time for another weekly update. This week I’ve been working on a new style for the API documentation and a couple of minor bug fixes.

The main focus this week has been on updating and styling the API documentation. So far we’ve been using the default Doxygen CSS stylesheets (with a couple of tiny edits) but the end result with those is neither very readable nor visually pleasing.

I spent a couple of evenings setting up CSS that follows the design of the website. It took a little longer than anticipated — Doxygen’s HTML output is surprisingly complex, with all kinds of different indices, directories, and tables. I’m quite pleased with the results, both in the web browser and the Qt Help format.

Visual appearance is only a small part of what makes API documentation useful, though. As far as the actual content goes, there are still some important parts missing, especially with things like top-level module overviews for introducing their functionality for someone who is not already familiar with them. I did spend some time reorganizing the SDK’s documentation into a cleaner tree of modules and submodules, hiding everything that is related to classes’ private implementations or other private data, and adding some macro expansions for the observer audiences.

In addition to the SDK API docs, there is also similar documentation for the client app and the three primary game plugins. These, and the repository commit tag index (Codex), are now available on the Source page. The autobuilder updates this documentation nightly based on the code in the master branch.

The week wasn’t all about a fresh coat of paint, though. I made a couple of small fixes:

  • When a mobj acts as a light source, the old renderer has always treated this as a hint to draw the object with maximum ambient lighting. With the new 3D models, though, where we have a custom per-pixel lighting model with normal mapping, this messes things up because when the ambient light is so bright, it overrides the contribution from diffuse lighting. To handle objects that emit light, the new renderer uses emissive maps. This allows the object to have light-emitting pixels anywhere on its surface, rather than affecting the entire model as a whole. The new model renderer now ignores the old full-bright flags on mobjs, with the assumption that the model asset will take care of emitting light appropriately.
  • Earlier when I was working on the Doomsday UI, I thought I had already fixed issue #2058: using the Windows desktop DPI factor for the client UI. Upon further testing it turned out this wasn’t working correctly. I applied a new fix where the DPI factor is queried directly via the Direct2D API, so it is guaranteed to be correct. This should be helpful if you’re running Windows on a high-resolution display.