SCREEN(3A) — MISC REFERENCE MANUAL PAGES

NAME

screen: OpenScreen, ScreenColors, NewBitmap, DisplayScreen, ScreenDeviceName, CloseScreen, ScreenError − functions for Amiga screen access

SYNOPSIS

cc flags files ... -lscreen
#include <sys/types.h>
int sd=OpenScreen(const char ∗title, const struct scrtype ∗stp, int flags);
intScreenColors(int sd, const struct scolor colors[]);
intNewBitmap(int sd, struct Bitmap ∗bp);
intDisplayScreen(int sd);
char ∗ScreenDeviceName(int sd);
intCloseScreen(int sd);
char ∗ScreenError(void);

DESCRIPTION

The /dev/screen device driver (see screen(7A)) provides access to the Amiga graphics screen capability. However, direct use of this driver in a way which is compatible with the "Screen Menu" and the "screen groups" concept requires a complex and tedious sequence of operations and error checking. It is also desirable for programs to adapt to future changes in the interface. Therefore, some "canned" functions are provided which perform the most common screen setup operations in a simplified way, hiding some of the tedium of creating a screen.

int sd=OpenScreen(const char ∗title, const struct scrtype ∗stp, int flags);
Subsumes the open, SIOCSETNAME, SIOCSETTYPE, and SIOCSETGROUP operations. title is the name, or title, to appear in the ALT-Esc screen menu. If stp is non-null, an SIOCSETTYPE is attempted with stp as the parameter. stp may be set to DEFAULT_SCRTYPE to have a default provided. flags must be zero. The sd return value is the file descriptor returned by open(), and must be used in subsequent calls to functions in this library.

intScreenColors(int sd, const struct scolor colors[]);
Sets the color map for sd to colors. Subsumes the SIOCSETCMAP ioctl operation.

intNewBitmap(int sd, struct Bitmap ∗bp);
Allocates, selects, and mmaps a new bitmap appropriate for sd. Subsumes the SIOCALLOCBMAP, SIOCSELBMAP, and mmap operations. bp must point to a Bitmap structure (defined in <amiga/screen.h>)

struct Bitmap {
    unsigned short flags;
    unsigned short width, height, depth, offset;
    unsigned char ∗bpl[MAXBPL];
};

which contains all zeroes. Upon return, ∗bp contains width, height, and depth fields that describe the bitmap, and bpl[0..depth] fields that point to the bitplane memory.

intDisplayScreen(int sd);
"Selects" the screen corresponding to sd. Subsumes the SIOCGROUPFRONT or SIOCFRONT and SIOCACTIVATE ioctl operations.

char ∗ScreenDeviceName(int sd);
Returns an openable pathname for sd.

intCloseScreen(int sd);
Closes sd and its corresponding screen.

char ∗ScreenError(void);
Returns a printable description of the cause of the last error return from a function in this library.

RETURN VALUES

OpenScreen and NewBitmap return -1 in case of error. ScreenColors, DisplayScreen, and CloseScreen return 0 for success or nonzero in case of error. ScreenDeviceName returns a null pointer in case of error.

FILES

/dev/screen - special file for creating screens
/dev/scr/∗ - names for already-open screens.

Museum