README.Epoc
author Sam Lantinga <slouken@libsdl.org>
Fri, 02 Nov 2001 18:12:52 +0000
changeset 221 50620ec9c86a
parent 173 83018110dce8
child 250 74a8f672f2f8
permissions -rw-r--r--
*** empty log message ***
     1 31.8.2001 HJV
     2 
     3 SDL for EPOC/Symbian OS
     4 =======================
     5 
     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).
     7 
     8 Btw. Also SDLDoom works over SDL Epoc port now (CDoom)!
     9  
    10 
    11 How to install to device
    12 ========================
    13 
    14 Extract binary packets of the demo and test programs and copy the files to N9210.
    15 
    16 
    17 How to use
    18 ==========
    19 
    20 Run exe's from the File manager. The Caps lock key enables or disables the virtual cursor. 
    21 The Esc key quits demo programs.
    22 Function keys are mapped as follows: 
    23 - F1=chr+q, F2=chr+w,..., F8=chr+i, 
    24 - F9=chr+a,..., F12=chr+d.
    25 
    26 In Crystal, Exe programs do not appear in task list nor in Extras :-(
    27 
    28 
    29 How to build
    30 ============
    31 
    32 Building SDL, SDL_IMAGE and tests & demos:
    33 - Build files are in "\sdl\epoc\" and "\sdl_image\epoc\" directories
    34 - Building as usual: "bldmake bldfiles" "abld build wins udeb" "abld build armi urel"
    35 - Test and demos programs are build: "abld test build wins udeb" "abld test build armi urel" 
    36 
    37 
    38 Building and sources
    39 ====================
    40 Information about the Epoc implementation: 
    41 - Made over SDL 1.2.0
    42 - Ported sources: SDL, SDL_image, xflame, fire, warp, newvox, graywin, testalpha, SDLDoom(CDoom)
    43 - Test programs do not have any major changes: usually only screen size and depth is 
    44   changed for 9210, if needed
    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__").
    46 - Currently, two resolutions and bit depths are supported: 320x200 and 640x200 with 8 or 12 bit color.
    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! 
    48 
    49 Change history
    50 ==============
    51 
    52 31.8.2001 Alpha 0.2:
    53 - Now you should build ARMI binaries instead of THUMB. It runs faster. 
    54 - sdl_main.cpp: removed check for existing instance of sdlprogram
    55 - sdl_error.h: Added debug macros under conditional compilation in Epoc
    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: 
    57   F1=chr+q, F2=chr+w,..., F8=chr+i, F9=chr+a,..., F12=chr+d.
    58 - sdl_epocvideo.h: Added EPOC_ScreenOffset variable. Added EPOC_IsWindowFocused variable (but not used for anything yet!). Added RedrawWindowL() function.
    59 - sdl_epocvideo.cpp: Added debugging functions: Debug_AvailMem2() and Debug_AvailMem(). 
    60   Changed window to have white background. Centralize game screen if it is not full size. 
    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.
    62 
    63 
    64 Todo
    65 ====
    66 
    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.
    68 
    69 Known bugs and unimplemented features:
    70 - No sound
    71 - No console output screen. Printing to stdout do not have any effect.
    72 - Epoc do not allow static/global variables in DLL libraries. So I could only use static linking with SDL.
    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.
    74 
    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... 
    76 
    77 
    78 Open Source & "bazaar" style software development
    79 =================================================
    80 
    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:".
    82 
    83 Cheers,
    84 Hannu
    85 
    86 Mail:hannu.j.viitala@mbnet.fi
    87 Homepage of SDL for Epoc: www.mbnet.fi/~haviital