graphics/nxbe: Implement hooks that will eventually support software 'sprites', i.e., things like OSD functionality, a software cursor, selection rectangles, window resize preview, etc.

graphics/nxbe/Make.defs

@@ -40,6 +40,10 @@ CSRCS += nxbe_fill.c nxbe_filltrapezoid.c nxbe_setpixel.c
 CSRCS += nxbe_lower.c nxbe_raise.c nxbe_modal.c
 CSRCS += nxbe_setsize.c nxbe_visible.c
 
+ifeq ($(CONFIG_NX_RAMBACKED),y)
+CSRCS += nxbe_flush.c
+endif
+
 DEPPATH += --dep-path nxbe
 CFLAGS += ${shell $(INCDIR) $(INCDIROPT) "$(CC)" $(TOPDIR)/graphics/nxbe}
 VPATH += :nxbe

graphics/nxbe/nxbe.h

@@ -443,9 +443,9 @@ void nxbe_move(FAR struct nxbe_window_s *wnd,
  *   device unconditionally.
  *
  * Input Parameters:
- *   wnd   - The window that will receive the bitmap image
+ *   wnd    - The window that will receive the bitmap image
- *   dest   - Describes the rectangular on the display that will receive the
+ *   dest   - Describes the rectangular region on the display that will
- *            the bit map.
+ *            receive the the bit map.
  *   src    - The start of the source image.
  *   origin - The origin of the upper, left-most corner of the full bitmap.
  *            Both dest and origin are in window coordinates, however, origin
@@ -474,9 +474,74 @@ void nxbe_bitmap_dev(FAR struct nxbe_window_s *wnd,
  *   and shadowed in the per-window framebuffer.
  *
  * Input Parameters:
- *   wnd   - The window that will receive the bitmap image
+ *   wnd    - The window that will receive the bitmap image
- *   dest   - Describes the rectangular on the display that will receive the
+ *   dest   - Describes the rectangular region on the display that will
- *            the bit map.
+ *            receive the the bit map.
+ *   src    - The start of the source image.
+ *   origin - The origin of the upper, left-most corner of the full bitmap.
+ *            Both dest and origin are in window coordinates, however, origin
+ *            may lie outside of the display.
+ *   stride - The width of the full source image in bytes.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
+void nxbe_bitmap(FAR struct nxbe_window_s *wnd,
+                 FAR const struct nxgl_rect_s *dest,
+                 FAR const void *src[CONFIG_NX_NPLANES],
+                 FAR const struct nxgl_point_s *origin,
+                 unsigned int stride);
+
+/****************************************************************************
+ * Name: nxbe_sprite_refresh
+ *
+ * Description:
+ *   Prior to calling nxbe_bitmap_dev(), update any "sprites" tht need to
+ *   be overlaid on the per-window frambuffer.  This could include such
+ *   things as OSD functionality, a software cursor, selection boxes, etc.
+ *
+ * Input Parameters (same as for nxbe_bitmap_dev):
+ *   wnd    - The window that will receive the bitmap image
+ *   dest   - Describes the rectangular region on the display that was
+ *            modified (in device coordinates)
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
+#ifdef CONFIG_NX_RAMBACKED
+#if 0 /* There are none yet */
+void nxbe_sprite_refresh(FAR struct nxbe_window_s *wnd,
+                         FAR const struct nxgl_rect_s *dest);
+#else
+#  define nxbe_sprite_refresh(wnd, dest)
+#endif
+#endif
+
+/****************************************************************************
+ * Name: nxbe_flush
+ *
+ * Description:
+ *   After per-window frambuffer has been updated, the modified region must
+ *   be written to device graphics memory.  That function is managed by this
+ *   simple function.  It does the following:
+ *
+ *   1) It calls nxbe_sprite_refresh() to update any "sprite" graphics on top
+ *      of the RAM framebuffer.   This could include such things as OSD
+ *      functionality, a software cursor, selection boxes, etc.
+ *   2) Then it calls nxbe_bitmap_dev() to copy the modified per-window
+ *      frambuffer into device memory.
+ *
+ *   This the "sprite" image is always on top of the device display, this
+ *   supports flicker-free software sprites.
+ *
+ * Input Parameters (same as for nxbe_bitmap_dev):
+ *   wnd    - The window that will receive the bitmap image
+ *   dest   - Describes the rectangular region on the display that will
+ *            receive the the bit map.
  *   src    - The start of the source image.
  *   origin - The origin of the upper, left-most corner of the full bitmap.
  *            Both dest and origin are in window coordinates, however, origin
@@ -489,13 +554,11 @@ void nxbe_bitmap_dev(FAR struct nxbe_window_s *wnd,
  ****************************************************************************/
 
 #ifdef CONFIG_NX_RAMBACKED
-void nxbe_bitmap(FAR struct nxbe_window_s *wnd,
+void nxbe_flush(FAR struct nxbe_window_s *wnd,
                  FAR const struct nxgl_rect_s *dest,
                  FAR const void *src[CONFIG_NX_NPLANES],
                  FAR const struct nxgl_point_s *origin,
                  unsigned int stride);
-#else
-#  define nxbe_bitmap(w,d,s,o,n) nxbe_bitmap_dev(w,d,s,o,n)
 #endif
 
 /****************************************************************************

graphics/nxbe/nxbe_bitmap.c

@@ -191,9 +191,9 @@ static inline void nxbe_bitmap_pwfb(FAR struct nxbe_window_s *wnd,
  *   device unconditionally.
  *
  * Input Parameters:
- *   wnd   - The window that will receive the bitmap image
+ *   wnd    - The window that will receive the bitmap image
- *   dest   - Describes the rectangular on the display that will receive the
+ *   dest   - Describes the rectangular region on the display that will
- *            the bit map.
+ *            receive the the bit map.
  *   src    - The start of the source image.
  *   origin - The origin of the upper, left-most corner of the full bitmap.
  *            Both dest and origin are in window coordinates, however, origin
@@ -291,9 +291,9 @@ void nxbe_bitmap_dev(FAR struct nxbe_window_s *wnd,
  *   and shadowed in the per-window framebuffer.
  *
  * Input Parameters:
- *   wnd   - The window that will receive the bitmap image
+ *   wnd    - The window that will receive the bitmap image
- *   dest   - Describes the rectangular on the display that will receive the
+ *   dest   - Describes the rectangular region on the display that will
- *            the bit map.
+ *            receive the the bit map.
  *   src    - The start of the source image.
  *   origin - The origin of the upper, left-most corner of the full bitmap.
  *            Both dest and origin are in window coordinates, however, origin
@@ -305,24 +305,30 @@ void nxbe_bitmap_dev(FAR struct nxbe_window_s *wnd,
  *
  ****************************************************************************/
 
-#ifdef CONFIG_NX_RAMBACKED
 void nxbe_bitmap(FAR struct nxbe_window_s *wnd,
                  FAR const struct nxgl_rect_s *dest,
                  FAR const void *src[CONFIG_NX_NPLANES],
                  FAR const struct nxgl_point_s *origin,
                  unsigned int stride)
 {
+#ifdef CONFIG_NX_RAMBACKED
   /* If this window supports a pre-window frame buffer then shadow the full,
    * unclipped bitmap in that framebuffer.
    */
 
   if (NXBE_ISRAMBACKED(wnd))
     {
+      /* Update the per-window framebuffer */
+
       nxbe_bitmap_pwfb(wnd, dest, src, origin, stride);
+
+      /* Overlay any update any sprites on the per-window frambuffer */
+
+      nxbe_sprite_refresh(wnd, dest);
     }
+#endif
 
   /* Rend the bitmap directly to the graphics device in any case */
 
   nxbe_bitmap_dev(wnd, dest, src, origin, stride);
 }
-#endif

graphics/nxbe/nxbe_filltrapezoid.c

@@ -250,11 +250,11 @@ static inline void nxbe_filltrapezoid_pwfb(FAR struct nxbe_window_s *wnd,
         break;
     }
 
-/* Copy the portion of the per-window framebuffer in the bounding box
+  /* Copy the portion of the per-window framebuffer in the bounding box
    * to the device graphics memory.
    */
 
-  nxbe_bitmap_dev(wnd, &relbounds, src, &origin, wnd->stride);
+  nxbe_flush(wnd, &relbounds, src, &origin, wnd->stride);
 }
 #endif
 

graphics/nxbe/nxbe_flush.c

@@ -0,0 +1,135 @@
+/****************************************************************************
+ * graphics/nxbe/nxbe_flush.c
+ *
+ *   Copyright (C) 2019 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ * 3. Neither the name NuttX nor the names of its contributors may be
+ *    used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <errno.h>
+#include <debug.h>
+
+#include <nuttx/nx/nxglib.h>
+#include <nuttx/nx/nxbe.h>
+
+#include "nxbe.h"
+
+#ifdef CONFIG_NX_RAMBACKED
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: nxbe_sprite_refresh
+ *
+ * Description:
+ *   Prior to calling nxbe_bitmap_dev(), update any "sprites" tht need to
+ *   be overlaid on the per-window frambuffer.  This could include such
+ *   things as OSD functionality, a software cursor, selection boxes, etc.
+ *
+ * Input Parameters (same as for nxbe_flush):
+ *   wnd    - The window that will receive the bitmap image
+ *   dest   - Describes the rectangular region on the display that was
+ *            modified (in device coordinates)
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
+#if 0 /* There are none yet */
+void nxbe_sprite_refresh(FAR struct nxbe_window_s *wnd,
+                        FAR const struct nxgl_rect_s *dest)
+{
+  /* Sprite support has not yet been implemented */
+}
+#endif
+
+/****************************************************************************
+ * Name: nxbe_flush
+ *
+ * Description:
+ *   After per-window frambuffer has been updated, the modified region must
+ *   be written to device graphics memory.  That function is managed by this
+ *   simple function.  It does the following:
+ *
+ *   1) It calls nxbe_sprite_refresh() to update any "sprite" graphics on top
+ *      of the RAM framebuffer.   This could include such things as OSD
+ *      functionality, a software cursor, selection boxes, etc.
+ *   2) Then it calls nxbe_bitmap_dev() to copy the modified per-window
+ *      frambuffer into device memory.
+ *
+ *   This the "sprite" image is always on top of the device display, this
+ *   supports flicker-free software sprites.
+ *
+ * Input Parameters (same as for nxbe_flush):
+ *   wnd    - The window that will receive the bitmap image
+ *   dest   - Describes the rectangular on the display that will receive the
+ *            the bit map.
+ *   src    - The start of the source image.
+ *   origin - The origin of the upper, left-most corner of the full bitmap.
+ *            Both dest and origin are in window coordinates, however, origin
+ *            may lie outside of the display.
+ *   stride - The width of the full source image in bytes.
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
+void nxbe_flush(FAR struct nxbe_window_s *wnd,
+                FAR const struct nxgl_rect_s *dest,
+                FAR const void *src[CONFIG_NX_NPLANES],
+                FAR const struct nxgl_point_s *origin,
+                unsigned int stride)
+{
+  /* Update any "sprite" graphics on top of the display.  These may have been
+   * damaged by the preceding framebuffer update.
+   */
+
+  nxbe_sprite_refresh(wnd, dest);
+
+  /* Copy the modified per-window frambuffer into device memory.  Since the
+   * "sprite" graphics were refreshed after the update, then should be no
+   * flicker as you see with a direct update of the device graphics memory.
+   */
+
+  nxbe_bitmap_dev(wnd, dest, src, origin, stride);
+}
+
+#endif  /* CONFIG_NX_RAMBACKED */
+

graphics/nxbe/nxbe_move.c

@@ -377,7 +377,7 @@ static inline void nxbe_move_pwfb(FAR struct nxbe_window_s *wnd,
    * framebuffer to the destination rectangle device graphics memory.
    */
 
-  nxbe_bitmap_dev(wnd, &destrect, src, &origin, wnd->stride);
+  nxbe_flush(wnd, &destrect, src, &origin, wnd->stride);
 }
 #endif
 

graphics/nxmu/nxmu_redrawreq.c

@@ -125,9 +125,9 @@ void nxmu_redrawreq(FAR struct nxbe_window_s *wnd,
             break;
         }
 
-      /* And render the bitmap */
+      /* And render the bitmap into device graphics memory */
 
-      nxbe_bitmap_dev(wnd, &wndrect, src, &origin, wnd->stride);
+      nxbe_flush(wnd, &wndrect, src, &origin, wnd->stride);
     }
   else
 #endif