diff --git a/Comm-Engines.md b/Comm-Engines.md index bb3bc68..91bb987 100644 --- a/Comm-Engines.md +++ b/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