minigui-docs/programming-guide/MiniGUIProgGuidePart5Chapter03.md

GAL and IAL Engines

In the development of MiniGUI version 0.3.xx, we introduce the concepts of Graphics and Input Abstract Layer (GAL and IAL). Abstract layer is similar to Linux kernel virtual file system. It defines a group of abstract interfaces that do not rely on any special hardware. All top-layer graphics operations and input handling are based on abstract interfaces. The code used to realize the abstract interfaces are called graphic engine and input engine, similar to the driver of operating system. Actually it is an object-oriented programming technology. By using this abstract interface, we can easily port MiniGUI to other operating systems. Generally speaking, Linux-based embedded system kernel will provide FrameBuffer support, thus existed FBCON graphics engine of MiniGUI can run on normal PC, and also can run on special embedded systems. Therefore, we usually do not need to develop a graphics engines for special embedded devices, but use FBCON graphics engine. At the same time, MiniGUI also offers Shadow and CommLCD GAL engines for different situations. There will be simple introduction in the first and second sections of this chapter.

Compared to graphics engine, it is more important to separate the bottom input handling and top input handling of MiniGUI. In Linux-based embedded systems, graphics engine can get from FrameBuffer, while input device does not have the uniformed interface. We usually use keyboard and mouse on PC, but we may only use touch screen and keypad on embedded systems. Considering this situation, we have to say that it is very important for MiniGUI to provide an abstract input layer.

Therefore, the following sections will introduce Custom IAL interface of MiniGUI 3.0, and focus on how to develop an input engine (Custom IAL).

Shadow NEWGAL Engine

The main functions of this engine are:

• Support for asynchronous update of graphics device, such as YUV output, indirect access to FrameBuffer, etc.
• Support for display modes of lower than 8-bpp on NEWGAL. At present, it can support all kinds of display modes of QVFB and all packed-pixel modes of FrameBuffer console.

When configure rotating screen, Shadow engine can be configured in MiniGUI.cfg as follow:

• real_engine Real engine, it means the name of device which draws graphic. Here is pc_xvfb
• defaultmode Default display mode
• rotate_screen Whether or not rotate the screen when virtual screen is draw on real screen. If so, how to rotate. It has the following values:
• normal Don't rotate
• cw Rotate it 90 degrees clockwise
• ccw Rotate it 90 degrees counterclockwise
• hflip Flip horizontal
• vflip Flip vertical

When configure N (N is lower than 8) bits per pixel display mode, Shadow engine can be configured in MiniGUI.cfg as follow:

• shadow engine's color depth is greater than 8, so real engine's color depth configuration (more than or equal to 8) is real color depth.

MLShadow GAL Engine

MLShadow engine implements multi-display-layer in many product solutions, such as set-top box and PMP. Multi-display-layer is similar with overlay display layer which is provided by hardware, it can implement transparence/translucent display between layers.

MiniGUI provides the operation functions on virtual graphic layer in MLShadow engine to implement controls for different graphic layers.

This function can get corresponding graphic layer, and set this graphic layer's offset, blend flag, transparent color, alpha and overlay order relative to real graphic layer by given dc_mls argument. The details of arguments are as follow:

• dc_mls the corresponding DC handler of graphic layer
• mask To determine which properties should be set, ignore passed other properties's value. For example, only set offset_x and offset_y when mask = MLS_INFOMASK_OFFSET; set all properties when mask is MLS_INFOMASK_ALL. The range of mask's value is:
• MLS_INFOMASK_OFFSET only set offset of display layer
• MLS_INFOMASK_BLEND only set blend flag of display layer
• MLS_INFOMASK_ZORDER only set overlay order of display layers
• MLS_INFOMASK_ENABLE only set whether display layer is visible
• MLS_INFOMASK_ALL set all properties
• offset_x and offset_y set offset of given display layer on main screen
• blend_flag To show the display layer is transparent or has alpha channel, flags can be:
• MLS_BLENDMODE_COLORKEY Remove transparent color when blending.
• MLS_BLENDMODE_ALPHA Remove alpha blend when blending.
• color_key value of transparent color
• alpha value of alpha channel
• z_order overlay order, z_order is greater, display layer is wider.

This function gets overlay information of display layer which is given by dc_mls. mask means to get all or partial information, its value has been explained in argument description of mlsSetSlaveScreenInfo.

This function set whether display layer which is give by dc_mls is visible. In other words, it means whether or not participate overlay operation of display layer. It is visible (invisible) when enable is TRUE (FALSE).

pc_xvfb GAL Engine

This engine's main functions are:

• Using unified parameters startup options, so MiniGUI can start xvfb automatically when it is initializing.
• Using unified shared memory ???, so pc_xvfb engine can use same key value to get framebuffer's system shared memory instance without caring about using Qt vfb, Window vfb or Gtk+ vfb.
• Using unified pipe/Unix socket object and input data transfer protocol, so pc_xvfb input engine can use same mechanism to get the data which is entered by user in the window without caring about using Qt vfb, Window vfb or Gtk+ vfb.

Configurations of pc_xvfb engine in MiniGUI.cfg are as follow:

• defaultmode Default display mode
• window_caption The text of window caption
• exec_file Executable file of virtual framebuffer program. For qvfb, it is qvfb2. wvfb2 is for wvfb. mvfb2 is for mvfb.

rtos_xvfb GAL Engine

By using of rtos_xvfb engine, we can run MiniGUI on an exist GUI of RTOS, such as uC/GUI, Gtk+ and Tilcon. The principle is as follows:

• rtos_xvfb program model creates window, allocates virtual frame buffer, and starts MiniGUI application with thread mode, so that MiniGUI application can be draw on virtual frame buffer.

APIs of Creating and destroying virtual frame buffer are as follow:

• Store input data which is generated by rtos_xvfb engine in ring buffer refers to agreed standard. rtos_xvfb input engine of MiniGUI provides related interfaces:
• The interfaces of creating and destroying ring buffer

• Put input event into ring buffer and notify rtos_xvfb engine to read function interface.

The configuration of rtos_xvfb in MiniGUI.cfg is quite simple. Only need to set default display mode as follow:

CommLCD NEWGAL Engine

This engine provides the support for direct access to LCD FrameBuffer (video memory) on conditional real-time operation systems like VxWorks, Nucleus, uC/OS-II, and eCos. The LCD’s pixel format should be above 8-bpp (bits-per-pixel), and in packed-pixel mode.

In every sub-drive of CommLCD, we need to implement the following interfaces according to the operating system and lower-level API.

• __commlcd_drv_init function is used to initialize the LCD device.
• __commlcd_drv_release function is used to release the LCD device.
• __commlcd_drv_getinfo function is used to get information of the LCD device.
• __commlcd_drv_setclut is used to set color palette.

The structure commlcd_info is defined as follows:

Sub driver implementation sample is as follow:

---++18.6 Comm Input Engine MiniGUI为传统嵌入式操作系统提供了Common输入引擎（comm），使用该引擎可以很方便地实现对键盘、鼠标或触摸屏等输入设备的支持。

MiniGUI provides comm IAL for conditional real-time operation systems like VxWorks, Nucleus, uC/OS-II, and eCos. Based on this engine, you can easily add the support for input device such as keyboard, mouse, and touch screen.

The comm ial engine needs the OS or low-level device driver to provide five functions as follows:

• __comminput_init is used to initialize the input device.
• __comminput_deinit is used to release the input device.
• __comminput_ts_getdata get the input data of the touch screen. The "x" and "y" returns the position data, and "button" returns the pressed state (if pen is pressed, return a non-zero value). It returns 0 while getting data successfully, otherwise returns -1.
• __comminput_kb_getdata gets the input data of the keyboard. "key" returns the key code of corresponding key; "status" returns the key status (1 for key-down, 0 for key-up). _comminput_kb_getdata returns 0 while getting data successfully, otherwise returns -1. The key code here is the MiniGUI-defined scan code of a keyboard key. The low-level keyboard driver needs to translate a keyboard scan code to a corresponding MiniGUI key code and return this key code.
• __comminput_wait_for_input enquires whether there are input data. If no input events comes, this function returns 0; if mouse events or touch screen events comes, the return value's first position is set to 1; if keyboard events comes, the return value's second position is set to 1. The control of the external events in MiniGUI is implemented as a single system thread. This event thread sleeps while no external events come. So, __comminput_wait_for_input should provide a waiting mechanism, such as using semaphore. __comminput_wait_for_input waits on an input semaphore while enquiring about input data, and makes the MiniGUI input task which calls this function go to sleep. When input events come, the low-level drivers (or interrupt routines) should post a semaphore to wake up the MiniGUI event task.

When migrating MiniGUI to new hardware, we need to implement the above five functions interface according to OS or hardware driver.

MiniGUI 3.0专业版和标准版的输入和输出引擎都是飞漫软件定制实现的，当然如果客户需要自己定制IAL的话，我们也可以提供custom-ial的库由客户自定义ial引擎接口的实现。按照下面的方法编写好IAL源代码后，要将该源代码编译生成一个ial 库，最后将实例、minigui 库和 ial 库一起编译，才可以生成正确的可执行文件。

Input and output engines of MiniGUI 3.0 standard/professional edtion are customized by Feynman software. Feynman can also provide custom-ial library to help custom implement customized ial engine interface if custom wants to customize IAL. Custom needs to compile IAL codes into a ial library, then get executable file by compiling application, minigui library and ial library together.

Custom input engine provides user message handle interfaces of customized keyboard and mouse. User can handle message after implements the following interfaces:

When we need to customize input engine for specified embedded device, firstly, set value for member of input engine structure in initializing function. These members are function pointers, they are called by MiniGUI's upper-level to get input device's status and data. Definition of INPUT structure is as follow:

These members' function are:

• update_mouse inform bottom-layer engine to update new mouse information
• get_mouse_xy calling this function by upper-layer to get x and y coordinates of mouse
• set_mouse_xy calling function by upper-layer to set the new mouse position. For those engines not supporting this function, the member can be null.
• get_mouse_button get mouse button state. Return value can be IAL_MOUSE_LEFTBUTTON, IAL_MOUSE_MIDDLEBUTTON, IAL_MOUSE_RIGHTBUTTON to respectively represent the pressed states: mouse left key, middle key, and right key.
• set_mouse_range set range of mouse movement. For engines not supporting this function, can be set as NULL.
• update_keyboard inform bottom-layer to update keyborad information
• get_keyboard_state get keyboard state, return a byte array, including keyboard pressed state indexed by scan code. Pressed is 1, released is 0.
• suspend_keyboard pause keyboard device read/write, used for switch of virtual console. Ususally set as NULL for embedded device.
• resume_keyboard resume keyboard device read/write, used for switch of virtual console. Ususally set as NULL for embedded device.
• set_leds set keyboard status LEDs, used for CapLock, NumLock, and ScrollLock statues.
• wait_event calling this function by upper-layer to wait for an event from input devices. This function has different interfaces for MiniGUI-Threads and MiniGUI-Processes, and must implement with select or poll system calls.

Custom IAL enginee sample

Actually developing a new IAL engine is not difficult. We use iPAQ as an example to illustrate the design of a customized input engine.

IPAQ produced by COMPAQ is a StrongARM-based high-end hand-held product, which includes touch screen and several control keys. The touch screen is similar to the mouse of PC, but it can only differentiate left button. For the control keys, we can emulate them as some keys in PC keyboard, such as cursor keys, ENTER key, and function keys. The source code of this engine is showed in List 1.

List 2 The customized input engine for iPAQ (custom IAL)

We now analyze how some important interface functions implement:

• The function IInitCustomInput is the initializing function of input engine defined in customial.h of MiniGUI 3.0. This function opens two devices: /dev/h3600_ts and /dev/h3600_key. The former is the device file for touch screen; the latter is the device for control keys. They are similar to device /dev/psaux and device /dev/tty on PCs. After successfully opening these two device files, the function sets INPUT structure and other members, some of which is assigned with NULL.
• The function mouse_update returns 1, indicating that the mouse state is ready.
• The function mouse_getxy returns mouse position data prepared by other functions and performs proper boundary examination.
• The function mouse_getbutton returns touch screen state, that is, whether the user have touched the screen. It is similar to whether the user has pressed the left button of mouse.
• The function keyboard_update properly fills state array according to the keyboard information prepared by other functions.
• The function keyboard_state directly returns the address of state array.
• The function wait_event is the core function of the input engine. This function first combines the two opened device file descriptors within the descriptor set in. Then it calls select system call. When the value returned by select is more than 0, this function will examine if there is any readable data waiting to read in the two file descriptors, if so, it will read touch screen and key stroke data separately from the two file descriptors.

-- Main.XiaodongLi - 07 Nov 2009

---

<< | Table of Contents | >>