e5397ce6a3d6b04839d77dda7d5653f8ae3bcff8
[sdl_omap.git] / README.OMAP
1 OMAP specific SDL driver
2 by GraÅžvydas "notaz" Ignotas
3
4
5 About
6 -----
7
8 This is a quick SDL driver to make use of some OMAP features, namely double
9 buffering and hardware scaler.
10
11 Features:
12
13  * hardware scaling support (up and down)
14  * doublebuffering support (can eliminate tearing)
15  * vsync support (can give smooth scrolling if done right)
16  * keymap change with a config file
17  * 16/24/32bpp display support
18  * touchscreen input translation to scaler source image coordinates
19  * screen surface cropping / border removal support
20
21 Caveats:
22  * disabled by default (falls back to x11/fbcon SDL drivers) unless
23    SDL_VIDEODRIVER environment variable is set
24  * no windowed mode support, fullscreen only
25  * requires functional DSS2 driver with /dev/fb1 mapped to overlay1 or
26    overlay2 and enough free VRAM available for requested display mode.
27
28 Although this was created for pandora, there is nothing preventing this to work
29 on other OMAP platforms as well (well, nothing intentional at least).
30
31
32 Usage / environment
33 -------------------
34
35 To enable this driver, SDL_VIDEODRIVER environment variable must be set to
36 "omapdss". It can be set by calling setenv() in the code, but it's better to
37 just set it in launcher script so that it can be changed easily without
38 recompiling as needed:
39 ---
40 #!/bin/sh
41 export SDL_VIDEODRIVER=omapdss
42 ./your_program_here
43 ---
44
45 Other environment variables:
46
47 SDL_OMAP_LAYER_SIZE:
48   Output layer size. Regardless what you set with SDL_SetVideoMode(), output
49   will be scaled to this size using hardware with zero processing cost.
50   Note: scaling amount range is limited to roughly 1/4x-8x. The exact range
51   depends on various factors like version of the driver or OMAP hardware itself.
52   Valid values:
53     "WxH", for example "640x480"
54     "fullscreen" to cover whole screen.
55     "scaled" to upscale the screen proportionally, letterboxing or pillarboxing.
56     "pixelperfect" to upscale by a whole-number factor (e.g. 2x or 3x size).
57
58 SDL_OMAP_BORDER_CUT:
59   This can be used to move parts of SDL surface out of screen, in other
60   words cut borders and zoom in. Format: <left>,<right>,<top>,<bottom>
61   For example, "0,0,16,0" would hide top 16 lines offscreen, making 17th
62   (16th if you count from 0) line the first visible.
63   Note: like for layer size ranges are limited.
64
65 SDL_OMAP_VSYNC:
66   Enables waiting for vertical sync on SDL_Flip() calls.
67   Set to "1" to enable, "0" to disable.
68
69 SDL_OMAP_DEFAULT_MODE:
70   If the app doesn't specify resolution in SDL_SetVideoMode(), then use this.
71   Should be specified in "WxH" format, for example "640x480".
72
73 SDL_OMAP_FORCE_DOUBLEBUF:
74   This can force double buffering to on, which can help to eliminate tearing.
75   Note that if app isn't updating whole buffer each frame, it will glitch.
76   This is the same as specifying SDL_DOUBLEBUF to SDL_SetVideoMode.
77
78 SDL_OMAP_FORCE_DIRECTBUF:
79   When double buffering is not used, this option forces all blits to go
80   directly to the framebuffer (SDL_UpdateRect[s]() has no effect), which will
81   give speed but may cause flickering. Otherwise all blits will go to offscreen
82   buffer and SDL_UpdateRect[s]() is needed to update the screen (this is how
83   standard SDL works too).
84   When double buffering is used, this option has no effect (all blits always
85   go to back buffer that's displayed after flip).
86
87 SDL_OMAP_NO_TS_TRANSLATE:
88   Disable automatic touchscreen screen -> layer coordinate translation,
89   return real screen coordinates.
90
91 SDL_OMAP_TS_FORCE_TSLIB:
92   Always use tslib to read touchscreen. Without this, use X events when they
93   are available (this gives external input device support).
94
95 SDL_OMAP_NO_PANDORA_TV:
96   This disables automatic framebuffer redirection to TV on pandora.
97
98
99 Config file
100 -----------
101
102 Optionally a file named "omapsdl.cfg" can be created in the game's working
103 directory. It has lower priority than environment variables, and has these
104 options (only when omapdss driver is active):
105
106 # same as SDL_OMAP_VSYNC
107 force_vsync = 1/0
108
109 # same as SDL_OMAP_FORCE_DOUBLEBUF
110 force_doublebuf = 1/0
111
112 # same as SDL_OMAP_FORCE_DIRECTBUF
113 force_directbuf = 1/0
114
115 # same as SDL_OMAP_NO_TS_TRANSLATE
116 no_ts_translate = 1/0
117
118 # same as SDL_OMAP_TS_FORCE_TSLIB
119 ts_force_tslib = 1/0
120
121 # can be used to bind a key to SDL keysym, good for quick ports.
122 # Example:
123 # bind ev_home = sdlk_space
124 bind ev_<evdev_key> = <sdl_key>
125
126
127 Source
128 ------
129
130 Available at git://notaz.gp2x.de/~notaz/sdl_omap.git
131