README
1
2 Simple DirectMedia Layer
3
4 (SDL)
5
6 Version 1.2
7
8---
9http://www.libsdl.org/
10
11This is the Simple DirectMedia Layer, a general API that provides low
12level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL,
13and 2D framebuffer across multiple platforms.
14
15The current version supports Linux, Windows CE/95/98/ME/XP/Vista, BeOS,
16MacOS Classic, Mac OS X, FreeBSD, NetBSD, OpenBSD, BSD/OS, Solaris, IRIX,
17and QNX. The code contains support for Dreamcast, Atari, AIX, OSF/Tru64,
18RISC OS, SymbianOS, Nintendo DS, and OS/2, but these are not officially
19supported.
20
21SDL is written in C, but works with C++ natively, and has bindings to
22several other languages, including Ada, C#, Eiffel, Erlang, Euphoria,
23Guile, Haskell, Java, Lisp, Lua, ML, Objective C, Pascal, Perl, PHP,
24Pike, Pliant, Python, Ruby, and Smalltalk.
25
26This library is distributed under GNU LGPL version 2, which can be
27found in the file "COPYING". This license allows you to use SDL
28freely in commercial programs as long as you link with the dynamic
29library.
30
31The best way to learn how to use SDL is to check out the header files in
32the "include" subdirectory and the programs in the "test" subdirectory.
33The header files and test programs are well commented and always up to date.
34More documentation is available in HTML format in "docs/index.html", and
35a documentation wiki is available online at:
36 http://www.libsdl.org/cgi/docwiki.cgi
37
38The test programs in the "test" subdirectory are in the public domain.
39
40Frequently asked questions are answered online:
41 http://www.libsdl.org/faq.php
42
43If you need help with the library, or just want to discuss SDL related
44issues, you can join the developers mailing list:
45 http://www.libsdl.org/mailing-list.php
46
47Enjoy!
48 Sam Lantinga (slouken@libsdl.org)
49
50
README-SDL.txt
1
2Please distribute this file with the SDL runtime environment:
3
4The Simple DirectMedia Layer (SDL for short) is a cross-platfrom library
5designed to make it easy to write multi-media software, such as games and
6emulators.
7
8The Simple DirectMedia Layer library source code is available from:
9http://www.libsdl.org/
10
11This library is distributed under the terms of the GNU LGPL license:
12http://www.gnu.org/copyleft/lesser.html
13
14
README.AmigaOS
README.ANDROID
1This is a modified version of SDL 1.2.15 that is used by the Android QEMU
2emulator. See the git history for modifications relative to upstream.
3
4To build it as a static library on Linux, OS X and Windows:
5
6./android-configure.sh [--prefix=<path>]
7make -j2
8make install
9
10
README.BeOS
README.DC
README.HG
1
2The latest development version of SDL is available via Mercurial.
3Mercurial allows you to get up-to-the-minute fixes and enhancements;
4as a developer works on a source tree, you can use "hg" to mirror that
5source tree instead of waiting for an official release. Please look
6at the Mercurial website ( http://mercurial.selenic.com/ ) for more
7information on using hg, where you can also download software for
8Mac OS X, Windows, and Unix systems.
9
10 hg clone -u SDL-1.2 http://hg.libsdl.org/SDL
11
12If you are building SDL with an IDE, you will need to copy the file
13include/SDL_config.h.default to include/SDL_config.h before building.
14
15If you are building SDL via configure, you will need to run autogen.sh
16before running configure.
17
18There is a web interface to the subversion repository at:
19 http://hg.libsdl.org/SDL/
20
21There is an RSS feed available at that URL, for those that want to
22track commits in real time.
23
24
README.MacOS
1
2==============================================================================
3Using the Simple DirectMedia Layer with MacOS 7,8,9 on PPC
4==============================================================================
5
6These instructions are for people using the Apple MPW environment:
7http://developer.apple.com/tools/mpw-tools/
8
9CodeWarrior projects are available in the CWprojects directory.
10
11==============================================================================
12I. Building the Simple DirectMedia Layer libraries:
13 (This step isn't necessary if you have the SDL binary distribution)
14
15 First, unpack the MPWmake.sea.hqx archive and move SDL.make into the
16 SDL directory.
17
18 Start MPW
19
20 Set the current directory within MPW to the SDL toplevel directory.
21
22 Build "SDL" (Type Command-B and enter "SDL" in the dialog)
23
24 If everything compiles successfully, you now have the PPC libraries
25 "SDL" and "SDLmain.o" in the 'lib' subdirectory.
26
27==============================================================================
28II. Building the Simple DirectMedia Layer test programs:
29
30 First, unpack the MPWmake.sea.hqx archive, move the new rsrc directory to
31 the main SDL directory, and move the makefiles in the new test subdirectory
32 to the SDL 'test' subdirectory.
33
34 Start MPW
35
36 Set the current directory within MPW to the SDL 'test' subdirectory.
37
38 Build the programs that have an associated MPW makefile (file ending
39 with .make), including "testwin", "testalpha", and "graywin".
40
41 Copy the SDL library file into the test directory, and run!
42
43==============================================================================
44III. Building the Simple DirectMedia Layer demo programs:
45
46 Copy one of the test program Makefiles to the demo directory
47 and modify it to match the sources in the demo.
48
49==============================================================================
50IV. Enjoy! :)
51
52 If you have a project you'd like me to know about, or want to ask questions,
53 go ahead and join the SDL developer's mailing list by sending e-mail to:
54
55 sdl-request@libsdl.org
56
57 and put "subscribe" into the subject of the message. Or alternatively you
58 can use the web interface:
59
60 http://www.libsdl.org/mailman/listinfo/sdl
61
62==============================================================================
63
64
README.MacOSX
1==============================================================================
2Using the Simple DirectMedia Layer with Mac OS X
3==============================================================================
4
5These instructions are for people using Apple's Mac OS X (pronounced
6"ten").
7
8From the developer's point of view, OS X is a sort of hybrid Mac and
9Unix system, and you have the option of using either traditional
10command line tools or Apple's IDE Xcode.
11
12To build SDL using the command line, use the standard configure and make
13process:
14
15 ./configure
16 make
17 sudo make install
18
19You can also build SDL as a Universal library (a single binary for both
20PowerPC and Intel architectures), on Mac OS X 10.4 and newer, by using
21the fatbuild.sh script in build-scripts:
22 sh build-scripts/fatbuild.sh
23 sudo build-scripts/fatbuild.sh install
24This script builds SDL with 10.2 ABI compatibility on PowerPC and 10.4
25ABI compatibility on Intel architectures. For best compatibility you
26should compile your application the same way. A script which wraps
27gcc to make this easy is provided in test/gcc-fat.sh
28
29To use the library once it's built, you essential have two possibilities:
30use the traditional autoconf/automake/make method, or use Xcode.
31
32==============================================================================
33Using the Simple DirectMedia Layer with a traditional Makefile
34==============================================================================
35
36An existing autoconf/automake build system for your SDL app has good chances
37to work almost unchanged on OS X. However, to produce a "real" Mac OS X binary
38that you can distribute to users, you need to put the generated binary into a
39so called "bundle", which basically is a fancy folder with a name like
40"MyCoolGame.app".
41
42To get this build automatically, add something like the following rule to
43your Makefile.am:
44
45bundle_contents = APP_NAME.app/Contents
46APP_NAME_bundle: EXE_NAME
47 mkdir -p $(bundle_contents)/MacOS
48 mkdir -p $(bundle_contents)/Resources
49 echo "APPL????" > $(bundle_contents)/PkgInfo
50 $(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
51
52You should replace EXE_NAME with the name of the executable. APP_NAME is what
53will be visible to the user in the Finder. Usually it will be the same
54as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME
55usually is "TestGame". You might also want to use @PACKAGE@ to use the package
56name as specified in your configure.in file.
57
58If your project builds more than one application, you will have to do a bit
59more. For each of your target applications, you need a seperate rule.
60
61If you want the created bundles to be installed, you may want to add this
62rule to your Makefile.am:
63
64install-exec-hook: APP_NAME_bundle
65 rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app
66 mkdir -p $(DESTDIR)$(prefix)/Applications/
67 cp -r $< /$(DESTDIR)$(prefix)Applications/
68
69This rule takes the Bundle created by the rule from step 3 and installs them
70into $(DESTDIR)$(prefix)/Applications/.
71
72Again, if you want to install multiple applications, you will have to augment
73the make rule accordingly.
74
75
76But beware! That is only part of the story! With the above, you end up with
77a bare bone .app bundle, which is double clickable from the Finder. But
78there are some more things you should do before shipping yor product...
79
801) The bundle right now probably is dynamically linked against SDL. That
81 means that when you copy it to another computer, *it will not run*,
82 unless you also install SDL on that other computer. A good solution
83 for this dilemma is to static link against SDL. On OS X, you can
84 achieve that by linkinag against the libraries listed by
85 sdl-config --static-libs
86 instead of those listed by
87 sdl-config --libs
88 Depending on how exactly SDL is integrated into your build systems, the
89 way to achieve that varies, so I won't describe it here in detail
902) Add an 'Info.plist' to your application. That is a special XML file which
91 contains some meta-information about your application (like some copyright
92 information, the version of your app, the name of an optional icon file,
93 and other things). Part of that information is displayed by the Finder
94 when you click on the .app, or if you look at the "Get Info" window.
95 More information about Info.plist files can be found on Apple's homepage.
96
97
98As a final remark, let me add that I use some of the techniques (and some
99variations of them) in Exult and ScummVM; both are available in source on
100the net, so feel free to take a peek at them for inspiration!
101
102
103==============================================================================
104Using the Simple DirectMedia Layer with Xcode
105==============================================================================
106
107These instructions are for using Apple's Xcode IDE to build SDL applications.
108
109- First steps
110
111The Xcode project files are in the "Xcode" directory.
112
113- Building the Framework
114
115The SDL Library is packaged as a framework bundle, an organized
116relocatable folder heirarchy of executible code, interface headers,
117and additional resources. For practical purposes, you can think of a
118framework as a more user and system-friendly shared library, whose library
119file behaves more or less like a standard UNIX shared library.
120
121To build the framework, simply open the framework project and build it.
122By default, the framework bundle "SDL.framework" is installed in
123/Library/Frameworks. Therefore, the testers and project stationary expect
124it to be located there. However, it will function the same in any of the
125following locations:
126
127 ~/Library/Frameworks
128 /Local/Library/Frameworks
129 /System/Library/Frameworks
130
131- Build Options
132 There are two "Build Styles" (See the "Targets" tab) for SDL.
133 "Deployment" should be used if you aren't tweaking the SDL library.
134 "Development" should be used to debug SDL apps or the library itself.
135
136- Building the Testers
137 Open the SDLTest project and build away!
138
139- Using the Project Stationary
140 Copy the stationary to the indicated folders to access it from
141 the "New Project" and "Add target" menus. What could be easier?
142
143- Setting up a new project by hand
144 Some of you won't want to use the Stationary so I'll give some tips:
145 * Create a new "Cocoa Application"
146 * Add src/main/macosx/SDLMain.m , .h and .nib to your project
147 * Remove "main.c" from your project
148 * Remove "MainMenu.nib" from your project
149 * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
150 * Add "$(HOME)/Library/Frameworks" to the frameworks search path
151 * Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
152 * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
153 * Add your files
154 * Clean and build
155
156- Building from command line
157 Use pbxbuild in the same directory as your .pbproj file
158
159- Running your app
160 You can send command line args to your app by either invoking it from
161 the command line (in *.app/Contents/MacOS) or by entering them in the
162 "Executibles" panel of the target settings.
163
164- Implementation Notes
165 Some things that may be of interest about how it all works...
166 * Working directory
167 As defined in the SDL_main.m file, the working directory of your SDL app
168 is by default set to its parent. You may wish to change this to better
169 suit your needs.
170 * You have a Cocoa App!
171 Your SDL app is essentially a Cocoa application. When your app
172 starts up and the libraries finish loading, a Cocoa procedure is called,
173 which sets up the working directory and calls your main() method.
174 You are free to modify your Cocoa app with generally no consequence
175 to SDL. You cannot, however, easily change the SDL window itself.
176 Functionality may be added in the future to help this.
177
178
179Known bugs are listed in the file "BUGS"
180
README.MiNT
1==============================================================================
2Using the Simple DirectMedia Layer on Atari
3==============================================================================
4
5
6 If you want to build SDL from sources to create SDL programs on Atari:
7 see sections I - II.
8
9 If you want to create SDL programs on Atari using SDL binary build,
10 download it from my web site (URL at end of this file).
11
12 If you want to configure a program using SDL on Atari,
13 see sections IV - VI.
14
15
16==============================================================================
17I. Building the Simple DirectMedia Layer libraries:
18 (This step isn't necessary if you have the SDL binary distribution)
19
20 Do the classic configure, with --disable-shared --enable-static and:
21
22 Tos version (should run everywhere):
23 --disable-threads
24 Tos does not support threads.
25
26 MiNT version (maybe Magic, only for multitasking OS):
27 --disable-pthreads --enable-pth
28 Mint and Magic may supports threads, so audio can be used with current
29 devices, like Sun audio, or disk-writing support. Like Tos, interrupt
30 audio without threads is more suited for Atari machines.
31
32 Then you can make ; make install it.
33
34==============================================================================
35II. Building the Simple DirectMedia Layer test programs:
36
37 Do the classic configure, then make.
38
39 Run them !
40
41==============================================================================
42III. Enjoy! :)
43
44 If you have a project you'd like me to know about, or want to ask questions,
45 go ahead and join the SDL developer's mailing list by sending e-mail to:
46
47 sdl-request@libsdl.org
48
49 and put "subscribe" into the subject of the message. Or alternatively you
50 can use the web interface:
51
52 http://www.libsdl.org/mailman/listinfo/sdl
53
54==============================================================================
55IV. What is supported:
56
57Keyboard (GEMDOS, BIOS, GEM, Ikbd)
58Mouse (XBIOS, GEM, Ikbd, /dev/mouse (non working atm, disabled))
59Video (XBIOS (Fullscreen), GEM (Windowed and Fullscreen))
60Timer (VBL vector, GNU pth library)
61Joysticks and joypads (Ikbd, Hardware)
62Audio (Hardware, XBIOS, GSXB, MCSN, STFA, /dev/audio if threads enabled)
63Threads (Multitasking OS only via GNU pth library)
64Shared object loader (using LDG library from http://ldg.atari.org/)
65Audio CD (MetaDOS)
66OpenGL (using Mesa offscreen rendering driver)
67
68- Dependent driver combinations:
69Video Kbd Mouse Timer Joysticks
70xbios ikbd ikbd vbl(2) ikbd
71xbios gemdos xbios vbl(2) xbios
72xbios bios xbios vbl(2) xbios
73gem gem gem(1) vbl(2) xbios
74
75Audio O/S Misc
76dma8 All Uses MFP Timer A interrupt
77xbios TOS Uses MFP Timer A interrupt
78xbios MiNT Uses MFP Timer A interrupt
79xbios Magic Uses MFP Timer A interrupt
80stfa All Uses MFP interrupt
81mcsn TOS Uses MFP Timer A interrupt
82mcsn MiNT Uses MiNT thread
83mcsn Magic Disabled
84gsxb All Uses GSXB callback
85
86Joypad driver always uses hardware access.
87OpenGL driver always uses OSMesa.
88
89(1) GEM does not report relative mouse motion, so xbios mouse driver is used
90to report this type event.
91A preliminary driver for /dev/mouse device driver is present, but is disabled
92till it can be used with other applications simultaneously.
93
94(2) If you build SDL with threads using the GNU pth library, timers are
95supported via the pth library.
96
97==============================================================================
98V. Environment variables:
99
100SDL_VIDEODRIVER:
101 Set to 'xbios' to force xbios video driver
102 Set to 'gem' to force gem video driver
103
104SDL_VIDEO_GL_DRIVER:
105 Set to filename to load as OpenGL library, if you use SDL_GL_LoadLibrary()
106
107SDL_AUDIODRIVER:
108 Set to 'mint_gsxb' to force Atari GSXB audio driver
109 Set to 'mint_mcsn' to force Atari MCSN audio driver
110 Set to 'mint_stfa' to force Atari STFA audio driver
111 Set to 'mint_xbios' to force Atari Xbios audio driver
112 Set to 'mint_dma8' to force Atari 8 bits DMA audio driver
113 Set to 'audio' to force Sun /dev/audio audio driver
114 Set to 'disk' to force disk-writing audio driver
115
116SDL_ATARI_EVENTSDRIVER
117 Set to 'ikbd' to force IKBD 6301 keyboard driver
118 Set to 'gemdos' to force gemdos keyboard driver
119 Set to 'bios' to force bios keyboard driver
120
121SDL_JOYSTICK_ATARI:
122 Use any of these strings in the environment variable to enable or
123 disable a joystick:
124
125 'ikbd-joy1-[on|off]' for IKBD joystick on port 1 (hardware access)
126 'xbios-joy1-[on|off]' for IKBD joystick on port 1 (xbios access)
127 'porta-pad-[on|off]' for joypad and/or teamtap on port A
128 'porta-joy0-[on|off]' for joystick 0 on port A
129 'porta-joy1-[on|off]' for joystick 1 on port A
130 'porta-lp-[on|off]' for lightpen on port A
131 'porta-anpad-[on|off]' for analog paddle on port A
132 'portb-pad-[on|off]' for joypad and/or teamtap on port B
133 'portb-joy0-[on|off]' for joystick 0 on port B
134 'portb-joy1-[on|off]' for joystick 1 on port B
135 'portb-anpad-[on|off]' for analog paddle on port B
136
137 Default configuration is:
138 'ikbd-joy1-on' (if IKBD events driver enabled)
139 'xbios-joy1-on' (if gemdos/bios/gem events driver enabled)
140 'porta-pad-on portb-pad-on' (if available on the machine)
141
142 port[a|b]-[pad|joy?|lp|anpad]-* strings are mutually exclusives.
143 On such a port, you can only use a joypad OR 1 or 2 joysticks OR
144 a lightpen OR an analog paddle. You must disable joypad before
145 setting another controller.
146
147 The second joystick port on IKBD is used by the mouse, so not usable.
148 Another problem with the IKBD: mouse buttons and joystick fire buttons
149 are wired together at the hardware level, it means:
150 port 0 port 0 port 1
151 mouse left button = joystick fire 0 = joystick fire 1
152 mouse right button = joystick fire 1 = joystick fire 0
153
154 Descriptions of joysticks/joypads:
155 - Joypads: 1 hat, 17 buttons (Atari Jaguar console-like).
156 - Joysticks: 1 hat, 1 button.
157 - Lightpen, analog paddles: 2 axis, 2 buttons. The 2 buttons are those
158 affected to 1 button joysticks on the same port.
159
160==============================================================================
161VI. More informations about drivers:
162
163OpenGL:
164 The default is to use the Mesa offscreen driver (osmesa.ldg). If you want
165 to use an older OpenGL implementation, like mesa_gl.ldg or tiny_gl.ldg,
166 your program must use SDL_GL_LoadLibrary() to do so, and retrieve the
167 needed function pointers with SDL_LoadFunction(). In all cases, the OpenGL
168 context is taken care of by SDL itself, you just have to use gl* functions.
169
170 However, there is one OpenGL call that has a different prototype in the old
171 implementations: glOrtho(). In the old implementations, it has 6 float as
172 parameters, in the standard one, it has 6 double parameters. If you want
173 to compile testdyngl, or any other SDL program that loads its OpenGL
174 library, you must change the glOrtho() prototype used in this program. In
175 osmesa.ldg, you can retrieve a glOrtho() with double parameters, by
176 searching for the function "glOrtho6d".
177
178Xbios video:
179 Video chip is detected using the _VDO cookie.
180 Screen enhancers are not supported, but could be if you know how to
181 use them.
182
183 ST, STE, Mega ST, Mega STE:
184 320x200x4 bits, shades of grey, available only for the purpose
185 of testing SDL.
186 TT:
187 320x480x8 and 320x240x8 (software double-lined mode).
188 Falcon:
189 All modes supported by the current monitor (RVB or VGA).
190 BlowUp and Centscreen extended modes, ScreenBlaster 3 current mode.
191 Milan:
192 Experimental support
193 Clones and any machine with monochrome monitor:
194 Not supported.
195
196Gem video:
197 Automatically used if xbios not available.
198
199 All machines:
200 Only the current resolution, if 8 bits or higher depth.
201
202IKBD keyboard, mouse and joystick driver:
203 Available if _MCH cookie is ST, Mega ST, STE, Mega STE, TT or Falcon.
204
205 Hades has an IKBD, but xbios is not available for video, so IKBD
206 driver is disabled.
207
208Gemdos and bios keyboard driver:
209 Available on all machines.
210
211Mouse and joystick xbios driver:
212 Available on all machines (I think).
213
214Joypad driver:
215 Available if _MCH cookie is STE or Falcon. Supports teamtap.
216
217PTH timer driver:
218 Available with multitasking OS.
219
220VBL timer driver:
221 Available on all machines (I think).
222
223Audio drivers:
224 Cookies _SND, MCSN, STFA and GSXB used to detect supported audio
225 capabilities.
226
227 STE, Mega STE, TT:
228 8 bits DMA (hardware access)
229 STFA, MCSN or GSXB driver if installed
230 Falcon:
231 8 bits DMA (hardware access)
232 Xbios functions
233 STFA, MCSN or GSXB driver if installed
234 Other machines:
235 STFA, MCSN or GSXB driver if installed
236
237 STFA driver:
238 http://removers.free.fr/softs/stfa.html
239 GSXB driver:
240 http://assemsoft.atari.org/gsxb/
241 MacSound driver:
242 http://jf.omnis.ch/software/tos/
243 MagicSound driver (MCSN,GSXB compatible):
244 http://perso.wanadoo.fr/didierm/
245 X-Sound driver (GSXB compatible):
246 http://www.uni-ulm.de/~s_thuth/atari/xsound_e.html
247
248--
249Patrice Mandin <patmandin@gmail.com>
250http://pmandin.atari.org/
251
README.NanoX
1 =================================================================
2 Patch version 0.9 of SDL(Simple DirectMedia Layer) for Nano-X API
3 =================================================================
4
5 Authors: Hsieh-Fu Tsai, clare@setabox.com
6 Greg Haerr, greg@censoft.com
7
8 This patch is against SDL version 1.2.4.
9 It enhances previous patch 0.8 by providing direct framebuffer
10 access as well as dynamic hardware pixel type support, not
11 requiring a compile-time option setting for different framebuffer
12 modes.
13 Tested against Microwindows version 0.89pre9.
14
15 Older Microwindows versions
16 ===========================
17 If running on a version older than Microwindows 0.89pre9,
18 the following items might need to be patched in Microwindows.
19
20 1. Patch src/nanox/client.c::GrClose()
21 It fixes the client side GrClose(). In the original version,
22 GrOpen() can only be called once. When the GrOpen() is called at
23 the second time, the program will terminate. In order to prevent
24 this situation, we need to insert "nxSocket = -1" after
25 "close(nxSocket)" in GrClose(). If you do not have this problem,
26 you may skip this step.
27
28 2. Patch src/nanox/clientfb.c to return absolute x,y coordinates
29 when using GrGetWindowFBInfo(). Copy the version 0.89pre9
30 of src/nanox/clientfb.c to your system, or configure
31 using --disable-nanox-direct-fb.
32
33 =============
34 Quick Install
35 =============
36
37 1. ./configure --disable-video-x11 --disable-video-fbcon \
38 --enable-video-nanox \
39 --with-nanox-pixel-type=[rgb/0888/888/565/555/332/pal]
40 2. make clean
41 3. make
42 4. make install (as root)
43
44 ============
45 Nitty-gritty
46 ============
47
48 --enable-nanox-direct-fb Use direct framebuffer access
49 --enable-nanox-debug Show debug messages
50 --enable-nanox-share-memory Use shared-memory to speed up
51
52 When running multi-threaded applications using SDL, such
53 as SMPEG, set THREADSAFE=Y in Microwindows' config file,
54 to enable GrXXX() system call critical section support.
55
56 =============================================
57 Some programs can be used to test this patch.
58 =============================================
59
60 1. http://www.cs.berkeley.edu/~weimer/atris (a tetris-like game)
61 2. http://www.libsdl.org/projects/newvox/
62 3. http://www.libsdl.org/projects/xflame/
63 4. http://www.libsdl.org/projects/optimum/
64 5. http://www.gnugeneration.com/software/loop/
65 6: http://www.lokigames.com/development/smpeg.php3 (SMPEG version 0.4.4)
66
67 =========
68 Todo List
69 =========
70
71 1. Create hardware surface
72 2. Create YUVOverlay on hardware
73 3. Use OpenGL
74 4. Gamma correction
75 5. Hide/Change mouse pointer
76 6. Better window movement control with direct fb access
77 7. Palette handling in 8bpp could be improved
78
79 =====================
80 Supporting Institutes
81 =====================
82
83 Many thanks to go to Setabox Co., Ltd. and CML (Communication and
84 Multimedia Laboratory, http://www.cmlab.csie.ntu.edu.tw/) in the
85 Department of Computer Science and Information Engineering of
86 National Taiwan University for supporting this porting project.
87
88 Century Embedded Technologies (http://embedded.censoft.com)
89 for this patch.
90
91 ===================
92 Contact Information
93 ===================
94
95 Welcome to give me any suggestion and to report bugs.
96 My e-mail address : clare@setabox.com or niky@cmlab.csie.ntu.edu.tw
97 or greg@censoft.com
98
README.NDS
README.OS2
1
2===========
3SDL on OS/2
4===========
5
6Last updated on May. 17, 2006.
7
8
91. How to compile?
10------------------
11
12To compile this, you'll need the followings installed:
13- The OS/2 Developer's Toolkit
14- The OpenWatcom compiler
15 (http://www.openwatcom.org)
16
17First of all, you have to unzip the Watcom-OS2.zip file. This will result in a
18file called "makefile" and a file called "setvars.cmd" in this folder (and some
19more files...).
20
21Please edit the second, fourth and fifth lines of setvars.cmd file
22to set the folders where the toolkit, the OW compiler and the FSLib are.
23You won't need NASM yet (The Netwide Assembler), you can leave that line.
24Run setvars.cmd, and you should get a shell in which you can
25compile SDL.
26
27Check the "makefile" file. There is a line in there which determines if the
28resulting SDL.DLL will be a 'debug' or a 'release' build. The 'debug' version
29is full of printf()'s, so if something goes wrong, its output can help a lot
30for debugging.
31
32Then run "wmake".
33This should create the SDL12.DLL and the corresponding SDL12.LIB file here.
34
35To test applications, it's a good idea to use the 'debug' build of SDL, and
36redirect the standard output and standard error output to files, to see what
37happens internally in SDL.
38(like: testsprite >stdout.txt 2>stderr.txt)
39
40To rebuild SDL, use the following commands in this folder:
41wmake clean
42wmake
43
44
45
462. How to compile the testapps?
47-------------------------------
48
49Once you have SDL12.DLL compiled, navigate into the 'test' folder, copy in
50there the newly built SDL12.DLL, and copy in there FSLib.DLL.
51
52Then run "wmake" in there to compile some of the testapps.
53
54
55
563. What is missing?
57-------------------
58
59The following things are missing from this SDL implementation:
60- MMX, SSE and 3DNOW! optimized video blitters?
61- HW Video surfaces
62- OpenGL support
63
64
65
664. Special Keys / Full-Screen support
67-------------------------------------
68
69There are two special hot-keys implemented:
70- Alt+Home switches between fullscreen and windowed mode
71- Alt+End simulates closing the window (can be used as a Panic key)
72Only the LEFT Alt key will work.
73
74
75
765. Joysticks on SDL/2
77---------------------
78
79The Joystick detection only works for standard joysticks (2 buttons, 2 axes
80and the like). Therefore, if you use a non-standard joystick, you should
81specify its features in the SDL_OS2_JOYSTICK environment variable in a batch
82file or CONFIG.SYS, so SDL applications can provide full capability to your
83device. The syntax is:
84
85SET SDL_OS2_JOYSTICK=[JOYSTICK_NAME] [AXES] [BUTTONS] [HATS] [BALLS]
86
87So, it you have a Gravis GamePad with 4 axes, 2 buttons, 2 hats and 0 balls,
88the line should be:
89
90SET SDL_OS2_JOYSTICK=Gravis_GamePad 4 2 2 0
91
92If you want to add spaces in your joystick name, just surround it with
93quotes or double-quotes:
94
95SET SDL_OS2_JOYSTICK='Gravis GamePad' 4 2 2 0
96
97or
98
99SET SDL_OS2_JOYSTICK="Gravis GamePad" 4 2 2 0
100
101 Notive However that Balls and Hats are not supported under OS/2, and the
102value will be ignored... but it is wise to define these correctly because
103in the future those can be supported.
104 Also the number of buttons is limited to 2 when using two joysticks,
1054 when using one joystick with 4 axes, 6 when using a joystick with 3 axes
106and 8 when using a joystick with 2 axes. Notice however these are limitations
107of the Joystick Port hardware, not OS/2.
108
109
110
1116. Proportional windows
112-----------------------
113
114For some SDL applications it can be handy to have proportional windows, so
115the windows will keep their aspect ratio when resized.
116This can be achieved in two ways:
117
118- Before starting the given SDL application, set the
119 SDL_USE_PROPORTIONAL_WINDOW environment variable to something, e.g.:
120
121 SET SDL_USE_PROPORTIONAL_WINDOW=1
122 dosbox.exe
123
124- If you have a HOME environment variable set, then SDL will look for a file
125 in there called ".sdl.proportionals". If that file contains the name of the
126 currently running SDL executable, then that process will have proportional
127 windows automatically.
128
129 Please note that this file is created automatically with default values
130 at the first run.
131
132
133
1347. Audio in SDL applications
135----------------------------
136
137Audio effects are one of the most important features in games. Creating audio
138effects in sync with the game and without hickups and pauses in the audio are
139very important things.
140
141However there are multithreaded SDL applications that have tight loops as their
142main logic loop. This kills performance in OS/2, and takes too much CPU from
143other threads in the same process, for example from the thread to create the
144sound effects.
145
146For this reason, the OS/2 port of SDL can be instructed to run the audio thread
147in high priority, which makes sure that there will be enough time for the
148processing of the audio data.
149
150At default, SDL/2 runs the audio thread at ForegroundServer+0 priority. Well
151written and well behaving SDL applications should work well in this mode.
152For other applications, you can tell SDL/2 to run the audio thread at
153TimeCritical priority by setting an env.variable before starting the SDL app:
154
155 SET SDL_USE_TIMECRITICAL_AUDIO=1
156
157Please note that this is a bit risky, because if the SDL application runs a
158tight infinite loop in this thread, this will make the whole system
159unresponsive, so use it with care, and only for applications that need it!
160
161
162
1638. Next steps...
164----------------
165
166Things to do:
167- Implement missing stuffs (look for 'TODO' string in source code!)
168- Finish video driver (the 'wincommon' can be a good example for missing
169 things like application icon and so on...)
170- Enable MMX/SSE/SSE2 acceleration functions
171- Rewrite CDROM support using DOS Ioctl for better support.
172
173
174
1759. Contacts
176-----------
177
178 You can contact the developers for bugs:
179
180 Area Developer email
181 General (Audio/Video/System) Doodle doodle@scenergy.dfmk.hu
182 CDROM and Joystick Caetano daniel@caetano.eng.br
183
184 Notice however that SDL/2 is 'in development' stage so ... if you want to help,
185please, be our guest and contact us!
186
187
188
18910. Changelog of the OS/2 port
190------------------------------
191
192Version 1.2.10 - 2006-05-17 - Doodle
193 - Small modifications for v1.2.10 release
194 - Changed DLL name to include version info (currently SDL12.dll)
195
196Version 1.2 - 2006-05-01 - Doodle
197 - Modified makefile system to have only one makefile
198 - Included FSLib headers, DLL and LIB file
199
200Version 1.2 - 2006-02-26 - Doodle
201 - Updated the official SDL version with the OS/2 specific changes.
202 - Added support for real unicode keycode conversion.
203
204Version 1.2.7 - 2006-01-20 - Doodle
205 - Added support for selectively using timecritical priority for
206 audio threads by SDL_USE_TIMECRITICAL_AUDIO environment variable.
207 (e.g.:
208 SET SDL_USE_TIMECRITICAL_AUDIO=1
209 dosbox.exe
210 )
211
212Version 1.2.7 - 2005-12-22 - Doodle
213 - Added support for proportional SDL windows.
214 There are two ways to have proportional (aspect-keeping) windows for
215 a given SDL application: Either set the SDL_USE_PROPORTIONAL_WINDOW
216 environment variable to something before starting the application
217 (e.g.:
218 SET SDL_USE_PROPORTIONAL_WINDOW=1
219 dosbox.exe
220 )
221 or, if you have the HOME environment variable set, then SDL12.DLL will
222 create a file in that directory called .sdl.proportionals, and you can
223 put there the name of executable files that will be automatically made
224 proportional.
225
226Version 1.2.7 - 2005-10-14 - Doodle
227 - Enabled Exception handler code in FSLib to be able to restore original
228 desktop video mode in case the application crashes.
229 - Added the missing FSLib_Uninitialize() call into SDL.
230 (The lack of it did not cause problems, but it's cleaner this way.)
231 - Fixed a mouse problem in Fullscreen mode where any mouse click
232 re-centered the mouse.
233
234Version 1.2.7 - 2005-10-09 - Doodle
235 - Implemented window icon support
236
237Version 1.2.7 - 2005-10-03 - Doodle
238 - Reworked semaphore support again
239 - Tuned thread priorities
240
241Version 1.2.7 - 2005-10-02 - Doodle
242 - Added support for custom mouse pointers
243 - Fixed WM_CLOSE processing: give a chance to SDL app to ask user...
244 - Added support for MMX-accelerated audio mixers
245 - Other small fixes
246
247Version 1.2.7 - 2005-09-12 - Doodle
248 - Small fixes for DosBox incorporated into public release
249 - Fixed semaphore support (SDL_syssem.c)
250 - Fixed FSLib to have good clipping in scaled window mode,
251 and to prevent occasional desktop freezes.
252
253Version 1.2.7 - 2004-09-08a - Caetano
254 - Improved joystick support (general verifications about hardware).
255 - Added support up to 8 buttons in 2 axes joysticks and 6 buttons in 3 axes joysticks.
256 - Added support to environment variable SDL_OS2_JOYSTICK to specify a joystick.
257 - Improved Joystick test to handle every type of joystick and display only relevant information.
258 - Merged with Doodle 2004-09-08
259 - Little tid up in README.OS2
260 - Added explanation about SDL_OS2_JOYSTICK environment variable on README.OS2
261
262Version 1.2.7 - 2004-09-07 - Caetano
263 - Merged with changes in headers for GCC compiling.
264 - Added Joystick support using basic IBM GAME$ support, allowing it to work with all joystick drivers since OS/2 2.1.
265 - Improved joystick detection (hacked!). OS/2 do not allow real joystick detection, so...
266 - Modified makefile in test to compile "testjoystick". Anyway, it's useless, since it seems to cause a lot of trouble in OS/2 (because os video routines, not Joystick support).
267 - Created separated Joystick test program to test only joystick functions.
268 - Improved joystick auto-centering.
269 - Improved the coordinate correction routine to use two scale factors for each axis.
270
271Version 1.2.7 - 2004-07-05 - Caetano
272 - Corrected the time returned by status in CDROM support (it was incorrect)
273 - Added the testcdrom.c and corrected the linking directive (it was causing an error)
274
275Version 1.2.7 - 2004-07-02a - Caetano
276 - Corrected a little problem in a comment at SDL-1.2.7\test\torturethread.c, line 18 (missing */, nested comment)
277 - Added CDROM support to tree (SDL-1.2.7\src\cdrom\os2\SDL_syscdrom.c)
278 - Modified makefile (SDL-1.2.7\src\makefiles.wat and SDL-1.2.7\watcom.mif) to build with CDROM support
279 - Added the "extra" SDL_types.h forgotten in 2004-07-02 version.
280
281<End-Of-File>
282
README.PicoGUI
1 ========================
2 Using SDL with PicoGUI
3 ========================
4
5- Originally contributed by Micah Dowty <micahjd@users.sourceforge.net>
6
7PicoGUI is a scalable GUI system with a unique architecture, primarily focused
8on scalability to various embedded systems. You can find more information
9including a FAQ at http://picogui.org
10
11To use the patch:
12
13 1. When compiling, add the "--enable-video-picogui" switch to ./configure
14
15 2. When running your program, ensure that the picogui driver for SDL
16 is in use by setting the SDL_VIDEODRIVER environment variable
17 to "picogui".
18
19 3. The program must also be linked to the C client library for PicoGUI
20 (libpgui.so). If the program is being compiled with a patched SDL
21 installed this should be done automatically. If you want to use an
22 existing binary with PicoGUI, you can set the LD_PRELOAD environment
23 variable to the path of your libpgui.so file.
24
25Capabilities:
26
27 So far only basic functionality is provided on true color (linear16/24/32)
28 devices. Accessing a memory mapped bitmap, updating the display, and handling
29 mouse/keyboard input. This functionality has been tested with several
30 applications, including mplayer, Xine, sldroids, and Abuse.
31
32TODO list:
33
34 - YUV overlays will be helpful for watching video on set top boxes or other
35 embedded devices that have some graphics acceleration hardware
36
37 - Account for rotated bitmap storage in pgserver
38
39 - Support for hiding or changing the cursor
40
41 - The display should be centered when the SDL application is smaller
42 than the PicoGUI panel
43
44 - Fullscreen or any other special modes
45
46 - Support for indexed and grayscale modes
47
48 - Probably much more...
49
50--- The End ---
51
README.Porting
1
2* Porting To A New Platform
3
4 The first thing you have to do when porting to a new platform, is look at
5include/SDL_platform.h and create an entry there for your operating system.
6The standard format is __PLATFORM__, where PLATFORM is the name of the OS.
7Ideally SDL_platform.h will be able to auto-detect the system it's building
8on based on C preprocessor symbols.
9
10There are two basic ways of building SDL at the moment:
11
121. The "UNIX" way: ./configure; make; make install
13
14 If you have a GNUish system, then you might try this. Edit configure.in,
15 take a look at the large section labelled:
16 "Set up the configuration based on the target platform!"
17 Add a section for your platform, and then re-run autogen.sh and build!
18
192. Using an IDE:
20
21 If you're using an IDE or other non-configure build system, you'll probably
22 want to create a custom SDL_config.h for your platform. Edit SDL_config.h,
23 add a section for your platform, and create a custom SDL_config_{platform}.h,
24 based on SDL_config.h.minimal and SDL_config.h.in
25
26 Add the top level include directory to the header search path, and then add
27 the following sources to the project:
28 src/*.c
29 src/audio/*.c
30 src/cdrom/*.c
31 src/cpuinfo/*.c
32 src/events/*.c
33 src/file/*.c
34 src/joystick/*.c
35 src/stdlib/*.c
36 src/thread/*.c
37 src/timer/*.c
38 src/video/*.c
39 src/audio/disk/*.c
40 src/video/dummy/*.c
41 src/joystick/dummy/*.c
42 src/cdrom/dummy/*.c
43 src/thread/generic/*.c
44 src/timer/dummy/*.c
45 src/loadso/dummy/*.c
46
47
48Once you have a working library without any drivers, you can go back to each
49of the major subsystems and start implementing drivers for your platform.
50
51If you have any questions, don't hesitate to ask on the SDL mailing list:
52 http://www.libsdl.org/mailing-list.php
53
54Enjoy!
55 Sam Lantinga (slouken@libsdl.org)
56
57
README.PS3
README.QNX
1README.QNX by Mike Gorchak <mike@malva.ua>, <lestat@i.com.ua>
2Last changed at 24 Apr 2004.
3
4======================================================================
5Table of Contents:
6
71. OpenGL.
82. Wheel and multi-button mouses.
93. CDROM handling issues.
104. Hardware video overlays.
115. Shared library building.
126. Some building issues.
137. Environment variables.
14
15======================================================================
161. OpenGL:
17
18 OpenGL works well and is stable, but fullscreen mode has not been
19heavily tested yet.
20 If you have QNX RtP version 6.1.0 or above you must download the
21Photon3D runtime from http://developers.qnx.com or install it from the
22public repository or from the public CD, available with QNX. OS versi-
23ons below 6.1.0 are not supported.
24 When creating an OpenGL context, software renderer mode is artifi-
25cially selected (QSSL made acceleration only for Voodoo boards in
26fullscreen mode, sorry but I don't have this board to test OpenGL -
27maybe it works or maybe not :)). If you want acceleration - you can
28remove one line in the source code: find the file SDL_ph_image.c and
29remove the following
30
31 OGLAttrib[OGLargc++]=PHOGL_ATTRIB_FORCE_SW;
32
33line in the ph_SetupOpenGLContext() function or change the argument to
34PHOGL_ATTRIB_FORCE_HW or PHOGL_ATTRIB_FAVOR_HW.
35
36======================================================================
372. Wheel and multi-button mouses:
38
39 Photon emits keyboard events (key up and down) when the mouse
40wheel is moved. The key_scan field appears valid, and it contains zero.
41That is a basic method of detecting mouse wheel events under Photon.
42It looks like a hack, but it works for me :) on various PC configura-
43tions.
44
45I've tested it on:
46
471. Genius Optical NetScroll/+ PS/2 (1 wheel)
482. A4Tech Optical GreatEye WheelMouse PS/2, model: WOP-35. (2 wheels
49 + 2 additional buttons). The wheel for vertical scrolling works as
50 usual, but the second wheel for horizontal scrolling emits two se-
51 quential events up or down, so it can provide faster scrolling than
52 the first wheel. Additional buttons don't emit any events, but it
53 looks like they're handled by photon in an unusual way - like click
54 to front, but works not with any window, looks like a fun bug-o-fe-
55 ature :).
56
57======================================================================
583. CDROM handling issues:
59
60 Access to CDROM can only be provided with 'root' privileges. I
61can't do anything about that, /dev/cd0 has brw------- permissions and
62root:root rights.
63
64======================================================================
654. Hardware video overlays:
66
67 Overlays can flicker during window movement, resizing, etc. It
68happens because the photon driver updates the real window contents be-
69hind the overlay, then draws the temporary chroma key color over the
70window contents. It can be done without using the chroma key but that
71causes the overlay to always be on top. So flickering during window
72movement is preferred instead.
73 Double buffering code is temporarily disabled in the photon driver
74code, because on my GF2-MX it can accidentally cause a buffer switch,
75which causes the old frame to show. S3 Savage4 has the same problem,
76but ATI Rage 128 doesn't. I think it can be fixed later. Current code
77works very well, so maybe double buffering is not needed right now.
78 Something strange happens when you try to move the window with the
79overlay beyond the left border of the screen. The overlay tries to
80stay at position x=0, but when attempting to move it a bit more it
81jumps to position x=-60 (on GF2-MX, on ATI Rage128 this value a bit
82smaller). It's really strange, looks like the overlay doesn't like
83negative coordinates.
84
85=======================================================================
865. Shared library building:
87
88 A shared library can be built, but before running the autogen.sh
89script you must manually delete the libtool.m4 stuff from the acinclu-
90de.m4 file (it comes after the ESD detection code up to the end of the
91file), because the libtool stuff in the acinclude.m4 file was very old
92in SDL distribution before the version 1.2.7 and doesn't knew anything
93about QNX. SDL 1.2.7 distribution contains the new libtool.m4 script,
94but anyway it is broken :), Just remove it, then run "libtoolize
95--force --copy", delete the file aclocal.m4 if it is exists and after
96that run the autogen.sh script. SDL 1.2.8 contains fixed libtool.m4,
97ltmain.sh and config.sub files, so you can just run the autogen.sh
98script.
99
100======================================================================
1016. Some building issues:
102
103 Feel free to not use the --disable-shared configure option if you'
104ve read the above comment about 'Shared library building'. Otherwise
105this option is strongly recommended, as without it the sdl-config
106script will be broken.
107
108 Run the configure script without x11 support, e.g.:
109
110 a) for OpenGL support:
111 ./configure --prefix=/usr \
112 --disable-video-x11 \
113 --disable-shared
114
115 b) without OpenGL support:
116 ./configure --prefix=/usr \
117 --disable-video-x11 \
118 --disable-shared \
119 --disable-video-opengl
120
121 And of course dont forget to specify --disable-debug, which is on
122by default, to disable debug and enable the expensive optimizations.
123
124 In the test directory also run the ./configure script without
125x11 support, e.g.:
126
127 ./configure --with-sdl-prefix=/usr \
128 --with-sdl-exec-prefix=/usr \
129 --prefix=/usr --without-x
130
131======================================================================
1327. Environment variables:
133
134 Please note that the photon driver is sensible to the following
135environmental variables:
136
137 * SDL_PHOTON_FULLSCREEN_REFRESH - this environment variable controls
138the refresh rate in all fullscreen modes. Be carefull !!! Photon
139drivers usually do not checking the maximum refresh rate, which video
140adapter or monitor supports.
141
142 * SDL_VIDEO_WINDOW_POS - can be set in the "X,Y" format. If X and Y
143coordinates are bigger than the current desktop resolution, then win-
144dow positioning across virtual consoles is activated. If X and Y are
145smaller than the desktop resolution then window positioning in the
146current console is activated. The word "center" can be used instead of
147coordinates, it produces the same behavior as SDL_VIDEO_CENTERED
148environmental variable.
149
150 * SDL_VIDEO_CENTERED - if this environmental variable exists then the
151window centering is perfomed in the current virtual console.
152
153Notes: The SDL_VIDEO_CENTERED enviromental variable has greater pri-
154ority than the SDL_VIDEO_WINDOW_POS in case if both variables are sup-
155plied to the application.
156
README.Qtopia
1
2==============================================================================
3Using the Simple DirectMedia Layer with Qtopia/OPIE
4==============================================================================
5
6==============================================================================
7I. Setting up the Qtopia development environment.
8
9 This document will not explain how to setup the Qtopia development
10 environment. That is outside the scope of the document. You can read
11 more on this subject in this excellent howto:
12
13 http://www.zauruszone.com/howtos/linux_compiler_setup_howto.html
14
15==============================================================================
16II. Building the Simple DirectMedia Layer libraries using the arm
17 cross-compiler
18
19 This is somewhat tricky since the name of the compiler binaries
20 differ from the standard. Also you should disable features not
21 needed. The command below works for me. Note that it's all one
22 line. You can also set the NM, LD etc environment variables
23 separately.
24
25 NM=arm-linux-nm LD=arm-linux-ld CC=arm-linux-gcc CXX=arm-linux-g++ RANLIB=arm-linux-ranlib AR=arm-linux-ar ./configure --enable-video-qtopia --disable-video-dummy --disable-video-fbcon --disable-video-dga --disable-arts --disable-esd --disable-alsa --disable-cdrom --disable-video-x11 --disable-nasm --prefix=/opt/Qtopia/sharp/ arm-unknown-linux-gnu
26
27 One thing to note is that the above configure will include joystick
28 support, even though you can't have joysticks on the Zaurus. The
29 reason for this is to avoid link / compile / runtime errors with
30 applications that have joystick support.
31
32==============================================================================
33III. Building the Simple DirectMedia Layer test programs:
34
35 After installing, making sure the correct sdl-config is in your
36 path, run configure like this:
37
38 NM=arm-linux-nm LD=arm-linux-ld CC=arm-linux-gcc CXX=arm-linux-g++ AR=arm-linux-ar ./configure arm-unknown-linux-gnu
39
40==============================================================================
41IV. Application porting notes
42
43 One thing I have noticed is that applications sometimes don't exit
44 correctly. Their icon remains in the taskbar and they tend to
45 relaunch themselves automatically. I believe this problem doesn't
46 occur if you exit your application using the exit() method. However,
47 if you end main() with 'return 0;' or so, this seems to happen.
48
49 Also note that when running in landscape mode - i.e requesting a
50 window that is HEIGHT pixels wide and WIDTH pixels high, where WIDTH
51 and HEIGHT normally is 240 and 320 - the image is blitted so that
52 the hardware buttons are on the left side of the display. This might
53 not always be desirable but such is the code today.
54
55
56==============================================================================
57V. Enjoy! :)
58
59 If you have a project you'd like me to know about, or want to ask questions,
60 go ahead and join the SDL developer's mailing list by sending e-mail to:
61
62 sdl-request@libsdl.org
63
64 and put "subscribe" into the subject of the message. Or alternatively you
65 can use the web interface:
66
67 http://www.libsdl.org/mailman/listinfo/sdl
68
69==============================================================================
70VI. What is supported:
71
72Keyboard (Sharp Zaurus)
73Hardware buttons
74Stylus input (mouse)
75Video. Allows fullscreen both in portrait mode (up to WIDTHxHEIGHT
76size window) and in landscape mode (up to HEIGHTxWIDTH).
77
78All other SDL functionality works like a normal Linux system (threads,
79audio etc).
80
81--
82David Hedbor <david@hedbor.org>
83http://david.hedbor.org/ http://eongames.com/
84
85
README.RISCOS
1Readme for RISC OS port of SDL
2==============================
3
4This document last updated on 2nd Februrary 2006
5
6This is a RISC OS port of the Simple Direct Media Layer (SDL) by Alan Buckley with contributions from Peter Naulls.
7
8Details of the SDL can be found at http://www.libsdl.org.
9
10The source code including the RISC OS version can be obtained from:
11
12http://www.libsdl.org.
13
14Pre built libraries and many games and applications compiled for RISC OS using this library can be downloaded from The Unix Porting Project at http://www.riscos.info/unix/.
15
16This is released under the LGPL see the file COPYING for details.
17
18
19Compiling applications under RISC OS
20====================================
21
22Add -ISDL: for the C compiler flags if you include the files in the SDL directory. e.g. #include "SDL/SDL.h"
23Add -ISDL:SDL for the C compiler flags if you include the files directly. e.g. #include "SDL/SDL.h"
24
25Add -LSDL: -lSDL to the link stage of compilation.
26
27For example, to compile the testbitmap.c sample you could use:
28
29gcc -ISDL:SDL -LSDL: -lSDL testbitmap.c -otestbitmap
30
31
32RISC OS port of SDL runtime information
33=======================================
34
35Runtime requirements
36--------------------
37
38This library currently needs a minimum of RISC OS 3.6. The source code for the library (and a lot of the programs built with it) also need long file names.
39
40To use the audio you also need 16 bit sound and to have installed the DigitalRender module by Andreas Dehmel version 0.51 available from his
41web site: http://home.t-online.de/~zarquon
42This is loaded when needed by UnixLib.
43
44Note: As most programs ported from other OSes use high resolution graphics and a memory back buffer a machine with a StrongARM processor and 1 or 2MB of VRAM (or a better machine) is recomended.
45
46
47RISC OS runtime parameters
48--------------------------
49
50Several environmental variables have been defined to make porting programs easier (i.e. By setting these variable you do not need to have source code differences between OSes).
51
52They are all defined on an application basis.
53
54The <appname> used below is found as follows:
551. Use the name of the program unless it is !RunImage
562. Check the folder specification for the folder !RunImage is run from. If it is a folder name use that name, otherwise if it is an environmental variable of the form <XXX$Dir> use the value of XXX.
57
58The variables are:
59
60SDL$<appname>$TaskName
61
62The name of the task for RISC OS. If omitted then <appname> is used for the task name,
63
64SDL$<appname>$BackBuffer
65
66Set to 1 to use a system memory back buffer for the screen in full screen mode. Some programs on other systems assume their is always a back buffer even though the SDL specification specifies this is not the case. The current RISC OS implementation uses direct writes to the screen if a hardware fullscreen is requested.
67
68Set to 2 to use an ARM code full word copy. This is faster than the standard back buffer, but uses aligned words only so it is possible (but unlikely) for it to corrupt the screen for 8bpp and 16bpp modes.
69
70Set to 3 to use a RISC OS sprite as the back buffer. This is usually the slowest for most SDL applications, however it may be useful in the future as Sprite acceleration is added to various hardware that runs RISC OS.
71
72SDL$<appname>$CloseAction - set the action for the close icon. Again as programs don't match the specification you can set this to 0 to remove the close icon from the main window for applications where this does not affect the program.
73
74
75RISC OS SDL port API notes
76==========================
77
78Current level of implementation
79-------------------------------
80
81The following list is an overview of how much of the SDL is implemented. The areas match the main areas of the SDL.
82
83video - Mostly done. Doesn't cover gamma, YUV-overlay or OpenGL.
84Window Manager - Mostly done. SetIcon/IconifyWindow not implemented.
85Events - Mostly done. Resize and some joystick events missing.
86Joystick - Currently assumes a single joystick with 4 buttons.
87Audio - Done
88CDROM - Not implemented.
89Threads - Done
90Timers - Done
91
92Thread support can be removed by defining DISABLE_THREADS and recompiling the library.
93
94SDL API notes
95-------------
96
97This section contains additional notes on some specific commands.
98
99SDL_SetVideoMode
100 On RISC OS a fullscreen mode directly accesses the screen. This can be modified by the environmental variable (SDL$<appname>$BackBuffer) or by using the SDL_SWSURFACE flag to write to an offscreen buffer that is updated using SDL_UpdateRects.
101 Open GL is not supported so SDL_OPENGL and SDL_OPENGLBLIT flags fail.
102 SDL_RESIZEABLE and SDL_NOFRAME flags are not supported.
103
104SDL_SetColors
105 In a wimp mode the screen colours are not changed for a hardware palette instead the RISC OS sprite colour mapping is used to get the best matching colours.
106
107SDL_CreateCursor
108 Inverted colour is not supported.
109
110SDL_WM_ToggleFullScreen
111 Currently this won't work if the application starts up in Fullscreen mode.
112 Toggling to fullscreen will only work if the monitor is set up to support the exact screen size requested.
113
114SDL_EnableUNICODE
115 Unicode translation used here is only really accurate for 7 bit characters.
116
117SDL_NumJoysticks/JoystickName etc.
118 Hardcoded to expect only 1 joystick with 4 buttons if the Joystick module is loaded.
119
120SDL_GetTicks
121 Timer used has only a centisecond accuracy. This applies to other time related functions.
122
123SDL_Delay
124 Modified to poll keyboard/mouse during the delay on the event thread.
125
126
127Notes on current implementation
128-------------------------------
129
130Keyboard and mouse are polled so if too long a time is spent between a call to SDL_PumpEvents, functions that use it, or SDL_Delay events can be missed.
131
README.Symbian
README.Watcom
1
2Using SDL under Windows with the OpenWatcom compiler
3====================================================
4
5Prerequisites
6-------------
7
8I have done the port under Windows XP Home with SP2 installed. Windows
92000 should also be working. I'm not so sure about ancient Windows NT,
10since only DirectX 3 is available there. Building should be possible,
11but running the compiled applications will probalbly fail with
12SDL_VIDEODRIVER=directx. The windib driver should work, though.
13
14To compile and use the SDL with Open Watcom you will need the following:
15- Open Watcom compiler. I used version 1.5. The environment variables
16 PATH, WATCOM and INCLUDE need to be set appropriately - please consult
17 the OpenWatcom documentation and instructions given during the
18 installation of the compiler.
19 My setup looks like this in owvars.bat:
20 set WATCOM=C:\watcom
21 set INCLUDE=%WATCOM%\h;%WATCOM%\h\nt
22 set PATH=%PATH%;%WATCOM%\binnt;%WATCOM%\binw
23- A fairly recent DirectX SDK. The original unmodified DX8 SDK works, as
24 well as the minimal DirectX 7 SDK from the Allegro download site
25 (<http://alleg.sourceforge.net/files/dx70_min.zip>).
26- The SDL sources from Subversion
27- The file Watcom-Win32.zip (now available in Subversion)
28
29
30Building the Library
31--------------------
32
331) In the SDL base directory extract the archive Watcom-Win32.zip. This
34 creates a subdirectory named 'watcom'.
352) The makefile expects the environment variable DXDIR to be set to the
36 base directory of a DirectX SDK. I have tried a stock DX8 SDK from
37 Microsoft as well as the minimal DirectX 7 SDK from the Allegro
38 download site.
39 You can also edit the makefile directly and hard code your path to
40 the SDK on your system.
41 I have this in my setup:
42 set DXDIR=D:\devel\DX8_SDK
433) Enter the watcom directory and run
44 wmake sdl
454) All tests from the test directory are working and can be built by
46 running
47 wmake tests
48
49Notes:
50
51 The makefile offers some options to tweak the way the library is built.
52 You have at your disposal the option to build a static (default)
53 library, or a DLL (with tgt=dll). You can also choose whether to build
54 a Release (default) or a Debug version (with build=debug) of the tests
55 and library. Please consult the usage comment at the top of the
56 makefile for usage instructions.
57
58 If you specify a test target (i.e. 'wmake tests' for all tests, or
59 selected targets like 'wmake testgl testvidinfo testoverlay2'), the
60 tests are always freshly compiled and linked. This is done to
61 minimise hassle when switching between library versions (static vs.
62 DLL), because they require subtly different options.
63 Also, the test executables are put directly into the test directory,
64 so they can find their data files. The clean target of the makefile
65 removes the test executables and the SDL.dll file from the test
66 directory.
67
68 To use the library in your own projects with Open Watcom, you can use
69 the way the tests are built as base of your own build environment.
70
71 The library can also be built with the stack calling convention of the
72 compiler (-6s instead of -6r).
73
74
75Test applications
76-----------------
77
78I've tried to make all tests work. The following table gives an overview
79of the current status.
80
81 Testname Status
82~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83checkkeys +
84graywin +
85loopwave +
86testalpha +
87testbitmap +
88testdyngl +
89testerror +
90testfile +
91testgamma +
92testgl +
93testhread +
94testiconv - (all failed)
95testkeys +
96testlock +
97testoverlay + (needs 'set SDL_VIDEODRIVER=directx')
98testoverlay2 + (needs 'set SDL_VIDEODRIVER=directx')
99testpalette +
100testplatform +
101testsem +
102testsprite +
103testtimer +
104testver +
105testvidinfo +
106testwin ? (fading doesn't seem right)
107testwm +
108torturethread +
109testcdrom +
110testjoystick not tested
111threadwin +
112testcursor +
113
114
115TODO
116----
117
118There is room for further improvement:
119- Test joystick functionality.
120- Investigate fading issue in 'testwin' test.
121- Fix the UTF-8 support.
122- Adapt the makefile/object file list to support more target systems
123- Use "#pragma aux" syntax for the CPU info functions.
124
125
126Questions and Comments
127----------------------
128
129Please direct any questions or comments to me: <mailto:macpete@gmx.de>
130
131 Happy Coding!
132
133 Marc Peter
134
README.WinCE
1
2Project files for embedded Visual C++ 3.0, 4.0 and
3Visual Studio 2005 can be found in the VisualCE directory.
4
5SDL supports GAPI and WinDib output for Windows CE.
6
7GAPI driver supports:
8
9- all possible WinCE devices (Pocket PC, Smartphones, HPC)
10 with different orientations of video memory and resolutions.
11- 4, 8 and 16 bpp devices
12- special handling of 8bpp on 8bpp devices
13- VGA mode, you can even switch between VGA and GAPI in runtime
14 (between 240x320 and 480x640 for example). On VGA devices you can
15 use either GAPI or VGA.
16- Landscape mode and automatic rotation of buttons and stylus coordinates.
17 To enable landscape mode make width of video screen bigger than height.
18 For example:
19 SDL_SetVideoMode(320,240,16,SDL_FULLSCREEN)
20- WM2005
21- SDL_ListModes
22
23NOTE:
24There are several SDL features not available in the WinCE port of SDL.
25
26- DirectX is not yet available
27- Semaphores are not available
28- Joystick support is not available
29- CD-ROM control is not available
30
31In addition, there are several features that run in "degraded" mode:
32
33Preprocessor Symbol Effect
34=================== =================================
35
36SDL_systimer.c:
37USE_GETTICKCOUNT Less accurate values for SDL time functions
38USE_SETTIMER Use only a single marginally accurate timer
39
40SDL_syswm.c:
41DISABLE_ICON_SUPPORT Can't set the runtime window icon
42
43SDL_sysmouse.c:
44USE_STATIC_CURSOR Only the arrow cursor is available
45
46SDL_sysevents.c:
47NO_GETKEYBOARDSTATE Can't get modifier state on keyboard focus
48
49SDL_dibevents.c:
50NO_GETKEYBOARDSTATE Very limited keycode translation
51
52SDL_dibvideo.c:
53NO_GETDIBITS Can't distinguish between 15 bpp and 16 bpp
54NO_CHANGEDISPLAYSETTINGS No fullscreen support
55NO_GAMMA_SUPPORT Gamma correction not available
56
README.wscons
1==============================================================================
2Using the Simple DirectMedia Layer with OpenBSD/wscons
3==============================================================================
4
5The wscons SDL driver can be used to run SDL programs on OpenBSD
6without running X. So far, the driver only runs on the Sharp Zaurus,
7but the driver is written to be easily extended for other machines.
8The main missing pieces are blitting routines for anything but 16 bit
9displays, and keycode maps for other keyboards. Also, there is no
10support for hardware palettes.
11
12There is currently no mouse support.
13
14To compile SDL with support for wscons, use the
15"--enable-video-wscons" option when running configure. I used the
16following command line:
17
18./configure --disable-oss --disable-ltdl --enable-pthread-sem \
19 --disable-esd --disable-arts --disable-video-aalib \
20 --enable-openbsdaudio --enable-video-wscons \
21 --prefix=/usr/local --sysconfdir=/etc
22
23
24Setting the console device to use
25=================================
26
27When starting an SDL program on a wscons console, the driver uses the
28current virtual terminal (usually /dev/ttyC0). To force the driver to
29use a specific terminal device, set the environment variable
30SDL_WSCONSDEV:
31
32bash$ SDL_WSCONSDEV=/dev/ttyC1 ./some-sdl-program
33
34This is especially useful when starting an SDL program from a remote
35login prompt (which is great for development). If you do this, and
36want to use keyboard input, you should avoid having some other program
37reading from the used virtual console (i.e., do not have a getty
38running).
39
40
41Rotating the display
42====================
43
44The display can be rotated by the wscons SDL driver. This is useful
45for the Sharp Zaurus, since the display hardware is wired so that it
46is correctly rotated only when the display is folded into "PDA mode."
47When using the Zaurus in "normal," or "keyboard" mode, the hardware
48screen is rotated 90 degrees anti-clockwise.
49
50To let the wscons SDL driver rotate the screen, set the environment
51variable SDL_VIDEO_WSCONS_ROTATION to "CW", "CCW", or "UD", for
52clockwise, counter clockwise, and upside-down rotation respectively.
53"CW" makes the screen appear correct on a Sharp Zaurus SL-C3100.
54
55When using rotation in the driver, a "shadow" frame buffer is used to
56hold the intermediary display, before blitting it to the actual
57hardware frame buffer. This slows down performance a bit.
58
59For completeness, the rotation "NONE" can be specified to use a shadow
60frame buffer without actually rotating. Unsetting
61SDL_VIDEO_WSCONS_ROTATION, or setting it to '' turns off the shadow
62frame buffer for maximum performance.
63
64
65Running MAME
66============
67
68Since my main motivation for writing the driver was playing MAME on
69the Zaurus, I'll give a few hints:
70
71XMame compiles just fine under OpenBSD.
72
73I'm not sure this is strictly necessary, but set
74
75MY_CPU = arm
76
77in makefile.unix, and
78
79CFLAGS.arm = -DLSB_FIRST -DALIGN_INTS -DALIGN_SHORTS
80
81in src/unix/unix.max
82
83to be sure.
84
85The latest XMame (0.101 at this writing) is a very large program.
86Either tinker with the make files to compile a version without support
87for all drivers, or, get an older version of XMame. My recommendation
88would be 0.37b16.
89
90When running MAME, DO NOT SET SDL_VIDEO_WSCONS_ROTATION! Performace
91is MUCH better without this, and it is COMPLETELY UNNECESSARY, since
92MAME can rotate the picture itself while drawing, and does so MUCH
93FASTER.
94
95Use the Xmame command line option "-ror" to rotate the picture to the
96right.
97
98
99Acknowledgments
100===============
101
102I studied the wsfb driver for XFree86/Xorg quite a bit before writing
103this, so there ought to be some similarities.
104
105
106--
107Staffan Ulfberg <staffan@ulfberg.se>
108