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