APPLICATION NOTE

Application Note: 4D-AN-P3005

Visi - Adding Image and Video Objects

Document Date: 8th June 2013

Document Revision: 1.0

4D SYSTEMS

4D-AN-P3005

Description

Content

This Application Note shows how to add image and video objects in ViSi.
Before getting started, the following are required:

Any of the following 4D Picaso display modules:

uLCD-24PTU
uLCD-28PTU
uLCD-32PTU
uLCD-32WPTU
uLCD-43(P/PT/PCT)
uVGA-III
other superseded modules which support the Visi environment

Description ............................................................................................. 2
Content .................................................................................................. 2
Application Overview .............................................................................. 3
Launch Workshop 4................................................................................. 3
Create a New Project .............................................................................. 4
Create a New Project ....................................................................... 4
Select ViSi ........................................................................................ 5
Design the Project ................................................................................... 5
Program Skeleton ............................................................................ 5
Uncomment the Necessary Parts

4D Programming Cable or uUSB-PA5

micro-SD (SD) memory card
Workshop 4 IDE (installed according to the installation
document)

Image Object ................................................................................... 7

Create an Image Object in the WYSIWYG Screen

Insert the Image Object Code

Save the Program for Compilation and Downloading

How to Compile and Download

Video Object .................................................................................. 10

Create a Video Object in the WYSIWYG Screen

10

Video Frames

11

Insert the Video Object Code

11

A Simple Example

13

Workshop Sample Programs .......................................................... 13

2013 4D Systems

Page 2 of 15

www.4dsystems.com.au

4D SYSTEMS
Proprietary Information ........................................................................ 15

4D-AN-P3005

Application Overview

Disclaimer of Warranties & Limitation of Liability................................... 15

It is often difficult to design a graphical display without being able to see

the immediate results of the application code. 4D-ViSi is the perfect
software tool that allows users to see the instant results of their desired
graphical layout. Additionally, there is a selection of inbuilt dials, gauges
and meters (called widgets) that can simply be dragged and dropped onto
the simulated module display. From here, each can have properties edited
and at the click of a button, all relevant code is produced in the user
program.
This application note explains how to create image and video objects in the
WYSIWYG screen, how to insert the generated object codes into the main
program, and how to display the objects using simple 4DGL commands. For
video objects, this tutorial shows how video frames are displayed either
one at a time or continuously.

Launch Workshop 4
There is a shortcut for Workshop 4 on the desktop.

Launch Workshop 4 by double-clicking on the icon.

2013 4D Systems

Page 3 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

Create a New Project

Create a New Project
Workshop 4 opens and displays the Recent page.

These options update the main window with the selection of the screen.

To create a new project, there are two options.

Click on the top left-most icon, New.

Or Click on the icon beside Create a new Project.

2013 4D Systems

Select your screen. The screen used in this example is the uLCD-32WPTU
(Portrait orientation).
Page 4 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

Select ViSi

Program Skeleton

Design the Project

Everything is now ready to start designing the project.
Workshop 4 displays the code (left side orange box), the WYSIWYG
screen (right upper side red box), and the Object Inspector (right lower
side green box). Refer to the ViSi User Guide document for more
information.
2013 4D Systems

ViSi automatically provides the program skeleton, to which developers can

simply add their codes. The program skeleton contains basic parts needed
to start designing an application. The user is advised to have a copy of the
PICASO-4DGL-Internal-Functions document on hand. The document
contains detailed information on the different functions used in this
application note.
Uncomment the Necessary Parts

Observe that in the main function, the lines are commented out. Also,
instructions are given to uncomment a line if needed. In this application

Page 5 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

note, most of the existing lines are needed. Remove the block comment
symbols shown below.

The code screen will be updated accordingly, showing the block as an

actual part of the code for compilation.

The block containing lines 16 to 24 defines the behaviour of the screen

while waiting for a SD card to be mounted on the slot. A SD card is
needed in this application since a widget will be added. Objects such as
images, videos, sound, and strings added to an application will also need a
SD card.
The statement in line 26, gfx_Transparency(ON), turns the transparency
on; gfx_TransparentColour(colour) defines the colour that needs to be
made transparent. Lines 25 and 26 can be omitted for now since they are
not really necessary here. The same is the case for lines 28 and 29.

2013 4D Systems

Page 6 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

The function file_LoadImageControl(fname1,fname2,mode) in line 30

creates an image control list.

Once the Image icon is selected, click on the WYSIWYG screen to place it. A
standard Open window appears. Browse for the desired file and click
Open. The WYSIWYG screen is updated.

It requires two files fname1 and fname2, the .dat file and .gci file,
respectively. These files are created by Workshop. The GCI file contains all
the graphics for the images and/or videos created by Workshop. The DAT
file contains one line, for each image or video, that names the object and
gives its starting offset within the GCI and its initial X/Y position.
C

The function returns a handle (pointer to the memory allocation) to the

image control list that has been created. This handle will be used to access
and display objects, as will be shown later.

Image Object
Create an Image Object in the WYSIWYG Screen

Go to the Widgets menu, select the System/Media pane, and click on the
Image icon.

2013 4D Systems

The user can drag the object to any desired location in the WYSIWYG
screen. It is also possible to resize the image by dragging the borders.
Further editing of other properties can be done using the Object Inspector.
The user may want to limit the image size (length and width) so as to give
room for a video object later on in this application note.

Page 7 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

Insert the Image Object Code

The program code will be updated accordingly.

Go to the code area and place the cursor just after the handle assignment
statement (line 32 in this example).

A new line for the image object is generated, along with a comment. The
command
Having selected the image object, go to the Object Inspector and click on
the Paste Code button.

img_Show(hndl,iImage1)

simply displays the image that has been created. Note that iImage1 is an
image index for the object created.
Save the Program for Compilation and Downloading

Now we make a quick test if the simple program works. Save the program
with the desired file name first, and then compile and download it. The
program in this example is saved as VIDIMAGEtutorial.

2013 4D Systems

Page 8 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

How to Compile and Download

Connect the Picaso display module to your PC using a USB programming

cable or a USB-PA5 adapter.
Go to the Comms menu to check if the module is detected. The button
should be blue in colour. If the button is red in colour, choose the correct
COM port by clicking on the drop down menu arrow
button to update the status.

. Then click on the

C

Workshop copies the GCI files to the SD card and downloads the program
to the display module. The message box will look like as shown below after
a successful download.

After making sure that the device is detected, insert the SD card into the
SD card slot (if using a SD to SD card adaptor) or USB port (if using a SD
to USB adaptor) of your PC. Format the SD card if necessary.
Now go to the Home menu and click on the Comp nLoad button.
C

Remove the SD card and insert it into the SD card slot of the display
module. The program will now run. The image should be shown on the
display module screen as configured in the WYSIWYG screen. Below is the
code at this point, with the unnecessary lines excluded.
The Copy Confirmation window appears. The user will be prompted to
choose the drive. Choose the correct drive by clicking on the drop down
arrow. Then click on OK.
2013 4D Systems

Page 9 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

#platform "uLCD-32WPTU"

Video Object

// Program Skeleton 1.0 generated 6/8/2013 11:50:25 AM

Create a Video Object in the WYSIWYG Screen

#inherit "4DGL_16bitColours.fnc"

Go to the Widgets menu, select the System/Media pane, and click on the
Video icon.

#inherit "VisualConst.inc"
#inherit "VIDIMAGEtutorialConst.inc"
func main()
putstr("Mounting...\n");
if (!(disk:=file_Mount()))
while(!(disk :=file_Mount()))
putstr("Drive not mounted...");
pause(200);
gfx_Cls();
pause(200);
wend
endif
gfx_TransparentColour(0x0020);
gfx_Transparency(ON);
gfx_Cls();
hndl := file_LoadImageControl("VIDIMA~1.dat",
"VIDIMA~1.gci", 1);

Once the Video icon is selected, click on the WYSIWYG screen to place it. A
standard Open window appears and displays the files that can be opened.
Browse for the desired file and click Open. The WYSIWYG screen is
updated.

// Image1 1.0 generated 6/8/2013 12:29:56 PM

img_Show(hndl,iImage1) ;
repeat
forever
endfunc

2013 4D Systems

Page 10 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

The user can drag the object to any desired location in the WYSIWYG
screen. It is also possible to resize the object by dragging the borders.
Further editing of other properties can be done using the Object Inspector.
Video Frames

It is possible for the user to know the number frames inside a video. In the
Object Inspector click on the symbol

beside Frames.

and clicking on the symbol

The Image + Video Converter window now appears. Refer to page 16 of

4D-AN-P4007-ViSi-Genie-Play-Video for detailed information on how to
use the Image + Converter window.
FrameDelay is the delay between each frame. The unit is in milliseconds.
The reciprocal of FrameDelay is the frame rate of the video. For example,
the video used in this application note has a frame rate of 1/.033 = 30
frames per second.

The properties under Frames will be displayed.

The video added in this application note has the frame properties shown
above. Total number of frames is 605 from 0 (First) to 604 (Last). The
user has the option of choosing what frames to include in the GCI file by
changing the First and Last frame properties. For example,

2013 4D Systems

The user can view the actual frames by clicking on the Video property line

Insert the Video Object Code

Go to the code area and place the cursor after the handle assignment
statement (line 37 after the img_Show() command in this example).

Page 11 of 15

www.4dsystems.com.au

4D SYSTEMS

Having selected the video object, go to the Object Inspector and click on
the Paste Code button.

4D-AN-P3005

A new block for the video object is generated, along with a comment. The
command
img_SetWord(hndl, iVideo1, IMAGE_INDEX, frame)

is used to set which frame of the movie is to be displayed. The user can
replace the fourth argument, frame, with a frame value. For instance, set
the program to display frame 0 of the object Video1 by writing the
statement
img_SetWord(hndl, iVideo1, IMAGE_INDEX, 0)

The program code will be updated accordingly.

After having set the frame to be shown, display the frame with the
command
img_Show(hndl,iVideo1)

To display three frames in succession, the user can use the code below.
2013 4D Systems

Page 12 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005
Or

img_SetWord(hndl, iVideo1, IMAGE_INDEX, 0) ;

img_Show(hndl,iVideo1) ;
pause(1000); //add a one second delay

n := img_GetWord(hndl, iVideo1, IMAGE_FRAMES) ;

for(frame := 0; frame < n; frame ++)
img_SetWord(hndl, iVideo1, IMAGE_INDEX, frame) ;
img_Show(hndl,iVideo1) ;
pause(33);
next

img_SetWord(hndl, iVideo1, IMAGE_INDEX, 1) ;

img_Show(hndl,iVideo1) ;
pause(2000); //add a two-second delay

Note that the delay used is 33 milliseconds, which is equal to the

FrameDelay property of the video file. This enables the program to play
the video at its original frame rate.

img_SetWord(hndl, iVideo1, IMAGE_INDEX, 2) ;

img_Show(hndl,iVideo1) ;
pause(3000); //add a three-second delay

Note that for the fourth argument, frame, the range of possible values
depends on how many frames the video object has - 0 to 604 for the video
used in this application note. If the user is doing pure codes in the Designer
environment, is also possible to get the number of frames by using the
function

This application note comes with a ViSi file, VIDIMAGEtutorial, which

contains a code for playing an entire video. It also contains the codes
shown in the previous sections of this tutorial.

Workshop Sample Programs

img_GetWord(hndl, iVideo1, IMAGE_FRAMES) ;

Workshop comes with many sample programs, one of which is entitled

VIDIMAGE. This program is almost identical to VIDIMAGEtutorial. To open
it, click on the File menu tab.

A Simple Example

To play an entire video, the user can use a loop with an incrementing
counter. To illustrate:
for(frame := 0; frame <= 604; frame ++)
img_SetWord(hndl, iVideo1, IMAGE_INDEX, frame) ;
img_Show(hndl,iVideo1) ;
pause(33);
next

2013 4D Systems

Page 13 of 15

www.4dsystems.com.au

4D SYSTEMS
Near the bottom of the drop down menu, you can find the Samples
button, click on it.

4D-AN-P3005
Select the file VIDIMAGE then click on Open.

The program now opens.

The samples window now appears. Select Picaso ViSi.

2013 4D Systems

Page 14 of 15

www.4dsystems.com.au

4D SYSTEMS

4D-AN-P3005

Proprietary Information
The information contained in this document is the property of 4D Systems Pty. Ltd. and may be the subject of patents pending or granted, and must not be
copied or disclosed without prior written permission.
4D Systems endeavours to ensure that the information in this document is correct and fairly stated but does not accept liability for any error or omission. The
development of 4D Systems products and services is continuous and published information may not be up to date. It is important to check the current
position with 4D Systems.
All trademarks belong to their respective owners and are recognised and acknowledged.

Disclaimer of Warranties & Limitation of Liability

4D Systems makes no warranty, either expresses or implied with respect to any product, and specifically disclaims all other warranties, including, without
limitation, warranties for merchantability, non-infringement and fitness for any particular purpose.
Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates.
It is your responsibility to ensure that your application meets with your specifications.
In no event shall 4D Systems be liable to the buyer or to any third party for any indirect, incidental, special, consequential, punitive or exemplary damages
(including without limitation lost profits, lost savings, or loss of business opportunity) arising out of or relating to any product or service provided or to be
provided by 4D Systems, or the use or inability to use the same, even if 4D Systems has been advised of the possibility of such damages.
4D Systems products are not fault tolerant nor designed, manufactured or intended for use or resale as on line control equipment in hazardous environments
requiring fail safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life
support machines or weapons systems in which the failure of the product could lead directly to death, personal injury or severe physical or environmental
damage (High Risk Activities). 4D Systems and its suppliers specifically disclaim any expressed or implied warranty of fitness for High Risk Activities.
Use of 4D Systems products and devices in 'High Risk Activities' and in any other application is entirely at the buyers risk, and the buyer agrees to defend,
indemnify and hold harmless 4D Systems from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or
otherwise, under any 4D Systems intellectual property rights.

2013 4D Systems

Page 15 of 15

www.4dsystems.com.au