How to Automate Plugin Screenshots

If you've written a manual entry for a plugin, you'll probably want some screenshots showing the plugin in action, but you really don't want to generate them by hand. In June 2016, the author used the following procedure to automate this process:

This article assumes some knowledge about Rockbox internals. If something is unclear, don't hesitate to ask __builtin on the IRC.

1. Modify Rockbox

You want Rockbox to start, run your plugin, save a screenshot, and exit.

There is a patch in gerrit that demonstrates this for the 2048 plugin: http://gerrit.rockbox.org/r/#/c/1338/

You should be able to modify it so that it runs your plugin instead of 2048.

A list of changes you'll need to make is outlined below:

• Uncomment the AUTOROCK define in apps/main.c
• Change the autorock path in apps/main.c to that of your plugin
• Change the filenames generated by the screendump
• Add the screen_dump function to the plugin API

2. Modify your plugin

You need to make the following changes to your plugin:

• Operate without user interaction -- this usually means eliminating interactive menus and simulating user input
• Operate deterministically -- rb->srand(SOME_CONSTANT)
• Get into an interesting state, call rb->screen_dump(), and exit

In order to make things run slightly faster, it is recommended that, if possible, you avoid refreshing the screen until the very end.

3. Gut Rockbox

Since you don't care about other plugins or codecs, you can edit apps/plugins/SOURCES and apps/plugins/SUBDIRS so that only your plugin is built.

Also, if you don't need codecs, you can edit the SOURCES files under lib/rbcodec/[codecs,dsp]

4. Build and run all targets

Now that your Rockbox has been configured to start your plugin, screen dump, and exit, you need to repeat this process for every target.

AmauryPouly was kind enough to provide a script that automates this:

cat ../www/buildserver/builds | grep sim | awk 'BEGIN { FS=":"; } { system("rm -rf build && mkdir build && cd build && "$7 " -j9 && make install && xvfb-run ./rockboxui && cp simdisk/*.bmp ../screenshots/ && cd .. && rm -rf build"); }'

You will need to edit this to suit your needs.

5. Convert to PNG

You will now have a collection of screenshots for various targets in the screenshots/ directory.

You need to make sure they are in the format ss-yourplugin-WxHxD.bmp, and then copy them to the manual/plugins/images directory

Here you must convert the BMP images to PNG to ensure that LaTeX recognizes them.

NOTE: the default pnmtopng utility produces very poor output. The author used ffmpeg to convert the images.

-- FranklinWei - 05 Jun 2016