CommLCD engine

Comm-Engines.md

@@ -120,6 +120,136 @@ values:
     - `COMMLCD_UPDATE_ASYNC`: call `__commlcd_drv_update` asynchronously.
 * `fb`: The address of the frame buffer.
 
+#### Setting palette
+
+If the color depth of the video mode is less than 15 (`COMMLCD_PSEUDO_RGB332`),
+`__commlcd_drv_setclut` function will be called to set the palette.
+
+In our sample, this method does nothing and returns zero:
+
+    int __commlcd_drv_setclut (int firstcolor, int ncolors, GAL_Color *colors)
+    {
+        return 0;
+    }
+
+In practice, you should set the hardware palette (color look up table) in this
+method if the color depth of your video device is only 256-color.
+
+The arguments of this function have the following meanings:
+
+* `firstcolor`: The first color index (the palette entry index) should be set.
+* `ncolors`: The number of palette entries should be set.
+* `colors`: The array of `GAL_Color` which define the RGB triples for each
+    palette entries will be set.
+
+`GAL_Color` is a structure defined in MiniGUI header:
+
+    typedef struct _GAL_Color
+    {
+        /**
+         * The red component of a RGBA quarter.
+         */
+        gal_uint8 r;
+        /**
+         * The green component of a RGBA quarter.
+         */
+        gal_uint8 g;
+        /**
+         * The blue component of a RGBA quarter.
+         */
+        gal_uint8 b;
+        /**
+         * The alpha component of a RGBA quarter.
+         */
+        gal_uint8 a;
+    } GAL_Color;
+
+#### Update method
+
+If you specify the `update_method` to be `COMMLCD_UPDATE_SYNC` or
+`COMMLCD_UPDATE_ASYNC`, the update method `__commlcd_drv_update` will
+be called frequently or periodically.
+
+In our sample, this method save the whole frame buffer content to Windows
+bitmap files by calling MiniGUI function:
+
+    int __commlcd_drv_update (const RECT* rc_dirty)
+    {
+        char filename [PATH_MAX + 1];
+        struct timeval tv;
+
+        MYBITMAP my_bmp = {
+            flags: MYBMP_TYPE_RGB | MYBMP_FLOW_DOWN,
+            frames: 1,
+            depth: 32,
+            w: SCREEN_WIDTH,
+            h: SCREEN_HEIGHT,
+            pitch: PITCH,
+            size: FB_SIZE,
+            bits: sg_fb
+        };
+
+        printf ("__commlcd_drv_update called (%d, %d, %d, %d)\n",
+                rc_dirty->left, rc_dirty->top,
+                rc_dirty->right, rc_dirty->bottom);
+
+        gettimeofday (&tv, NULL);
+        sprintf (filename, "screenshot-%d.%d.bmp", (int)tv.tv_sec, (int)tv.tv_usec);
+        SaveMyBitmapToFile (&my_bmp, NULL, filename);
+        return 0;
+    }
+
+Note that, you can not call MiniGUI GDI functions here to draw something to
+screen.
+
+In practice, you may need to send an `ioctl` command to your video device driver
+to update the content in our frame buffer to the real LCD controller.
+
+For example, if you use SPI
+to connect a LCD screen, you may create an off-screen frame buffer in memory,
+and transfer the pixels to the LCD controller via SPI.
+
+The argument `rc_dirty` contains the dirty rectangle, i.e., the rectangle need
+to be updated to the real frame buffer or LCD controller.
+
+Generally, you should set `update_mothod` to be `COMMLCD_UPDATE_ASYNC` in
+`__commlcd_drv_init` method, and the method will be called asynchronously
+in a different thread, about 20 times per second.
+
+If you set `update_mothod` to be `COMMLCD_UPDATE_SYNC`, this update method
+will be called synchronously when there is any update of the frame buffer.
+For example, you call the MiniGUI function `SetPixel` to draw just one pixel
+on the screen. Therefore, this will reduce the refresh performance of the
+entire system. However, if you use MiniGUI's
+[Synchronous Update Mechanism](https://github.com/VincentWei/minigui/wiki/Sync-Update),
+it will be better to set `update_mothod` to be `COMMLCD_UPDATE_SYNC`.
+
+If you can access the LCD frame buffer directly, and your LCD screen
+do not need a refresh/update operation, you do not need to implement
+the update method, and the function can just return zero:
+
+    int __commlcd_drv_update (const RECT* rc_dirty)
+    {
+        return 0;
+    }
+
+If you specify the `update_mothod` to be `COMMLCD_UPDATE_NONE` in
+`__commlcd_drv_init` method, this function will be never called.
+
+#### Releasing the engine
+
+When MiniGUI quits, it will call `__commlcd_drv_release` to release
+the resource allocated or created by the engine.
+
+In our sample, it destroys the anonymous memory map and returns zero:
+
+    int __commlcd_drv_release (void)
+    {
+        munmap (sg_fb, FB_SIZE);
+        return 0;
+    }
+
+
 ### Comm IAL engine
 
 ## Summary