This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new d4c904d949d docs/applications/examples/fb: Add documentation to fb
example
d4c904d949d is described below
commit d4c904d949d01d55672c20424024af263e846e5b
Author: Matteo Golin <[email protected]>
AuthorDate: Sun Nov 9 12:31:34 2025 -0500
docs/applications/examples/fb: Add documentation to fb example
Included documentation for the framebuffer example, fb. This includes a
description of how the program works, what features it supports and
images of what the rendered output should look like if everything is
correct.
Signed-off-by: Matteo Golin <[email protected]>
---
.../applications/examples/fb/fb-image.jpg | Bin 0 -> 201996 bytes
Documentation/applications/examples/fb/fb-skip.png | Bin 0 -> 3453231 bytes
Documentation/applications/examples/fb/index.rst | 65 ++++++++++++++++++++-
3 files changed, 64 insertions(+), 1 deletion(-)
diff --git a/Documentation/applications/examples/fb/fb-image.jpg
b/Documentation/applications/examples/fb/fb-image.jpg
new file mode 100644
index 00000000000..d0eeec7e11b
Binary files /dev/null and
b/Documentation/applications/examples/fb/fb-image.jpg differ
diff --git a/Documentation/applications/examples/fb/fb-skip.png
b/Documentation/applications/examples/fb/fb-skip.png
new file mode 100644
index 00000000000..c0d2e9b415b
Binary files /dev/null and b/Documentation/applications/examples/fb/fb-skip.png
differ
diff --git a/Documentation/applications/examples/fb/index.rst
b/Documentation/applications/examples/fb/index.rst
index 4e31adfa48c..6c6bb7bdf31 100644
--- a/Documentation/applications/examples/fb/index.rst
+++ b/Documentation/applications/examples/fb/index.rst
@@ -2,4 +2,67 @@
``fb`` Framebuffer
==================
-A simple test of the framebuffer character driver.
+This application is a simple demonstration which serves to test the
+:doc:`framebuffer character driver
+</components/nxgraphics/framebuffer_char_driver>`.
+
+The program interacts with the framebuffer through the interfaces described in
+the linked page in order to render a very simple image consisting of 6
+concentric, colourful rectangles. Note that between each rectangle, the program
+sleeps for 500 milliseconds. Rectangle are drawn from outermost to innermost,
in
+descending size.
+
+.. figure:: fb-image.jpg
+ :figwidth: 80%
+ :align: center
+ :alt: The Pinephone displaying concentric, colourful rectangles after
running the ``fb`` example.
+
+ The image displayed by the ``fb`` example, shown on the Pinephone. Credit to
+ Lup Yuen Lee.
+
+.. warning::
+
+ The application renders directly to the framebuffer provided by the
character
+ driver. On some devices, the entire rendering operation may not be complete
+ in time for the video synchronization, causing screen tearing or skips. This
+ is the case for the :doc:`Raspberry Pi 4B
+ </platforms/arm64/bcm2711/boards/raspberrypi-4b/index>`, and the results can
+ be seen below.
+
+.. figure:: fb-skip.png
+ :figwidth: 40%
+ :align: center
+ :alt: The framebuffer example output, but with skipped pixels.
+
+ The framebuffer example output, but with skipped pixels.
+
+Skipping issues like this one can generally be avoided by rendering to a
+separate buffer first, and then copying that buffer to the framebuffer in one
+operation.
+
+Feature support
+---------------
+
+The application ignores the pixel format provided by the framebuffer character
+driver, and only inspects the 'bits per pixel' (depth) field. Currently, only
+the following bits per pixel are supported (with the corresponding formats
+assumed):
+
+* 1: Monochrome
+* 8: RGB_332
+* 16: RGB_565
+* 24: RGB
+* 32: ARGB
+
+The program supports different features depending on the characteristics of the
+framebuffer driver. If the framebuffer requires ``FB_UPDATE``, this example
+behaves accordingly.
+
+If the framebuffer supports ``FB_OVERLAY``, then the application also supports
+getting and displaying the overlay information.
+
+If the virtual y resolution is double that of the y resolution when the
+framebuffer is initially queried, the application will attempt to use
+double-buffer rendering by fetching a second framebuffer corresponding to the
+``display + 1``, where ``display`` is the display number that was associated
+with the first framebuffer.
