Documentation/applications/games/nxdoom: document the display options

The options that let a board trade memory for drawing speed were only
described in their Kconfig help, where someone bringing the game up on a
new board is unlikely to find them.  Describe what each one does and
when it is worth enabling.

Signed-off-by: Jorge Guzman <jorge.gzm@gmail.com>

Documentation/applications/games/nxdoom/index.rst

@@ -93,6 +93,49 @@ To launch the game, just run:
 
 and replace the path with your WAD file's path.
 
+Tuning the display for a board
+------------------------------
+
+DOOM renders a 320x200 image with 8 bits per pixel and a palette, and the port
+scales that up and converts it to whatever the frame buffer wants. How much
+that costs depends a great deal on the board, so the following options are
+available. All of them are disabled by default, which leaves the behaviour
+unchanged, and each is worth enabling only where it pays.
+
+``CONFIG_GAMES_NXDOOM_FB_CMAP``
+  Load the DOOM palette into the frame buffer's colour map and blit the
+  palette indices unconverted, letting the display convert them while it scans
+  out. This needs a frame buffer that is 8 bits per pixel and supports
+  ``FBIOPUT_CMAP``, such as an STM32 LTDC layer configured for L8. It removes
+  the conversion from the blit and halves the amount of data written per
+  frame.
+
+``CONFIG_GAMES_NXDOOM_FILLSCREEN``
+  Stretch the image over the whole display instead of scaling it by the
+  largest whole number that fits. This fills a display whose size is not an
+  exact multiple of 320x200, at the cost of a scale factor that is not uniform
+  across the image. Without it the image is scaled by a whole number and
+  centred, leaving a border.
+
+``CONFIG_GAMES_NXDOOM_ROWSTAGE``
+  Build each output row in a staging buffer and copy it out, rather than
+  writing the frame buffer a pixel at a time, so that the frame buffer only
+  ever sees burst-friendly copies. Costs a few kilobytes of ``.bss``. This is
+  worth a lot when the frame buffer is external memory and the data cache is
+  in write-through mode, and little otherwise.
+
+``CONFIG_GAMES_NXDOOM_STATIC_SCRNBUF``
+  Place the buffer DOOM renders into in ``.bss`` rather than taking it from the
+  heap, which puts it in internal RAM on a board whose heap is mostly external
+  memory. The renderer draws in vertical columns, so consecutive writes are
+  one screen width apart and none of them coalesce, which makes external memory
+  close to the worst case for it. Costs 64000 bytes of RAM whether the game
+  runs or not.
+
+As an illustration of the effect, on an STM32H753 driving a 1024x600 panel
+whose frame buffer lives in SDRAM, ``ROWSTAGE`` and ``STATIC_SCRNBUF`` are
+worth 2.7 times the frame rate between them.
+
 Other Notes
 -----------
 

Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst

@@ -1150,8 +1150,8 @@ reset the board and check that all three devices came up::
    zero
 
 Mount the card and start the game. ``nxdoom`` looks for the IWAD in the
-current directory, so either ``cd`` to the mount point first or point it at the
-file with ``-iwad``::
+current directory, so either ``cd`` to the mount point first or point it at
+the file with ``-iwad``::
 
   nsh> mount -t vfat /dev/mmcsd0 /mnt
   nsh> nxdoom -iwad /mnt/doom1.wad
@@ -1183,10 +1183,11 @@ file with ``-iwad``::
   hu_init: Setting up heads up display.
   st_init: Init status bar.
 
-**Copying the IWAD with zmodem:** the configuration also enables the ``rz`` and
-``sz`` commands, so the IWAD can be copied over the serial console instead of
-moving the SD card to a card reader. ``CONFIG_SYSTEM_ZMODEM_MOUNTPOINT`` is
-set to ``/mnt``, so a received file lands on the SD card::
+**Copying the IWAD with zmodem:** the configuration also enables the ``rz``
+and ``sz`` commands, so the IWAD can be copied over the serial console
+instead of moving the SD card to a card reader.
+``CONFIG_SYSTEM_ZMODEM_MOUNTPOINT`` is set to ``/mnt``, so a received file
+lands on the SD card::
 
   nsh> mount -t vfat /dev/mmcsd0 /mnt
   nsh> rz