From 0d102f1cfff6653150efc6d0cb01179ac1b6cd6c Mon Sep 17 00:00:00 2001 From: Jorge Guzman Date: Thu, 30 Jul 2026 02:38:22 -0300 Subject: [PATCH] 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 --- .../applications/games/nxdoom/index.rst | 43 +++++++++++++++++++ .../boards/linum-stm32h753bi/index.rst | 13 +++--- 2 files changed, 50 insertions(+), 6 deletions(-) diff --git a/Documentation/applications/games/nxdoom/index.rst b/Documentation/applications/games/nxdoom/index.rst index 4129f89c7a7..ed9c34a92da 100644 --- a/Documentation/applications/games/nxdoom/index.rst +++ b/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 ----------- diff --git a/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst b/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst index c105b3855cc..2f57f072265 100644 --- a/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst +++ b/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