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