A virtual screen means a display area greater than the physical size of the display. It requires additional video memory and allows instantaneous switching between different screens even on slow CPUs. If a virtual display area is configured, the visible part of the display can be changed by setting the origin.

The virtual screen support of emWin can be used for panning or for switching between different video pages.

Panning

If the application uses one screen which is larger than the display, the virtual screen API functions can be used to make the desired area visible.

Virtual pages

Virtual pages are a way to use the display RAM as multiple pages. If an application for example needs 3 different screens, each screen can use its own page in the display RAM. In this case, the application can draw the second and the third page before they are used. After that the application can switch very fast between the different pages using the virtual screen API functions of emWin. The only thing the functions have to do is setting the right display start address for showing the desired screen. In this case the virtual Y-size typically is a multiple of the display size in Y.

Requirements

The virtual screen feature requires hardware with more display RAM than required for a single screen and the ability of the hardware to change the start position of the display output.

Video RAM

The used display controller should support video RAM for the virtual area. For exam-ple if the display has a resolution of 320x240 and a color depth of 16 bits per pixel and 2 screens should be supported, the required size of the video RAM can be calculated as follows:

Size = LCD_XSIZE * LCD_YSIZE * LCD_BITSPERPIXEL / 8 * NUM_SCREENS
Size = 320 x 240 x 16 / 8 x 2
Size = 307200 Bytes

Configurable display start position

The used display controller needs a configurable display start position. This means the display driver even has a register for setting the display start address or it has a command to set the upper left display start position.

Configuration options

The virtual screen support configuration should be done in the file LCDConf.h. The table below shows all available configuration options:

LCD_SET_ORG

Description

This macro is used by the display driver to set the display start position of the upper left corner of the display.

Type

Function replacement.

Prototype

#define LCD_SET_ORG(x, y)

Example

#define LCD_SET_ORG(x, y) SetDisplayOrigin(x,y) /* Function call for setting the display start position */

LCD_VXSIZE, LCD_VYSIZE

Description

The virtual screen size is configured by the macros LCD_VXSIZE and LCD_VYSIZE. LCD_VXSIZE always should be > LCD_XSIZE and LCD_VYSIZE should be > LCD_YSIZE. If a virtual area is configured the clipping area of emWin depends on the virtual screen and not on the display size. Drawing operations outside of LCD_XSIZE and LCD_YSIZE but inside the virtual screen are performed.

Type

Numerical values.

Sample configuration

The following excerpt of the file LCDConf.h shows how to configure emWin for using a virtual area of 640x480 pixels on a QVGA display with 320x240 pixels:

#define LCD_SET_ORG(x, y) SetDisplayOrigin(x, y) /* Function call for setting the display start position */
#define LCD_XSIZE 320 /* X-resolution of LCD */
#define LCD_YSIZE 240 /* Y-resolution of LCD */
#define LCD_VXSIZE 640 /* Virtual X-resolution */
#define LCD_VYSIZE 480 /* Virtual Y-resolution */

Using virtual screens

Basic sample

The following sample shows how to use a virtual screen of 128x192 and a display of 128x64 for instantaneous switching between 3 different screens.

Configuration
#define LCD_XSIZE 128
#define LCD_YSIZE 64
#define LCD_VYSIZE 192

Application
GUI_SetColor(GUI_RED);
GUI_FillRect(0, 0, 127, 63);
GUI_SetColor(GUI_GREEN);
GUI_FillRect(0, 64, 127, 127);
GUI_SetColor(GUI_BLUE);
GUI_FillRect(0, 127, 127, 191);
GUI_SetColor(GUI_WHITE);
GUI_SetTextMode(GUI_TM_TRANS);
GUI_DispStringAt("Screen 0", 0, 0);
GUI_DispStringAt("Screen 1", 0, 64);
GUI_DispStringAt("Screen 2", 0, 128);
GUI_SetOrg(0, 64); /* Set origin to screen 1 */
GUI_SetOrg(0, 128); /* Set origin to screen 2 */

Output

The table below shows the output of the display:

Explanation	Display output	Contents of virtual area
Before executing GUI_SetOrg(0, 240)
After executing GUI_SetOrg(0, 240)
After executing GUI_SetOrg(0, 480)

Advanced sample using the window manager

The shipment of emWin contains a sample which shows how to use virtual screens in an application. It can be found under Sample\GUI\BASIC_VirtualScreens.c:

Screen 0	Screen 1

After showing a short introduction the sample creates 2 screens on 2 separate pages as shown above. The first screen shows a dialog which includes a graphical representation of 2 temperature curves. When pressing the ’Set color’ button, the application switches instantaneously to the second screen, even on slow CPUs. After pressing the ’OK’ button of the ’Adjust color’ dialog, the application switches back to the first screen.

Viewer Screenshot of the above sample

If using the viewer both screens can be shown at the same time. The screenshot above shows the visible display at the left side and the contents of the whole configured virtual display RAM at the right side.

Dialog sample using the window manager

Main screen/Page 0	Main screen/Page 1
Calibration screen/Page 2	About screen/Page 2

After a short intro screen the ’Main Screen’ is shown on the display using page 0. After the ’Setup’ button is pressed, the ’Setup’ screen is created on page 1. After the screen has been created, the application makes the screen visible by switching to page 1. The ’Calibration’ and the ’About’ screen both use page 2. If the user presses one of the buttons ’Calibration’ or ’About’ the application switches to page 2 and shows the dialog.

The viewer can show all pages at the same time. The screenshot above shows the visible display at the left side and the contents of the whole layer (virtual display RAM) with the pages 0 - 2 at the right side.