NAME

screen − interface to Amiga Unix screens devices

SYNOPSIS

#include <sys/types.h>
#include <sys/amiga/screen.h>
int sd;/∗ Screen descriptor ∗/
sd = open(devicename, O_RDWR);

DESCRIPTION

devicename is the name of a special file providing access to the Amiga Unix screens facility.  Two device drivers exist which provide this access.  "/dev/console" and "/dev/term/con∗" are names for the console screen driver, described in console(7A).  "/dev/screen" and "/dev/scr/∗" are names for the graphics screen driver, described by this manual entry.  Much of the description here applies to the console driver as well.  "/dev/screen" is a special file which, when opened, gives the calling process a "screen descriptor" corresponding to a unique, newly created, "screen".  This screen is not displayed immediately as it does not yet have certain crucial characteristics, such as vertical and horizontal resolution, number of bitplanes, or video modes. 

The screen is the basic method of generating an Amiga display.  It is a "virtual" screen, meaning that programs can access it as if it were the physical display screen, but in reality it might not be displayed at the moment, and there might be many other virtual screens.  Multiple screens can be created by separate programs, or by the same program.  The "console" screen and the X window system screen can exist at the same time, along with whatever other screens are created by programs. 

A user can chose which screen is displayed based on "screen groups".  A group of screens is chosen using the mouse or keyboard, and the "top" screen in that group is displayed and made active.  If a normal text console screen is displayed, and a graphics program is run from that screen, the graphics program’s newly created screen becomes the top screen in that group.  The old login screen is hidden until the graphics program exits. 

Currently, a "screen group" is selected by holding the ALT key and pressing one of the function keys. 

This manual entry describes the low-level access to the /dev/screen driver.  A set of functions for convenient and upward-compatible access to this driver exists in a shared library.  See screen(3A) for information on these functions, and /usr/amiga/src/cmd/samp.c for an example program.  The library functions should be used for the functions they perform, with these low level methods used for the remaining operations. 

/dev/screen is a "clone" device.  Each time it is opened, a descriptor to a newly created object is returned, which cannot be accessed by the name "/dev/screen" anymore.  The name for a screen after it has been created is of the form "/dev/scr/N" where N is a decimal screen number.  The number can be obtained by applying the SCREENMINOR macro to the st_rdev field from fstat(2). 

After opening /dev/screen, the screen descriptor can be manipulated to cause the screen to be displayed, to read keyboard and mouse input, or to draw graphics or text on the screen.  When the screen descriptor is closed using the close(2) or _exit(2) system calls, the screen will cease to exist and its memory will be released for use by other programs. 

Screens use the Amiga’s "chip" memory, the special 16-bit wide memory that is accessible by the graphics custom chips.  This memory is not virtual, so the number of screens that can exist at one time is limited by the amount of chip memory in the system.  This is usually 512k to 2M bytes. 

INPUT

Normally, a read(2) system call issued on the screen descriptor will return an integral multiple of eight bytes.  These groups of eight bytes are structures of the form:

struct inputevent {
    unsigned char type;
    unsigned char class;
    unsigned short code;
    unsigned long qualifiers;
};

Depending on the value of type, the remaining members contain different information about the input event.

type=IETYPE_ASCII
Keymap encoded input.  Class should be zero, and code contains an ASCII character. 

type=IETYPE_RAWKEY
"Raw" unencoded key input.  This type is only returned if SIM_RAWKEY inputmode is selected. Class should be zero, and code contains an unencoded key transition code as described in The Amiga Hardware Reference Manual.  Unencoded mouse buttons are returned as raw key codes 0x7C through 0x7E, left to right. 

type=IETYPE_MOUSE
Mouse action.  If class is IECLASS_MOUSEBUTTON, then the high-order byte of code is a mouse button number (0=left, 1=middle, 2=right) and the low-order byte is the resulting state of that button (1=pressed, 0=released).  If class is IECLASS_MOUSEMOTION, then the high-order byte of code is a signed 8-bit value indicating rightward motion, and the low-order byte is a signed 8-bit value indicating downward motion. 

The poll(2) system call can be used to wait for other input streams in addition to a /dev/screen device. 

IOCTL COMMANDS

Screens support ioctl(2) system calls of the form:

ioctl(fd, command, arg)
int arg;

Many of these commands are supported by all the Amiga Unix screen devices (such as the console(7A) driver) as well as the /dev/screen device.  Others are only supported by some devices. 

The value of command determines the action taken:

SIOCSETTYPE
Sets the type of screen display.  This function must be used before allocating the bitmap or using any functions which attempt to display the screen.  The argument is a pointer to a struct scrtype as follows:

struct scrtype {
    unsigned short flags;
    unsigned short type;
    unsigned short dispx, dispy;
    unsigned short dispz;
    unsigned long modes;
};

The flags can include the following bits:

SF_LESSPLANESFewer planes are OK
SF_LESSRESLess resolution is OK
SF_MORERESMore resolution is OK

The bits of modes specify various video modes, including:

SM_HAMAmiga Hold-And-Modify
SM_HALFBRITEAmiga HalfBrite
SM_INTERLACEInterlace
SM_NONLACENot Interlace
SM_HEDLEYA2024 Hires mode
SM_NONHEDLEYNot A2024 Hires mode
SM_HIRES640 x ?
SM_LORES320 x ?

SIOCGETTYPE
Fills in the struct scrtype pointed to by arg.  This should be used after SIOCSETTYPE to see if the system had to use display parameters different from the ones requested. 

SIOCALLOCBMAP
Allocates a bitmap according to the struct bmap pointed to by arg. 

struct bmap {
    unsigned short flags;
    unsigned short bmapx, bmapy;
    unsigned short bmapz;
};

This should only be used after SIOCSETTYPE, since the system might need to allocate a special type of memory depending on how it is to be displayed. bmapx, bmapy, and bmapz, should be equal to the dispx, dispy, and dispz values returned by SIOCGETTYPE.  The return value is a bitmap id, only valid with this screen, which can be used to identify the bitmap to the SIOCSELBMAP function, or to derive an offset to pass to the mmap(2) system call to map the bitmap memory into your process.  (See USE OF MMAP below.) 

SIOCSELBMAP
Causes the screen to display the bitmap whose id number is arg.  If the screen was already being displayed, the new bitmap will be displayed at the next video field (retrace).  Otherwise there is no effect until the screen is displayed.  If the SELBMAP_VBWAIT bit is set in arg, the call will not return until the next vertical retrace. 

SIOCSETCMAP
Sets the color map for the screen. arg points to an array of struct scolor as defined in <sys/amiga/screen.h>:

struct scolor {
    unsigned char gray;
    unsigned char red, green, blue;
};

The system will use either the gray value or the rgb values, depending on what kind of monitor it believes is in use.  All four fields should be given appropriate values.  The gray value can be just an average of the red, green, and blue, or it can be a completely unrelated value if your program wants completely different color settings to be used when a gray scale monitor is used. There must be an appropriate number of these structs for the number of bitplanes and the display modes.

SIOCGETCMAP
Copies the color map for the screen to the array of struct scolor pointed to by arg. There must be an appropriate number of these structs for the number of bitplanes and the display modes.

SIOC Returns success if fd corresponds to an Amiga screen of any sort.  This includes screens opened through /dev/screen as well as any other types, such as console screens (see console(7A)). 

SIOCDISPLAYTYPE
Returns (as the return value of ioctl) the internal displaytype variable in the kernel.  This number indicates what display hardware is attached to the Amiga.  This includes bits indicating whether the video output is PAL or NTSC, and whether the new Enhanced ChipSet is installed. 

SIOCFRONT
Causes the screen corresponding to fd to be displayed, if possible.  It must already have had its type set with SIOCSETTYPE and have a current bitmap (set with SIOCSELBMAP).  If the screen is not already a member of a screen group, it becomes a member of the group of the screen that was previously on the display.  SIOCFRONT should be done in conjunction with SIOCACTIVATE. 

SIOCBACK
Causes the corresponding screen to cease being displayed or active (some other screen will be displayed instead).  It can be brought back to the front with SIOCFRONT or through the user’s manual selection.

SIOCACTIVATE
Causes the corresponding screen to become active, that is, the keyboard and mouse will be "attached" to that screen.  This should be done in conjunction with SIOCFRONT.

SIOCSETKMAP
Sets the keymap for the given screen. arg must either be zero, indicating that the system default keymap should be used, or a pointer to a valid keymap description in memory.  The keymap description should be a memory image of a keymap file.  Only the screen corresponding to fd will be affected. 

SIOCGETKMAP
Copies the keymap currently in use by the corresponding screen to the buffer pointed to by arg.  The buffer must already contain a ’struct keymap’ header with the km_length field specifying the available size of the buffer.  No more than that many bytes will be filled in by this call.  On return, the km_length field is filled in with the actual length of the keymap. 

SIOCSETDEFKMAP
Sets the system-wide default keymap. arg must either be zero, indicating that the kernel’s default powerup keymap should be used, or a pointer to a valid keymap description in memory.  The keymap description should be a memory image of a keymap file.  Any screens which have their current keymap set to zero will immediately begin using this new system default keymap. 

SIOCSETFONT
Sets the font for the given screen. arg must either be zero, indicating that the system default font should be used, or a pointer to a valid font description in memory.  The font description should be a memory image of a font file.  Only the screen corresponding to fd will be affected.  The selected font is currently only used by the console(7A) device, not the /dev/screen device. 

SIOCGETFONT
Copies the font currently in use by the corresponding screen to the buffer pointed to by arg.  The buffer must already contain a ’struct font’ header with the f_length field specifying the available size of the buffer.  No more than that many bytes will be filled in by this call.  On return, the f_length field is filled in with the actual length of the font. 

SIOCSETDEFFONT
Sets the system-wide default font. arg must either be zero, indicating that the kernel’s default powerup font should be used, or a pointer to a valid font description in memory.  The font description should be a memory image of a font file.  Any screens which have their current font set to zero will continue to use the font they were using until is is explicitly set to zero once again. 

SIOCWINSIZE
The struct swinsize pointed to by arg will be filled in with the current size of the corresponding screen.  The size is given both in pixels and in characters of the screen’s current font.  The numeric value of the SIOCWINSIZE command code and the layout of the struct swinsize correspond to those used by the JWINSIZE ioctl, so that programs using JWINSIZE will automatically recognize the size of an Amiga screen. 

SIOCSETINPUTMODE
The screen’s input mode is set to arg, which is a mask of bit values.  The default initial input mode is zero. The only defined bit value is SIM_RAWKEY, which if set, causes the input stream to contain "raw" input events.  Mouse motions will still cause type 2 events, but keyboard and mouse buttons will cause type 1 events.

SIOCSETDISPLAYTYPE
Sets the value of the internal displaytype variable to arg. Most of the bits of displaytype can not be changed, and an attempt to change them will result in an EINVAL error.

SIOCGETGROUP
Returns the number of the group of which the screen is a member, or -1 if the screen is not a member of a group.

SIOCSETGROUP
Causes the screen to become a member of group arg. It will be the "top" screen in that group, and will be displayed when the user selects that group for display.

SIOCSETDISPLAYADJUST
arg points to an instance of struct displayadjust. The values in this structure are read and retained, and affect the creation and display of screens.  The fields are:

short xoffset
horizontal adjustment of display position

short yoffset
vertical adjustment of display position

unsigned short xoverscan
number of LORES pixels of horizontal overscan displayable on the monitor

unsigned short yoverscan
number of non-interlace pixels of vertical overscan displayable on the monitor

SIOCGETDISPLAYADJUST
arg points to an instance of struct displayadjust, which is filled in with the currently remembered displayadjust settings.

USE OF MMAP(2)

The mmap(2) system call is used to map a bitmap’s memory into a process’s address space, where it can be accessed as normal memory.  One mmap call must be made for each bitplane to be accessed.  The offset argument to mmap is calculated from the bitmapid and the bitplane number, using the BPADDR macro provided in <sys/amiga/screen.h>. An example usage:

 #include <sys/types.h>
#include <sys/mman.h>
#include <sys/amiga/screen.h>
 unsigned char ∗bpaddr[MAXPLANES];
for ( bitplane=0 ; bitplane<bmap.bmapz ; ++bitplane )
    bpaddr[bitplane] =
        (unsigned char ∗)mmap((caddr_t)0,
                              (bmap.bmapx ∗ bmap.bmapy)/8,
                              PROT_READ|PROT_WRITE, MAP_SHARED,
                              sd, BPADDR(bitmapid, bitplane, 0));
 /∗ each element of bpaddr[] now contains
 ∗ the address of the corresponding bitplane ∗/

The return from mmap() is the address where the corresponding bitplane memory can be found.  The layout is as the Amiga hardware provides it: the memory could be considered to have the following C declaration:

unsigned short bpaddr[bmapy][(bmapx+15)/16];

which is to say that bpaddr is an array of bmapy lines of bmapx pixels each.  The number of pixels per line is rounded up to an integral number of 16-bit words if necessary.  See mmap(2) for more details on the use of mmap.

BUGS

The keymap file format is not documented or finalized.  Don’t look at it.  Amiga Enhanced ChipSet modes are not supported yet.

FILES

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

SEE ALSO

open(2), close(2), ioctl(2), read(2), write(2), mmap(2), poll(2), screen(3A),
 font(5A), kmap(5A), amiga(7A), console(7A), sioc(1A), displaytype(1A). /usr/amiga/src/cmd/samp.c (sample program) The Amiga Hardware Reference Manual.

Amiga Unix  —  Last change: