Using the Renesas Graphics API to Create a User Interface_Part2_LabProcedure

LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 1 of 10

Graphics Lab: Using the Renesas Graphics API to
Create a User Interface – Part 2

RX TFT-LCD Solution
Description: This objective of this lab session is to introduce you the Renesas Graphics API
(GAPI) and associated application framework. We will start with an introduction to frame based
graphics and basic GAPI calls, than move to more advanced GAPI calls and framework details,
and finally an example of a user interface screen design process. Starting with concept artwork,
we will work through the components required to create a user interface, discusses details
about behavior, and illustrate how the embedded graphics are generated. Finally, we will
implement the user interface on a low-cost embedded system platform.

Lab Sections
3 Create Graphical Resource Files 2
4
Create New Screen 5
5
Creating Interaction with the Screen 9


Lab Objectives
1. Learn a method to create GUI graphics
2. Use GAPI and application framework on an
embedded platform to create a user
interface.
3. Understand callback function interaction.

Skill Level

1. Familiarity with the HEW IDE and debuggers
Time to Complete Lab
160 Minutes
Lab Materials
Please verify you have the following materials at
your lab station.
• HEW v4
• RX Standard Toolchain v1.2
• E1 debugger
• Inkscape and ImageMagick software
•
RX62N based Serious SIM205
LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 2 of 10

3 Create Graphical Resource Files
Overview:
In this lab we’re going to extract components from an SVG (Scalable Vector Graphics) file and make
component BMP (bitmap) files that are compatible with GAPI.

Procedural Steps
Step 3.1 Open the “Medical.svg” file in the
“C:\Workspace\5L08I_Graphics_API\Lab3_Graphical_Resources” directory by double clicking it.
This file will open in “Inkscape” (an open source SVG editor).
Press “5” to center and display the image.

Step 3.2 To help “clear our plate”, delete all text by selecting and pressing “delete”.
Text will be inserted at runtime by the application code.

Unlike many programs, to select multiple items in Inkscape, hold down

the “shift” key while selecting.
To make selection easier, you can view the SVG in “outline mode”.
Enter outline mode by “<alt>-V, D, O”. Exit outline by “<alt>-V,D,N”
LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 3 of 10




Step 3.3 Looking at the image in outline mode, we can see there are duplications of some
components…so let’s delete them so we don’t have to consider them separately.


Step 3.4
We are now going to export each of the individual components as separate “bitmap” files to
facilitate converting them to BMP files for GAPI usage.

- To create these component “bitmap” files:
1. Select all objects except for the background image and the slider bar (overlapping images
are a problem for the export operation). You should have eight objects selected (slider bar and
slider button are separate objects).
2. Open the export dialog by pressing <ctrl-shift-E>
You can “drag” a box to select multiple items. Only items completely
within the box will be selected.
LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 4 of 10

.
Check “batch export…” and “hide all ” boxes, and press export.

3. Now, select just the background image and export, select just the slider bar and export.
Ensure that “Hide all except selected” is checked in each case.
4. Inkscape has exported these component images as “.png” files into
the “C:\Workspace\5L08I_Graphics_API\Lab3_Graphical_Resources” directory. You can use
Windows Explorer to view these files in a thumbnail view.
Step 3.5

5. At this point, we are done with Inkscape and you can close it <alt-F4> (there is no reason
to save the modified SVG file).
Renesas GAPI does not handle “.png” files, so we need to convert these exported files to a
format that can be properly used by GAPI. To do this, we will use an open source tool called
“ImageMagick”.

Run the “ConvertMed.bat” file located in
the
Step 3.6
“C:\Workspace\5L08I_Graphics_API\Lab3_Graphical_Resources” by double clicking on it
from Windows Explorer.

Examine the command lines being used to convert the files into GAPI compatible images. We
will discuss these in some detail after the lab. You can use Windows Explorer to view these
generated files in a thumbnail view.
Step 3.7
To create the fonts that will be used by our screen, we will use the GAPI font generation tool.
1. Open Windows Explorer and navigate to the
“C:\Workspace\5L08I_Graphics_API\Lab3_Graphical_Resources” directory.
2. Run the “CreateFont.bat” by double clicking.
3. Note how the batch file invokes the font generator 4 times creating 4 font files rendered at 14,
18, 24 and 42 pixels (the 24 and 42 pixel font are rendered bold).
4. Close the command window by pressing any key.

5. In Windows Explorer, you will see the four newly created “.efnt” font files.


PLEASE WAIT. WE WILL CONTINUE AS A GROUP.

Lab 3 Questions:
1. What are several advantages and disadvantages to building the screen
at runtime from components (as opposed to pre-rendering the
information into the bitmaps)?
LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 5 of 10

4 Create New Screen
Overview:
In this lab section, we will place our new objects on the screen, and ensure their appearance meets our
needs. Because of time constraints, we have provided a basic screen file that we will examine and
enhance.

Procedural Steps
Step 4.1 Open the HEW workspace “DirectLCD.hws” in the “Lab4_Create_Screen” directory by double-
clicking the file from within Windows Explorer.
C:\Workspace\5L08I_Graphics_API\Lab4_Create_Screen\DirectLCD.hws
Step 4.2
Step 4.3
SIM205 hardware should be assembled, connected to power, switched on and the E1 should
be plugged into the PC. The connection dialog should automatically launch (if not, please
initiate by pressing “<alt-D>,N”). Select “OK” on the dialogs until connected.
Step 4.4
Ensure the code has been built by pressing “F7”
Step 4.5

Download the “DirectLCD.abs” module by double-clicking in workspace panel or by pressing
“<alt-D>,W,A”.
Now download the resources.bin file that was generated as part of the build process by running
a script from the debug console by pressing the “play” button on it.

This process will also start the application running. You should see the “resource load” screen
on the LCD panel, followed by the “home” screen.
Step 4.6

By pressing the “Medical Icon” button on the display we will enter our “screen”. Note that
currently only the background image is shown. Stop the program by pressing “<alt-D>,H”.
Open the “ScreenMed.c” file (should be open in tab on main window, if not double-click the file
in the Workspace pane). You can also navigate the following by selecting the navigation tab in
LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 6 of 10

the Workspace pane (ensure “group by file” is selected).


Step 4.7

Locate the constructor function (by searching using <ctrl-H> or by using the navigation pane).
This function is registered with the framework (via the “ScreenMedicalData” structure) to be
called to initially build the screen. Here you can see the “FileFind” framework call to locate the
“Med_BG” bitmap file and pass it to the “R_expand_jpeg” API function to display the image at
the 0,0 screen location.
You can also see the call the framework “BasicConstructor”. This call will process all screen
objects within the “Icons” table (also registered within the “ScreenMedicalData” structure).
Currently there are no screen objects in this table (hence nothing on the screen).
Constructor Function

static void Constructor(Screen_t const *pS)
{
/* Clear the background */
{
/* LAB1_10: expand a jpeg file */
uint8_t const *pJPG = FileFind(pResources, "Med_BG");
int32_t width = R_BMP_Width(backFrameBuf);
int32_t height = R_BMP_Height(backFrameBuf);
R_init_jpeg();
R_expand_jpeg(pJPG,
FileSizeFind(pResources, "Med_BG"),
(uint16_t *)(((uint8_t *)backFrameBuf) + R_BMP_Offset(backFrameBuf))+(width*(height-1)), -width);
}

// Run default behavior
BasicConstructor(pS);
}
Step 4.8
/* MUST INCLUDE NULL TERMINATED RECORD */
Locate the Icons table by pressing <ctrl-F> and searching for “Icons”. Note that currently we
have much of the initialization excluded by “#if 0”. Change the 0 to a 1 to allow the code to
build (you can try running the code by pressing <F7> to build and <shift-F5> to run to see what
our screen currently looks like.
static const ScreenObj_t Icons[]=
{
/* Bit map Address Color Scheme Function call X Pos Y Pos */
#if 0
{ &pBMP_HomeIcon, T_HomeButtonScheme, ButtonBack, 418, 236 },
{ &pBMP_ButtonS, T_CalendarScheme, TimerRTC_Display, 10, 240 },
…

{ &pBMP_Mode, T_ButtonScheme, MedModePress, 278, 130 },
{ &pBMP_StartStop, T_ButtonScheme, MedStartStopPress, 344, 130 },
{ &pBMP_ONOFF, T_ButtonScheme, MedONOFFPress, 410, 130 },
{ &pBMP_Status, T_StatusScheme, MedStatus, 278, 176 },
#endif
{ NULL, NULL, NULL, 0, 0 },
};


LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 7 of 10

Step 4.9

Use the following diagram to note the relationship between the “Icons” table and our screen
objects (dimensions are pixels).
Touch the buttons and slider, note their behavior.
Note that the “Run/Stop” button definition is incomplete, we will address that next.
Step 4.10
Step 4.11
The objects are being displayed because they are being called by the framework (via the Icons
table registered callback functions).
Scroll down through the screen callback functions within “ScreenMed.c”.
Note the calls to the framework handlers “ButtonHandler”, ”SliderHandler”, and
“DataBoxHandler”.
These handlers are just conveniences that eliminate recreation of common behavior for some
generic objects.

static int16_t state=0;
Locate the “MedStartStopPress” callback function. Note the code that is currently conditionally

excluded. Using the framework calls “FileFind” and “ButtonHandler” greatly simplify the code
necessary to insert this object on the screen.

/* locate the BMP resources */
if (NULL == pBMP_StartStop)
{
pBMP_StartStop= FileFind(pResources, "MedButton");
}

if(0 != (state = ButtonHandler(pS, pMsg, (uint8_t *)StateText[MedState], state)))
{
if (ME_PRESS == pMsg->event)
{
MedState = (0 == MedState)? 1: 0;
}
}


LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 8 of 10

Step 4.12
Step 4.13
Include the code for the start/stop button by changing to “#if 1”. Test by building <F7> and
running <shift-F5>.
Step 4.14
Stop the program by pressing “<alt-D>,H”.
When you have completed this lab section, please close HEW by pressing <alt-F4>.
Step 4.15

PLEASE WAIT. WE WILL CONTINUE AS A GROUP.

Lab 4 Questions:
1. Where in the source code are the six “data boxes” being handled?
2. What would be another candidate for a “handler” looking at the source
in this example?
LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 9 of 10

5 Creating Interaction with the Screen
Overview:
In this lab section we’re going to add some interaction to our callback functions. In this section, hints are
available at the end of the “ScreenRefrig.c” file that can be referenced as necessary.

Procedural Steps

Step 5.1 Open the HEW workspace “DirectLCD.hws” in the “Lab5_Interaction” directory by double-
clicking the file from within Windows Explorer.
C:\Workspace\5L08I_Graphics_API\Lab5_Interaction\DirectLCD.hws
Step 5.2
Step 5.3
SIM205 hardware should be assembled, connected to power, switched on and the E1 should
be plugged into the PC. The connection dialog should automatically launch (if not, please
initiate by pressing “<alt-D>,N”). Select “OK” on the dialogs until connected.
Step 5.4
Ensure the code has been built by pressing “F7”
Step 5.5
Download the “DirectLCD.abs” module by double-clicking in workspace panel or by pressing
“<alt-D>,W,A”. Run the project by pressing “<shift>F5”, this is the state we left it in lab 4.

Step 5.6
To add some interaction, we are going to simulate data values for the graph and data boxes in
a separate thread. Additionally, we are going to request updates to several of the objects on a
periodic basis via another thread.
Rather than creating RTOS threads that will only be used in a single screen, the framework has
allocated several threads that can be shared by multiple screens (activated when necessary).
Within the constructor function of the “ScreenMed.c” file, change “#if 0” to “#if 1”.

Test by building <F7> and running <shift-F5>.
Step 5.7
Examine the “genData” (simulated data) and “genEvents” functions (periodic event generation).
The “MedInc” array in “genData” is controlling the amount that each data variable is
incremented per time tick, the “heartbeat” array contains the simulated data for the graph.
The “EventValues” array in “genEvents” contains the values used to signal the screen objects
that they should update.
Step 5.8
Press and hold the slider (note the graph waveform), hold and move the slider.
Press the “Run” button (note slider behavior)
Press the “Mode” and “Power” Buttons and note the behavior.
In the “MedStatus” callback function, change the “FileFind” name argument "
Step 5.9
MedStatusBox" to
"StatusBox"
Test by building <F7> and running <shift-F5>.
Using the code in the “genData” function as a template, control LED 2 based on the state of the
“Power Button”. Hint, this code can be done in the MedONOFFPress Callback or the “genData”
// Run default behavior
BasicConstructor(pS);
#if 0
(void)ScreenTaskStart(genData);

(void)ScreenTaskStart(genEvents);
#endif
LAB PROCEDURE
Using the Reneas Graphics API to create a user interface V1.0 Page 10 of 10

function based on the “GraphState” variable.
Test by building <F7> and running <shift-F5>.
Step 5.10
Step 5.11
Stop the program by pressing “<alt-D>,H”.
When you have completed this lab section, please close HEW by pressing <alt-F4>.
Step 5.12

PLEASE WAIT. WE WILL CONTINUE AS A GROUP.
Lab 5 Questions:
1. What happens if you use the FileFind framework call to search for a
resource and it is not located?