libpayload: Rename PDCurses-3.4 to PDCurses
Change-Id: If881ec130833c7e7e62caa3d31e350a531f5bc8e Signed-off-by: Stefan Reinauer <stefan.reinauer@coreboot.org> Reviewed-on: http://review.coreboot.org/12398 Tested-by: build bot (Jenkins) Reviewed-by: Patrick Georgi <pgeorgi@google.com>
This commit is contained in:
152
payloads/libpayload/curses/PDCurses/doc/sdl.txt
Normal file
152
payloads/libpayload/curses/PDCurses/doc/sdl.txt
Normal file
@@ -0,0 +1,152 @@
|
||||
SDL Considerations
|
||||
==================
|
||||
|
||||
There are no special requirements to use PDCurses for SDL -- all
|
||||
PDCurses-compatible code should work fine. (In fact, you can even build
|
||||
against the Win32 console pdcurses.dll, and then swap in the SDL
|
||||
pdcurses.dll.) Nothing extra is needed beyond the base SDL library.
|
||||
However, there are some optional special features, described here.
|
||||
|
||||
The principal limitation of this port is that input is currently
|
||||
restricted to ASCII (i.e., 0-127), plus the special keys like KEY_LEFT.
|
||||
(You could have Unicode input, but then the input wouldn't match the
|
||||
output, which is in Code Page 437.) Also, see the note about the
|
||||
potential for incomplete output under "PDC_update_rects()", below.
|
||||
|
||||
|
||||
Fonts
|
||||
-----
|
||||
|
||||
The font is a simple BMP, 32 characters wide by 8 characters tall,
|
||||
preferably with a palette. (BMPs without palettes still work, but in
|
||||
that case, no attributes will be available, nor will the cursor work.)
|
||||
The first entry in the palette (usually black) is treated as the
|
||||
background color; the last entry (usually white) is treated as the
|
||||
foreground. These are changed or made transparent as appropriate; any
|
||||
other colors in the palette are passed through unchanged. So -- although
|
||||
a one-bit depth is sufficient for a normal font -- you could redraw some
|
||||
characters as multi-colored tiles.
|
||||
|
||||
The font must be monospaced. The size of each character is derived by
|
||||
dividing the width of the BMP by 32 and the height by 8. There is no
|
||||
constraint on the dimensions.
|
||||
|
||||
As provided in the default font and expected by acs_map[], the font is
|
||||
in Code Page 437 form. But you can of course use any layout if you're
|
||||
not relying on correct values for the ACS_* macros.
|
||||
|
||||
The font can be set via the environment variable PDC_FONT. If it's not
|
||||
set, PDCurses looks for a file named "pdcfont.bmp" in the current
|
||||
directory at the time of initscr(). If neither is found, it uses the
|
||||
built-in default font encoded in deffont.h.
|
||||
|
||||
|
||||
Backgrounds
|
||||
-----------
|
||||
|
||||
PDCurses for SDL supports an optional background image BMP. This is used
|
||||
whenever start_color() has not been called (see the ptest demo for an
|
||||
example), or when use_default_colors() has been called after
|
||||
start_color(), and the background color of a pair has been set to -1
|
||||
(see newdemo, worm, and rain for examples). The usage parallels that of
|
||||
ncurses in an appropriate terminal (e.g., Gnome Terminal). The image is
|
||||
tiled to cover the PDCurses window, and can be any size or depth.
|
||||
|
||||
As with the font, you can point to a location for the background via the
|
||||
environment variable PDC_BACKGROUND; "pdcback.bmp" is the fallback.
|
||||
(There is no default background.)
|
||||
|
||||
|
||||
Icons
|
||||
-----
|
||||
|
||||
The icon (used with SDL_WM_SetIcon() -- not used for the executable
|
||||
file) can be set via the environment variable PDC_ICON, and falls back
|
||||
to "pdcicon.bmp", and then to the built-in icon from deficon.h. The
|
||||
built-in icon is the PDCurses logo, as seen in ../x11/little_icon.xbm.
|
||||
The SDL docs say that the icon must be 32x32, at least for use with MS
|
||||
Windows.
|
||||
|
||||
If pdc_screen is preinitialized (see below), PDCurses does not attempt
|
||||
to set the icon.
|
||||
|
||||
|
||||
Screen size
|
||||
-----------
|
||||
|
||||
The default screen size is 80x25 characters (whatever size they may be),
|
||||
but you can override this via the environment variables PDC_COLS and/or
|
||||
PDC_LINES. (Some other ports use COLS and LINES; this is not done here
|
||||
because those values are, or should be, those of the controlling
|
||||
terminal, and PDCurses for SDL is independent of the terminal.) If
|
||||
pdc_screen is preinitialized (see below), these are ignored.
|
||||
|
||||
|
||||
Integration with SDL
|
||||
--------------------
|
||||
|
||||
If you want to go further, you can mix PDCurses and SDL functions. (Of
|
||||
course this is extremely non-portable!) To aid you, there are several
|
||||
external variables and functions specific to the SDL port; you could
|
||||
include pdcsdl.h, or just add the declarations you need in your code:
|
||||
|
||||
PDCEX SDL_Surface *pdc_screen, *pdc_font, *pdc_icon, *pdc_back;
|
||||
PDCEX int pdc_sheight, pdc_swidth, pdc_yoffset, pdc_xoffset;
|
||||
|
||||
void PDC_update_rects(void);
|
||||
void PDC_retile(void);
|
||||
|
||||
pdc_screen is the main surface, created by SDL_SetVideoMode(), unless
|
||||
it's preset before initscr(). You can perform normal SDL operations on
|
||||
this surface, but PDCurses won't respect them when it updates. (For
|
||||
that, see PDC_retile().) As an alternative, you can preinitialize this
|
||||
surface before calling initscr(). In that case, you can use pdc_sheight,
|
||||
pdc_swidth, pdc_yoffset and/or pdc_xoffset (q.v.) to confine PDCurses to
|
||||
only a specific area of the surface, reserving the rest for other SDL
|
||||
operations. If you preinitialize pdc_screen, you'll have to close it
|
||||
yourself; PDCurses will ignore resize events, and won't try to set the
|
||||
icon. Also note that if you preinitialize pdc_screen, it need not be the
|
||||
display surface.
|
||||
|
||||
pdc_font, pdc_icon, and pdc_back are the SDL_surfaces for the font,
|
||||
icon, and background, respectively. You can set any or all of them
|
||||
before initscr(), and thus override any of the other ways to set them.
|
||||
But note that pdc_icon will be ignored if pdc_screen is preset.
|
||||
|
||||
pdc_sheight and pdc_swidth are the dimensions of the area of pdc_screen
|
||||
to be used by PDCurses. You can preset them before initscr(); if either
|
||||
is not set, it defaults to the full screen size minus the x or y offset,
|
||||
as appropriate.
|
||||
|
||||
pdc_xoffset and pdc_yoffset are the x and y offset for the area of
|
||||
pdc_screen to be used by PDCurses. See the sdltest demo for an example.
|
||||
|
||||
PDC_retile() makes a copy of pdc_screen, then tiles it with the
|
||||
background image, if any. The resulting surface is used as the
|
||||
background for transparent character cells. PDC_retile() is called from
|
||||
initscr() and resize_term(). However, you can also use it at other
|
||||
times, to take advantage of the way it copies pdc_screen: Draw some SDL
|
||||
stuff; call PDC_retile(); do some curses stuff -- it will use whatever
|
||||
was on pdc_screen as the background. Then you can erase the curses
|
||||
screen, do some more SDL stuff, and call PDC_retile() again to make a
|
||||
new background. (If you don't erase the curses screen, it will be
|
||||
incorporated into the background when you call PDC_retile().) But this
|
||||
only works if no background image is set.
|
||||
|
||||
PDC_update_rects() is how the screen actually gets updated. For
|
||||
performance reasons, when drawing, PDCurses for SDL maintains a table of
|
||||
rectangles that need updating, and only updates (by calling this
|
||||
function) during getch(), napms(), or when the table gets full.
|
||||
Normally, this is sufficient; but if you're pausing in some way other
|
||||
than by using napms(), and you're not doing keyboard checks, you may get
|
||||
an incomplete update. If that happens, you can call PDC_update_rects()
|
||||
manually.
|
||||
|
||||
|
||||
Interaction with stdio
|
||||
----------------------
|
||||
|
||||
As with X11, it's a bad idea to mix curses and stdio calls. (In fact,
|
||||
that's true for PDCurses on any platform; but especially these two,
|
||||
which don't run under terminals.) Depending on how SDL is built, stdout
|
||||
and stderr may be redirected to files.
|
Reference in New Issue
Block a user