payloads/libpayload/curses/PDCurses/doc/sdl.txt

   1 SDL Considerations
   2 ==================
   3
   4 There are no special requirements to use PDCurses for SDL -- all
   5 PDCurses-compatible code should work fine. (In fact, you can even build
   6 against the Win32 console pdcurses.dll, and then swap in the SDL
   7 pdcurses.dll.) Nothing extra is needed beyond the base SDL library.
   8 However, there are some optional special features, described here.
   9
  10 The principal limitation of this port is that input is currently
  11 restricted to ASCII (i.e., 0-127), plus the special keys like KEY_LEFT.
  12 (You could have Unicode input, but then the input wouldn't match the
  13 output, which is in Code Page 437.) Also, see the note about the
  14 potential for incomplete output under "PDC_update_rects()", below.
  15
  16
  17 Fonts
  18 -----
  19
  20 The font is a simple BMP, 32 characters wide by 8 characters tall,
  21 preferably with a palette. (BMPs without palettes still work, but in
  22 that case, no attributes will be available, nor will the cursor work.)
  23 The first entry in the palette (usually black) is treated as the
  24 background color; the last entry (usually white) is treated as the
  25 foreground. These are changed or made transparent as appropriate; any
  26 other colors in the palette are passed through unchanged. So -- although
  27 a one-bit depth is sufficient for a normal font -- you could redraw some
  28 characters as multi-colored tiles.
  29
  30 The font must be monospaced. The size of each character is derived by
  31 dividing the width of the BMP by 32 and the height by 8. There is no
  32 constraint on the dimensions.
  33
  34 As provided in the default font and expected by acs_map[], the font is
  35 in Code Page 437 form. But you can of course use any layout if you're
  36 not relying on correct values for the ACS_* macros.
  37
  38 The font can be set via the environment variable PDC_FONT. If it's not
  39 set, PDCurses looks for a file named "pdcfont.bmp" in the current
  40 directory at the time of initscr(). If neither is found, it uses the
  41 built-in default font encoded in deffont.h.
  42
  43
  44 Backgrounds
  45 -----------
  46
  47 PDCurses for SDL supports an optional background image BMP. This is used
  48 whenever start_color() has not been called (see the ptest demo for an
  49 example), or when use_default_colors() has been called after
  50 start_color(), and the background color of a pair has been set to -1
  51 (see newdemo, worm, and rain for examples). The usage parallels that of
  52 ncurses in an appropriate terminal (e.g., Gnome Terminal). The image is
  53 tiled to cover the PDCurses window, and can be any size or depth.
  54
  55 As with the font, you can point to a location for the background via the
  56 environment variable PDC_BACKGROUND; "pdcback.bmp" is the fallback.
  57 (There is no default background.)
  58
  59
  60 Icons
  61 -----
  62
  63 The icon (used with SDL_WM_SetIcon() -- not used for the executable
  64 file) can be set via the environment variable PDC_ICON, and falls back
  65 to "pdcicon.bmp", and then to the built-in icon from deficon.h. The
  66 built-in icon is the PDCurses logo, as seen in ../x11/little_icon.xbm.
  67 The SDL docs say that the icon must be 32x32, at least for use with MS
  68 Windows.
  69
  70 If pdc_screen is preinitialized (see below), PDCurses does not attempt
  71 to set the icon.
  72
  73
  74 Screen size
  75 -----------
  76
  77 The default screen size is 80x25 characters (whatever size they may be),
  78 but you can override this via the environment variables PDC_COLS and/or
  79 PDC_LINES. (Some other ports use COLS and LINES; this is not done here
  80 because those values are, or should be, those of the controlling
  81 terminal, and PDCurses for SDL is independent of the terminal.) If
  82 pdc_screen is preinitialized (see below), these are ignored.
  83
  84
  85 Integration with SDL
  86 --------------------
  87
  88 If you want to go further, you can mix PDCurses and SDL functions. (Of
  89 course this is extremely non-portable!) To aid you, there are several
  90 external variables and functions specific to the SDL port; you could
  91 include pdcsdl.h, or just add the declarations you need in your code:
  92
  93  PDCEX SDL_Surface *pdc_screen, *pdc_font, *pdc_icon, *pdc_back;
  94  PDCEX int pdc_sheight, pdc_swidth, pdc_yoffset, pdc_xoffset;
  95
  96  void PDC_update_rects(void);
  97  void PDC_retile(void);
  98
  99 pdc_screen is the main surface, created by SDL_SetVideoMode(), unless
 100 it's preset before initscr(). You can perform normal SDL operations on
 101 this surface, but PDCurses won't respect them when it updates. (For
 102 that, see PDC_retile().) As an alternative, you can preinitialize this
 103 surface before calling initscr(). In that case, you can use pdc_sheight,
 104 pdc_swidth, pdc_yoffset and/or pdc_xoffset (q.v.) to confine PDCurses to
 105 only a specific area of the surface, reserving the rest for other SDL
 106 operations. If you preinitialize pdc_screen, you'll have to close it
 107 yourself; PDCurses will ignore resize events, and won't try to set the
 108 icon. Also note that if you preinitialize pdc_screen, it need not be the
 109 display surface.
 110
 111 pdc_font, pdc_icon, and pdc_back are the SDL_surfaces for the font,
 112 icon, and background, respectively. You can set any or all of them
 113 before initscr(), and thus override any of the other ways to set them.
 114 But note that pdc_icon will be ignored if pdc_screen is preset.
 115
 116 pdc_sheight and pdc_swidth are the dimensions of the area of pdc_screen
 117 to be used by PDCurses. You can preset them before initscr(); if either
 118 is not set, it defaults to the full screen size minus the x or y offset,
 119 as appropriate.
 120
 121 pdc_xoffset and pdc_yoffset are the x and y offset for the area of
 122 pdc_screen to be used by PDCurses. See the sdltest demo for an example.
 123
 124 PDC_retile() makes a copy of pdc_screen, then tiles it with the
 125 background image, if any. The resulting surface is used as the
 126 background for transparent character cells. PDC_retile() is called from
 127 initscr() and resize_term(). However, you can also use it at other
 128 times, to take advantage of the way it copies pdc_screen: Draw some SDL
 129 stuff; call PDC_retile(); do some curses stuff -- it will use whatever
 130 was on pdc_screen as the background. Then you can erase the curses
 131 screen, do some more SDL stuff, and call PDC_retile() again to make a
 132 new background. (If you don't erase the curses screen, it will be
 133 incorporated into the background when you call PDC_retile().) But this
 134 only works if no background image is set.
 135
 136 PDC_update_rects() is how the screen actually gets updated. For
 137 performance reasons, when drawing, PDCurses for SDL maintains a table of
 138 rectangles that need updating, and only updates (by calling this
 139 function) during getch(), napms(), or when the table gets full.
 140 Normally, this is sufficient; but if you're pausing in some way other
 141 than by using napms(), and you're not doing keyboard checks, you may get
 142 an incomplete update. If that happens, you can call PDC_update_rects()
 143 manually.
 144
 145
 146 Interaction with stdio
 147 ----------------------
 148
 149 As with X11, it's a bad idea to mix curses and stdio calls. (In fact,
 150 that's true for PDCurses on any platform; but especially these two,
 151 which don't run under terminals.) Depending on how SDL is built, stdout
 152 and stderr may be redirected to files.