Facebook Pixel

AN-00074 ViSi Images and User Images

Description This application note is intended to demonstrating to the user the usage of the image and user image widgets in ViSi.
Supported Processor PICASO, DIABLO16
Supported Environment ViSi
Difficulty Medium


File Downloads


This application note is intended to demonstrating to the user the usage of the image and user image widgets in ViSi.

Before getting started, the following are required:

and other superseded modules which support the ViSi Genie environment


Visit www.4dsystems.com.au/products to see the latest display module products that use the Diablo16 processor. The display module used in this application note is the uLCD-32PTU, which is a Picaso display. This application note is applicable to Diablo16 display modules as well.

for non-gen4 displays(uLCD-xxx)

for gen4 displays (gen4-uLCD-xxx)

When downloading an application note, a list of recommended application notes is shown. It is assumed that the user has read or has a working knowledge of the topics presented in these recommended application notes.

  Application Overview

This application note is intended to demonstrating to the user the usage of the image and user image widgets in ViSi.

Setup Procedure

For instructions on how to launch Workshop 4, how to open a ViSi project, and how to change the target display, kindly refer to the section “Setup Procedure” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16

Create a New Project

For instructions on how to create a new ViSi project, please refer to the section “Create a New Project” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16


  Design the Project

The ViSi environment Digits is a group of customizable widget from the Workshop IDE – ViSi environment. These objects allow the addition of a single images or a group of images.  The image and user images widget can be found in the Widgets Menu >> Systems/Media tab.


Images can be very useful in different applications like graphic user interfaces. It can also serve as a visual aid for users. Adding images in a project made in the ViSi environment is fairly simple. To add a single image to the project click on the Image objects icon.


After clicking on this icon a pop-up window will appear. This window will ask the user to locate and open the image files that are to be added in the project.


** Click on the ‘Open’ to add the image file to the project.

After the addition of the image file, the Object Inspector will display the filename of the image.  The image can now be positioned on the display module according to the user’s preference.

On the event that a group of images needs to be added to a project, the User Images object is the best choice. The User Images allows addition of several images all at the same time and addition afterwards.


When a User Image object is first added in the project form, a broken line boarder is seen. Adding the images to the object is done is the Object Inspector properties.

Clicking on the ‘Images’ will open a new window. This new window enables the user to locate the images that are to be added into the project.


After clicking the ‘Add’ button, another window will appear enabling the user to locate the images. Several files can be selected at the same time and be added to the project. Clicking open will then result to the enlisting of the image files in the ‘Image List Editor’  window.


After all the files are added, the images can be arranged using the up/down button. The number on the first column identifies the frame number of the image file. Hitting the ‘OK’ button finalizes the addition and arranging of images.


Going back to the Object inspector, the once empty ‘Images’ options will now be populated with the image filename and location similar to the image show below.


Following all the steps discussed herein will have the ‘User Image’ objects ready for use in the coding area.


The ViSi-based Image and User Image application

The aim of this application is to demonstrate the manner of how to use the Image and User Images object of the Workshop IDE.

 After all the objects have been laid-out, let’s continue with the other half which involves the coding of the project. This will be presented in a sectional manner so as not to create confusion with the project. For an in-depth detail of the functions used in this application note please refer to the DIABLO16 Internal Functions Reference Manual.

The Include Section

This project starts with the identification of the platform being used as declared by the #platform function. For the program to be able to function properly files are included herein using the #inherit function. Three other files are included automatically during creation of the new project, namely:  4DGL_16bitColours.fnc, the VisualConst.inc, and user_imgConst.inc.  Notice that the last include file is almost the same as the project filename. This file is automatically generated as soon as project saving is done.


The Main Program

The main program for this projects contains several sections: the initialization and the mounting of the micro-SD card, the initial displaying of the image objects, and a continuous repeat-forever loop.  The main aim of the repeat-forever loop is to create an ‘animated eye’ for the image.


The micro-SD Initialization

Let’s start with the initialization of the uSD card. The uSD card contains all the image information about the objects used in the project. The object information and data are saved under a *.DAT and a *.GCI filename extension which is copied to the uSD during project compilation. Mounting of the disk in this application note was done using the following set of program statements.


When starting a new project in the ViSi environment these set of statements are already included in the coding area. The last part of these set of statements uses a function file_LoadImageControl() to call on the object data/information files on the uSD drive. This initializes the data to be called in using the variable ‘hndl’.  In addition, the filenames for the dat and gci files are automatically changed to the project filename as soon as the project is saved.

Added to the statements above are the screen orientation setup function and the      touch enable function. The screen orientation is set to portrait thereby providing an 800x480 pixel dimension. This setup is attained using the gfx_Set() function.

Having been able to load and initialize the uSD drive, the processor is now able to access the information stored therein. As mentioned from the previous section, the filenames with an extension of DAT and GCI has the image data and information.  Therefore, the next part of the main program is to display all the objects that were placed on the Workshop IDE form viewer.

A special button from the Object Inspector can help reduce the time of coding of this part. The ‘Paste Code” simply pastes object code.


Displaying the Objects

In this part of the program, the img_Show() function simply calls out the object image and information found in the microSD drive.  This set of statements call out the images from their handlers and are displayed on screen. Observe the characters with the green font colours. This denotes the available object frame numbers available for the particular User Image object.


The Repeat-forever Loop

This section of the main program contains statements that are continually run by the processor.  For this project, a simple change in frame number is made. The change in frame numbers added with instances of pause() functions produces a simply user image ‘animated’ result. This program should result to the penguin image’s eyes open/close animation.


There are a total of five different frames added to each of the User Images in this project demonstration. Changing the second frame number between 2 to 4 will yield to different eye animation results.


Run the Program

For instructions on how to save a ViSi project, how to connect the target display to the PC, how to select the program destination (this option is not available for Goldelox displays), and how to compile and download a program, please refer to the section “Run the Program” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16

The uLCD-32PTU and uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other displays.