SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
NAME
screen - interface to Amiga screens
SYNOPSIS
#include <sys/types.h>
#include <sys/screen.h>
int sd; /* Screen descriptor */
sd = open("/dev/screen", O_RDWR);
DESCRIPTION
/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 cru-
cial characteristics, such as vertical and horizontal reso-
lution, 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 login 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.
/dev/screen is a "clone" device. Each time it is opened, a
descriptor to a newly created object is returned, which can-
not 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 extracting the minor device number from
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 pro-
grams.
Amiga Unix Last change: 1
SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
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 con-
tain different information about the input event.
type=0
Keymap encoded input. Class should be zero, and
code contains an ASCII character.
type=1
"Raw" unencoded key input. This type is only
returned if SIM_RAWKEY inputmode is selected.
Class should be zero, and code contains an unen-
coded 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=2
Mouse action. If class is 0xFE, 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 0xFF, then the high-
order byte of code is a signed 8-bit value indi-
cating 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;
Amiga Unix Last change: 2
SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
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_LESSPLANES Fewer planes are OK
SF_LESSRES Less resolution is OK
SF_MORERES More resolution is OK
The bits of modes specify various video modes,
including:
SM_HAM Amiga Hold-And-Modify
SM_HALFBRITE Amiga HalfBrite
SM_INTERLACE Interlace
SM_NONLACE Not Interlace
SM_HEDLEY A2024 Hires mode
SM_NONHEDLEY Not A2024 Hires mode
SM_HIRES 640 x ?
SM_LORES 320 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 a different display size
than requested.
SIOCALLOCBMAP
Allocates a bitmap according to the struct bmap
pointed to by arg.
struct bmap {
unsigned short flags;
Amiga Unix Last change: 3
SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
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) sys-
tem call to map the bitmap memory into your pro-
cess. (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
SELBMAPVBWAIT 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 color as follows:
struct color {
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
beleives 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 pro-
gram 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 color pointed to by arg. There must be
an appropriate number of these structs for the
number of bitplanes and the display modes.
Amiga Unix Last change: 4
SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
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 inter-
nal 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 pre-
viously on the display. SIOCFRONT should be done
in conjunction with SIOCACTIVATE.
SIOCBACK
Causes the corresponding screen to cease being
displayed (some other screen will be displayed
instead). It can be brought back to the front
with SIOCFRONT or through the user's manual selec-
tion using the keyboard or mouse (currently only
the keyboard selection method is supported).
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 conjunc-
tion 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 descrip-
tion 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
Amiga Unix Last change: 5
SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
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 correspond-
ing 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
Amiga Unix Last change: 6
SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
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 vari-
able 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,
Amiga Unix Last change: 7
SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
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/screen.h>. An example usage:
#include <sys/types.h>
#include <sys/mman.h>
#include <sys/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 correspond-
ing 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.
ECS 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), font(5A), kmap(5A), amiga(7A), console(7A),
sioc(1A), displaytype(1A).
Amiga Unix Last change: 8
SCREEN(7A) MISC. REFERENCE MANUAL PAGES SCREEN(7A)
The Amiga Hardware Reference Manual.
Amiga Unix Last change: 9