Documentation
[SDK Documentation] [GapiDraw 3.6 Symbian Readme.txt]

GapiDraw 3.6 Symbian Readme.txt

This document has been updated for use with GapiDraw 3.6 or later.
Last updated on Sunday, May 21, 2006.

Contents

Please read the section “known issues” below before sending any bug reports.

1. Getting started with Symbian development
2. GapiDraw / Symbian platform notes
3. Known Issues
4. Some problems and solution suggestions
5. Useful links to some Symbian pages
6. Steps to port a simple application to Symbian

Getting started with Symbian development

What you need

• GapiDraw 3.6 or later
• A Series 60 SDK. GapiDraw 3.6 was built for Symbian 6.1 and later, and you can download the SDK for your device here: http://www.symbian.com/developer/sdks.asp.
• If Active Perl is not included in the SDK for your phone, you need it as well. The scripts in the SDK tools use Perl, so get it at http://www.activestate.com/Products/ActivePerl/
• Make sure that you are able to build and install one of the provided example projects in the SDK. There is a nice tutorial at newlc.com about getting started with symbian programming at http://www.newlc.com/article.php3?id_article=134
• To port a game from PocketPC (or XP), follow the guidelines from the porting of the sample project "simple" below

Planning your installation

The Symbian SDKs must be on the same drive partition as your project files! For example, you cannot install the Symbian SDKs to C: and store project files on D:. If you store your project files on D:, remember to install the Symbian SDKs on the same drive (D:).

Also, if you install the Symbian SDKs to another drive than C: and you want to use the emulator in Nokia Series 60 SDK 1.2, you must manually edit the file \Symbian\6.1\Series60\Epoc32\Data\epoc.ini to reflect this - otherwise the Series 60 emulator will stall! Simply set the key _EPOC_DRIVE_D to D: instead of C:.

SDK Choices

It is recommended that you download and install the following SDKs:

1. Nokia Series 60 SDK v1.2 (binary compatible with all Nokia series 60 phones)
2. Nokia Series 60 SDK v2.0 (for environmentswitch.exe if you want to use it - not necessary)

GapiDraw Binaries

Before you begin to compile the sample applications you need to copy the GapiDraw LIB file to its correct location.

• ARMI. For the ARM version of the GapiDraw LIB file, copy the file GAPIDRAW.LIB from GapiDraw/lib/Symbian-S60 to %epocroot%/epoc32/release/armi/urel
• WINS. For the emulator version of the GapiDraw LIB file, copy the file GAPIDRAW.LIB from GapiDraw/lib/Symbian-S60-WINS to %epocroot%/epoc32/release/wins/udeb

Depending on the SDKs you want to target you have to repeat the above file copy steps once for each of the SDKs you have installed, such as:

• Series 60 SDK - %epocroot% should be set to "C:\Symbian\6.1\Series60"

Environment Setup

The Nokia Series 60 SDK 1.2 changes several settings in the environment that are not compatible with other SDKs. Go to Start Menu -> Control Panel -> System -> Advanced -> Environment Variables and remove the following folders from the system search path:

1. C:\Symbian\6.1\Shared\epoc32\tools
2. C:\Symbian\6.1\Shared\epoc32\gcc\bin;
3. C:\Program Files\Microsoft Visual Studio\VC98\Bin;
4. C:\Program Files\Microsoft Visual Studio\Common\MSDev98\Bin;

All the above paths should be removed from the system path and will be set later.

Environmentswitch

Many people recommend the use of a tool called "environmentswitch" that is shipped with the Nokia Series 60 SDK 2.0. Using the environmentswitch tool you can easily create new shells where all the correct environment variables are set for you automatically. The disadvantage of using environmentswitch is that you can only build for one environment at a time - something that we probably do not want (in most cases we want to build for all target devices at once). However, if you want to use environmentswitch here is a sample configuration file to get you started (the program is located in the folder "C:\Symbian\7.0s\Series60_v20\Series60Tools\environmentswitch\"). Replace the contents of the file settings.xml in the same folder with this content:

BuildSample.cmd - the easy and better way

Using environmentswitch it is assumed that you only want to build for one device at a time. If you want to build for multiple devices you would have to have two shells open and compile the same program twice, once for each shell.

For each sample application shipped with GapiDraw there is a batch file called "BuildSample.cmd". If you start this file, GapiDraw will automatically set the necessary environment variables for you! So throw away environmentswitch and simply double click on "BuildSample.cmd" to get started! Please note that you may need to modify the "symbianroot" parameter on line #4 in the BuildSample.cmd file to match the folder of your Symbian installation.

Compiling and running the "Simple" demo

To compile and run the "Simple" demo shipped with GapiDraw, start the windows explorer and navigate to the folder "\GapiDraw\Samples\Symbian\Simple". Edit the file "BuildSample.cmd" and change the key "symbianroot" to match the folder of your Symbian installation. Double click on the file "BuildSample.cmd" to compile the Series60 target, which will be placed in the folder "Release". To install the sample on your device, simply transfer the SIS file to the device using IR or USB transfer.

Emulator notes

To start the emulator, you simply call "epoc.exe" after you have set the correct environment variables for the SDK you are using. Please review the file "BuildSample.cmd" shipped with each sample application for instructions on how to set the necessary environment variables.

Please note that all images and resources have to be copied manually to the emulator. Simply select all images in the "res" folder and copy them manually to the %epocroot%/epoc32/release/wins/udeb/z/{PROJECT} folder.

GapiDraw / Symbian platform notes

CGapiDraw

Before you use any of the classes in the GapiDraw library you must create an instance of the CGapiDraw class, which GapiDraw uses for initialization and cleanup. If you’re using CGapiApplication this is done for you.

Timers / animation

Timers in Symbian are a real drawback. It is impossible to sleep with a greater accuracy than 15 ms, although the documentation for the Symbian equivalent of win32's Sleep() takes a microsecond argument so this is rather a limitation of current devices. Most cell phones running Symbian OS generates a clock tick every 1/64 of a second and the equivalent to Sleep(1) simply waits until the next clock tick. Therefore, it is virtually impossible to set a constant fps other than 16,21,32,64 so the approach used in CGapiApplication for Symbian is simply to render graphics when there are no other higher priority threads scheduled. This practically means that you should never base your in-game animation on how many frames that have passed, but rather on time. This approach is discussed in a few threads at http://forums.pocketmatrix.com

Global variables and static member variables

Global variables are not supported in Symbian, which may cause issues for developers used to the Win32 environment. Since static member variables also are not available (preventing the use design patterns such as the Singleton pattern), it might not be clear how to work around this issue. The solution is to use a Thread Local Storage (TLS) to store one global pointer to a STRUCT created on the heap. This struct can contain unique pointers to all the global data in your application, and you can then define macros so that myglobalobject->myfunction will be replaced by Dll::Tls()->myglobalobject->myfunction. Using the TLS workaround, porting applications to Symbian is actually quite easy. The drawback is that there is a 20 cycle overhead in retreiving the TLS pointer, but in most cases this is not an issue. The solution of using a TLS is used in many cross-platform products such as Opera and GapiDraw. A DLL has it's own TLS so there should be no conflict between the GapiDraw TLS and the application TLS.

Known Issues

Menu program terminates on the Nokia 7650

When running an application derived from CGapiApplication on the 7650, the menu program terminates about 10-15 seconds after starting, because of ViewSrv 11. It seems that the scheduler on the 7650 does not give enough priority to the menu program, and the menu program doesn’t respond to the View server in time. The GapiDraw application does not crash however and this problem does not occur on any other Symbian device we have tested.

Image loading does not work with exe files

The imageloader does not work if you build an exe. If you need to build an exe instead of an app, and you want to load images, you would need to provide your own image loading, and convert the loaded image to a CGapiSurface using CGapiSurface::GetBuffer().

Some problems and solution suggestions

Problem: When I run my application in the emulator none of my images will load into surfaces

Solution: You have probably just re-compiled your application without copying the images to the emulator. Just copy the images in the "res" folder into \Symbian\6.1\Series60\Epoc32\Release\wins\udeb\z\system\apps\ + the name of your application.

Problem: I have problems linking to the GapiDraw library, I get lots of undefined symbol errors

Solution: You need to place "STATICLIBRARY GAPIDRAW.LIB" before all other libraries. See the MMP projects shipped with GapiDraw to see sample setups.

Problem: the compiler/linker says that there are initialized data in my dll

Solution: You are probably using global/static variables in your program. Apps/dlls in Symbian are not allowed to use these, so you have to organize thing differently to get rid of these, i.e. have them as member variables in your class rather than static variables in functions.

Problem: I get "undefined symbol __chkstk" when I try to build my app

Solution: You are putting to much on the stack. The stack size in Symbian is very limited so try to use the heap as much as possible.

Problem: The menu program crashes 15 seconds after my app has started. My app runs fine though.

Solution: Se section known issues

Problem: I have a function LoadScore that returns a TBuf<15> and I want to display it using DrawText. So I need to convert it to a TCHAR*. I tried to use name.Ptr() which should have returned a pointer to the data (exactly what I need) but only the first letter is displayed! Do I miss something obvious?

Solution: TBuf<15> is a pointer to a TUint16, and TEXT is an array of TUint8. So you should do something like this:

TUint16 *uiPtr16 = buf15.Ptr();
TUint8 *uiPtr8 = new TUint8[15];
wcstombs(uiPtr8, uiPtr16, 15);

It is assumed that your TBuf<15> variable is buf15. Now you can do DrawText(..., uiPtr8,...). The problem was in that TUint16* pointer which was returned from buf15.Ptr(). You received only the first letter because in upper byte of your TUint16* was a "0" which terminated string (null terminated string).

Useful links to some Symbian pages

Forums:

• Symbian C++ - http://www.newlc.com/forums/
• Development for Nokia devices - http://discussion.forum.nokia.com/forum/forumdisplay.php?s=&forumid=40
• Development for SE P800 - http://www.sonyericsson.com/developer/show_forums.do
• General Symbian forum - http://www.allaboutsymbian.com/forum/

General:

• Developer pages at symbian.com - http://www.symbian.com/developer/
• Nice site about Symbian - http://www.newlc.com
• Symbian news + forums - http://my-symbian.com/

Steps to port a simple application to Symbian

Here's a brief description of the steps required to port the simple example from win32 to Symbian. The Symbian SDK has to be installed on your computer. This description is not intended to be an introduction to Symbian programming, and it doesn't try to explain any Symbian specific details, its sole purpose is to show the amount of work to get a small existing application up and running using GapiDraw for Symbian. If you are interested in the various tools invoked in the build process for Symbian, check out the online documentation at symbian.com: http://www.symbian.com/developer/techlib/v70docs/SDL_v7.0/doc_source/ToolsAndUtilities/Build-ref/index.html

1. Copy the file GAPIDRAW.LIB (from GapiDraw/lib/Symbian-S60) to %epocroot%/epoc32/release/armi/urel
    
2. Copy the content of "common".
    
3. Rename myapplication.h and .cpp to something else, and copy the Symbian version of minimal myapplicationfiles to the new directory.
    
4. Create bld.inf, which should contain the following lines:
   

   // File bld.inf PRJ_MMPFILES simple_s60.mmp // End bld.inf

   
    
5. Create the file simple.mmp:
   

   // File simple.mmp TARGET TARGETTYPE TARGETPATH UID MACRO SOURCEPATH SOURCE RESOURCE RESOURCE SOURCEPATH SOURCE USERINCLUDE SYSTEMINCLUDE SYSTEMINCLUDE STATICLIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY LIBRARY #if !defined(WINS) STATICLIBRARY #endif

   Simple.app app \system\apps\simple 0x100039ce 0x0101F415 SERIES60 . myapplication.cpp Simple.rss simple_caption.rss ..\..\..\include\symbian GapiApplication.cpp ..\..\..\include\symbian \epoc32\include \epoc32\include\libc GAPIDRAW.LIB euser.lib apparc.lib cone.lib eikcore.lib ws32.lib hal.lib bitgdi.lib estlib.lib etel.lib apgrfx.lib avkon.lib // Additional libraries needed by GapiDraw.lib MediaClientImage.lib fbscli.lib bafl.lib gdi.lib egcc.lib

   AIF simple.aif res simpleaif.rss c8 gapidrawicon.bmp gapidrawiconmask.bmp

   
   Note that the above UID 0x0101F411 is a test UID (the range is 0x01000000 to 0x0fffffff). You need to obtain a real UID from Symbian before releasing your app. When changing UIDs, make sure you change it in all relevant places, or your app will probably not run. The places you have to change the UIDs are: in MyApplication.h, your .mmp file and in your .pkg files and the .rss file for AIFs. For more information on why the library egcc.lib is not included in the WINS environment, please see this page.
    
6. Create an rss resource file.
   

   // File simple.rss NAME SIMP #include <eikon.rh> #include <eikon.rsg> RESOURCE RSS_SIGNATURE { } RESOURCE TBUF { buf=""; } RESOURCE EIK_APP_INFO { } RESOURCE HOTKEYS r_example_hotkeys { } RESOURCE MENU_BAR r_example_menubar { } RESOURCE MENU_PANE r_example_file_menu { } // End simple.rss

   
   (rss files defines menus, hotkeys and other stuff that we don’t really care about when writing fullscreen games with GapiDraw. However, the Symbian framework insists that every application has a compiled resource file, so we make a really slimmed version of one).
    
7. Create make files with the command bldmake bldfiles
    
8. If you're using Visual C++ 6.0 you can use abld makefile vc6 to build vc6 project files. Your .dsw file will end up in %epocroot%\Epoc32\BUILD\{path-to-mmp-file} (for example C:\Symbian\6.1\Series60\Epoc32\BUILD\SOURCE\GAPIDRAW\MYPROJECTS\SYMBIAN\SIMPLE\WINS) together with a .dsp file.
   
   ABOUT VC++6.0: You should see Visual C++ 6.0 just as a file editor for the files included in the mmp file of your project and nothing else. You still have to build the project from the command line.
   If you create new source files and want to include them in your build, you still have to add them in a SOURCE directive in your mmp file. It’s not enough to just add them in your visual C++ 6.0 project. You can add a file to your workspace like this: 1. Create an empty file in your project directory 2. add this file on a SOURCE line in your mmp file and save. 3. Run the command abld makefile vc6 4. Visual C++ will ask if you want to reload your workspace, click yes and now the new files are added in visual c++ as well.
    
9. Copy missing members from the W32 version to the Symbian version. The m_cursor member needs to be omitted since GapiDraw for Symbian doesn't support CGapiCursor, and the same for goes for DrawFrameInfo, because of CGapiTimer. Also, we want to have the member surfaces as pointers.
    
10. In the .cpp file:
    (a) Note that there are fewer things to set in the config in the Symbian version. ConstructL is called by the Symbian framework instead of WinMain. It also constructs the application.
    (b) Create surfaces must a bit altered. In the Win32 version they were created from resources, whereas in the Symbian version they will be created from files. Enter the relative or absolute path to the files on the device. The cursor surface is of course omitted too. SetRect has to be changed too. The parameter display is now a pointer.
    (c) ProcessNextFrame: Remove the timer parts and change the SetRect. Parameters display and backbuffer are now pointers. We can't have static variables, they need to become member variables instead.
    (d) StylusDown: Change the way to calculate if the stylus is within the bounds of a rect, since we cant use the w32 specific functions.
     
11. Compile your work with the command abld build armi urel
     
12. Create the simple_s60.pkg file to specify which files to include in the sis file
    

    ; File simple_s60.pkg ; Installation header #{"Simple"},(0x0101f415),1,0,0 ;Supports Series 60 v 0.9 (0x101F6F88), 0, 0, 0, {"Series60ProductID"} "\Symbian\6.1\Series60\epoc32\release\armi\urel\Simple.app"-"!:\system\apps\Simple\Simple.app" "\Symbian\6.1\Series60\epoc32\release\armi\urel\Simple.rsc"-"!:\system\apps\Simple\Simple.rsc" "\Symbian\6.1\Series60\epoc32\release\armi\urel\Simple.aif"-"!:\system\apps\Simple\Simple.aif" "res\p900.png"-"!:\system\apps\Simple\p900.png" "res\SimpleFont.png"-"!:\system\apps\Simple\SimpleFont.png" "res\taskbar.png"-"!:\system\apps\Simple\taskbar.png"

    
    Note: This package file assumes your epocroot is \Symbian\6.1\Series60\.
     
13. Create a sis file with the command makesis simple_s60.pkg
     
14. Install the sis file on your phone, either by IR or by using a PC connectivity suite and a data cable.

These are the steps that were used to create the simple Symbian example in the samples folder.