Add "scaled" and "pixelperfect" layer sizes.

[sdl_omap.git] / README.OMAP

OMAP specific SDL driver
by Gražvydas "notaz" Ignotas


About
-----

This is a quick SDL driver to make use of some OMAP features, namely double
buffering and hardware scaler.

Features:

 * hardware scaling support (up and down)
 * doublebuffering support (can eliminate tearing)
 * vsync support (can give smooth scrolling if done right)
 * keymap change with a config file
 * 16/24/32bpp display support
 * touchscreen input translation to scaler source image coordinates
 * screen surface cropping / border removal support

Caveats:
 * disabled by default (falls back to x11/fbcon SDL drivers) unless
   SDL_VIDEODRIVER environment variable is set
 * no windowed mode support, fullscreen only
 * requires functional DSS2 driver with /dev/fb1 mapped to overlay1 or
   overlay2 and enough free VRAM available for requested display mode.

Although this was created for pandora, there is nothing preventing this to work
on other OMAP platforms as well (well, nothing intentional at least).


Usage / environment
-------------------

To enable this driver, SDL_VIDEODRIVER environment variable must be set to
"omapdss". It can be set by calling setenv() in the code, but it's better to
just set it in launcher script so that it can be changed easily without
recompiling as needed:
---
#!/bin/sh
export SDL_VIDEODRIVER=omapdss
./your_program_here
---

Other environment variables:

SDL_OMAP_LAYER_SIZE:
  Output layer size. Regardless what you set with SDL_SetVideoMode(), output
  will be scaled to this size using hardware with zero processing cost.
  Note: scaling amount range is limited to roughly 1/4x-8x. The exact range
  depends on various factors like version of the driver or OMAP hardware itself.
  Valid values:
    "WxH", for example "640x480"
    "fullscreen" to cover whole screen.
    "scaled" to upscale the screen proportionally, letterboxing or pillarboxing.
    "pixelperfect" to upscale by a whole-number factor (e.g. 2x or 3x size).

SDL_OMAP_BORDER_CUT:
  This can be used to move parts of SDL surface out of screen, in other
  words cut borders and zoom in. Format: <left>,<right>,<top>,<bottom>
  For example, "0,0,16,0" would hide top 16 lines offscreen, making 17th
  (16th if you count from 0) line the first visible.
  Note: like for layer size ranges are limited.

SDL_OMAP_VSYNC:
  Enables waiting for vertical sync on SDL_Flip() calls.
  Set to "1" to enable, "0" to disable.

SDL_OMAP_DEFAULT_MODE:
  If the app doesn't specify resolution in SDL_SetVideoMode(), then use this.
  Should be specified in "WxH" format, for example "640x480".

SDL_OMAP_FORCE_DOUBLEBUF:
  This can force double buffering to on, which can help to eliminate tearing.
  Note that if app isn't updating whole buffer each frame, it will glitch.
  This is the same as specifying SDL_DOUBLEBUF to SDL_SetVideoMode.

SDL_OMAP_NO_TS_TRANSLATE:
  Disable automatic touchscreen screen -> layer coordinate translation,
  return real screen coordinates.

SDL_OMAP_TS_FORCE_TSLIB:
  Always use tslib to read touchscreen. Without this, use X events when they
  are available (this gives external input device support).


Config file
-----------

Optionally a file named "omapsdl.cfg" can be created in the game's working
directory. It has lower priority than environment variables, and has these
options (only when omapdss driver is active):

# same as SDL_OMAP_VSYNC
force_vsync = 1/0

# same as SDL_OMAP_FORCE_DOUBLEBUF
force_doublebuf = 1/0

# same as SDL_OMAP_NO_TS_TRANSLATE
no_ts_translate = 1/0

# same as SDL_OMAP_TS_FORCE_TSLIB
ts_force_tslib = 1/0

# can be used to bind a key to SDL keysym, good for quick ports.
# Example:
# bind ev_home = sdlk_space
bind ev_<evdev_key> = <sdl_key>


Source
------

Available at git://notaz.gp2x.de/~notaz/sdl_omap.git