README.Epoc
author Sam Lantinga <slouken@libsdl.org>
Thu, 25 Oct 2001 04:35:42 +0000
changeset 213 c79890792bfb
parent 173 83018110dce8
child 250 74a8f672f2f8
permissions -rw-r--r--
*** empty log message ***
slouken@173
     1
31.8.2001 HJV
slouken@173
     2
slouken@173
     3
SDL for EPOC/Symbian OS
slouken@173
     4
=======================
slouken@173
     5
slouken@173
     6
This is an Epoc port of SDL (1.2.0). It is not yet complete, but good enough for starting to port all those wonderful SDL based demos, games and other programs to Epoc! I have tested a bunch of demos and test programs in Nokia 9210 Communicator, which is a fancy device with combined PDA/GSM phone features, Symbian OS (Crystal), a full keyboard and a color screen (640x200x12bit).
slouken@173
     7
slouken@173
     8
Btw. Also SDLDoom works over SDL Epoc port now (CDoom)!
slouken@173
     9
 
slouken@173
    10
slouken@173
    11
How to install to device
slouken@173
    12
========================
slouken@173
    13
slouken@173
    14
Extract binary packets of the demo and test programs and copy the files to N9210.
slouken@173
    15
slouken@173
    16
slouken@173
    17
How to use
slouken@173
    18
==========
slouken@173
    19
slouken@173
    20
Run exe's from the File manager. The Caps lock key enables or disables the virtual cursor. 
slouken@173
    21
The Esc key quits demo programs.
slouken@173
    22
Function keys are mapped as follows: 
slouken@173
    23
- F1=chr+q, F2=chr+w,..., F8=chr+i, 
slouken@173
    24
- F9=chr+a,..., F12=chr+d.
slouken@173
    25
slouken@173
    26
In Crystal, Exe programs do not appear in task list nor in Extras :-(
slouken@173
    27
slouken@173
    28
slouken@173
    29
How to build
slouken@173
    30
============
slouken@173
    31
slouken@173
    32
Building SDL, SDL_IMAGE and tests & demos:
slouken@173
    33
- Build files are in "\sdl\epoc\" and "\sdl_image\epoc\" directories
slouken@173
    34
- Building as usual: "bldmake bldfiles" "abld build wins udeb" "abld build armi urel"
slouken@173
    35
- Test and demos programs are build: "abld test build wins udeb" "abld test build armi urel" 
slouken@173
    36
slouken@173
    37
slouken@173
    38
Building and sources
slouken@173
    39
====================
slouken@173
    40
Information about the Epoc implementation: 
slouken@173
    41
- Made over SDL 1.2.0
slouken@173
    42
- Ported sources: SDL, SDL_image, xflame, fire, warp, newvox, graywin, testalpha, SDLDoom(CDoom)
slouken@173
    43
- Test programs do not have any major changes: usually only screen size and depth is 
slouken@173
    44
  changed for 9210, if needed
slouken@173
    45
- Like in all the other platform implementations, the Epoc specific code is in "Epoc" subdirectories. All build files for Epoc are in the directory \sdl\epoc\. Adding a new OS support requires always some changes also in generic files (search for "#ifdef __SYMBIAN32__").
slouken@173
    46
- Currently, two resolutions and bit depths are supported: 320x200 and 640x200 with 8 or 12 bit color.
slouken@173
    47
- I addition, two faked resolutions are supported: 640x400, 640x480. These are implemented by shrinking the screen vertically i.e. only every second scanline is drawn. This can be used for testing and for non-resource intensive programs. Thought, using faked resolutions is a waste of memory and cpu power! 
slouken@173
    48
slouken@173
    49
Change history
slouken@173
    50
==============
slouken@173
    51
slouken@173
    52
31.8.2001 Alpha 0.2:
slouken@173
    53
- Now you should build ARMI binaries instead of THUMB. It runs faster. 
slouken@173
    54
- sdl_main.cpp: removed check for existing instance of sdlprogram
slouken@173
    55
- sdl_error.h: Added debug macros under conditional compilation in Epoc
slouken@173
    56
- sdl_epocevents.cpp: Added focus lost&gained event handling, added modifier handling, added a lot more key event handling (function keys and others). Function keys are mapped as follows: 
slouken@173
    57
  F1=chr+q, F2=chr+w,..., F8=chr+i, F9=chr+a,..., F12=chr+d.
slouken@173
    58
- sdl_epocvideo.h: Added EPOC_ScreenOffset variable. Added EPOC_IsWindowFocused variable (but not used for anything yet!). Added RedrawWindowL() function.
slouken@173
    59
- sdl_epocvideo.cpp: Added debugging functions: Debug_AvailMem2() and Debug_AvailMem(). 
slouken@173
    60
  Changed window to have white background. Centralize game screen if it is not full size. 
slouken@173
    61
  Added RedrawWindowL() function. Force other windows to redraw if SDL window lost focus. This cleans up possible game graphics from screen. Redraw after getting focus again.
slouken@173
    62
slouken@173
    63
slouken@173
    64
Todo
slouken@173
    65
====
slouken@173
    66
slouken@173
    67
This Epoc port is (of course;-) not thoroughly tested. For testing, I have compiled and run a couple of test programs and demos in N9210. Still, e.g. thread related functions have not been tested at all.
slouken@173
    68
slouken@173
    69
Known bugs and unimplemented features:
slouken@173
    70
- No sound
slouken@173
    71
- No console output screen. Printing to stdout do not have any effect.
slouken@173
    72
- Epoc do not allow static/global variables in DLL libraries. So I could only use static linking with SDL.
slouken@173
    73
- Some test programs may take so much cpu in 9210 that e.g. SMS sending and receiving is not possible at a same time. Also screen may look awkward if there appear visible notes, dialogs etc. when an sdl program is active. SDL program runs in the lowest possible priority for minimum interference in the system. Unfortunately, this is always not enough.  Perhaps some Delay() commands are needed.
slouken@173
    74
slouken@173
    75
P.s. I have ported also the SDL version of MirrorMagic puzzle game to Epoc. I will put the sources and binaries available as soon as I bother to clean the ported sources a bit... 
slouken@173
    76
slouken@173
    77
slouken@173
    78
Open Source & "bazaar" style software development
slouken@173
    79
=================================================
slouken@173
    80
slouken@173
    81
You can take part in this porting project. This is Open Source software and you are very welcome to try it, test it, improve the code and implement the missing pieces. If you have any fix suggestions, improvements, code excerpts etc., contact me by email. Please start the mail subject with a string "EPOC SDL:".
slouken@173
    82
slouken@173
    83
Cheers,
slouken@173
    84
Hannu
slouken@173
    85
slouken@173
    86
Mail:hannu.j.viitala@mbnet.fi
slouken@173
    87
Homepage of SDL for Epoc: www.mbnet.fi/~haviital