diff options
Diffstat (limited to 'payloads/libpayload/curses/PDCurses/doc/sdl.txt')
| -rw-r--r-- | payloads/libpayload/curses/PDCurses/doc/sdl.txt | 164 |
1 files changed, 82 insertions, 82 deletions
diff --git a/payloads/libpayload/curses/PDCurses/doc/sdl.txt b/payloads/libpayload/curses/PDCurses/doc/sdl.txt index 6a54b9b426..10710ce9a3 100644 --- a/payloads/libpayload/curses/PDCurses/doc/sdl.txt +++ b/payloads/libpayload/curses/PDCurses/doc/sdl.txt @@ -1,93 +1,93 @@ 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. +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 +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 +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 +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 +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 +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 +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. +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 +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 +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 +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 +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; @@ -96,57 +96,57 @@ include pdcsdl.h, or just add the declarations you need in your code: 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 +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. +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, +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_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 +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() +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 +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. |