ref: 2b99422480d596ebc26921c87c6bb81a07949f3e
dir: /ch12.ms/
.so tmacs
.BC 12 "User Input/Output
.BS 2 "Console input
.LP
.ix "user I/O
In chapter 7 we saw that
.CW #c
.ix "[#c] device driver
.ix "console device
is the root of the file tree exported by the
.I cons (3)
driver. It is conventionally bound at
.CW /dev ,
.ix [/dev]
and provides the familiar
.CW /dev/cons
.ix [/dev/cons]
file. Reading
.CW #c/cons
obtains input from the console keyboard. Writing to
.CW #c/cons
writes characters in the console screen.
.PP
.ix [rio]
.ix "window system
When \f(CWrio\fP, the window system, is running, it reads
.CW #c/cons
to obtain the characters you type. Writing them in the screen is a different story
that we will tell later. Reading and writing
.CW #c/cons
while running the window system is not a good idea. If more than one program is
reading this file, the characters typed will go to either program. In the following
experiment, we ask
.CW cat
to read
.CW #c/cons ,
storing what it could read into
.CW /tmp/out ,
so you could see what happens.
.P1
; cat '#c/cons' >/tmp/out
!!hlo \fRWe typed "hello"\fP
\fBDelete\fP !!\fRTo restore things to a normal behavior\fP
; cat /tmp/out
el;
.P2
.ix "simultaneous read
.LP
Despite typing
.CW "hello" ,
\f(CWrio\fP could only read
.CW "hlo" .
The other characters were read by
.CW cat .
.CW rio
expects to keep the real
.CW #c/cons
for itself, because it multiplexes this file nicely, providing a virtual version of it
on each window's
.CW /dev/cons .
.PP
A write to
.CW #c/cons
is also processed by the
.I cons
device, even when \f(CWrio\fP is running. As a result, it prints in the screen behind
\f(CWrio\fP's back. This command
.P1
; echo 'where will this go?' > '#c/cons'
.P2
.LP
.ix [#c/cons]
will produce an ugly message printed in the screen, which might look like
the one shown in figure [[!write console rio!]]. In a very few occasions, the kernel
itself may write a message for you in the console. The same would happen. Programs
started prior to running \f(CWrio\fP, that might also issue some diagnostics, would produce
the same effect. All of them are writing to the console output device.
.LS
.BP conswrite.ps
.LE F A write to the actual console may write to the screen even when rio is running.
.PP
.ix "console write
Writing some more things in the real console may cause a scroll, and the images
in the screen will scroll along with the text. Poor \f(CWrio\fP, it will never know that the
screen is messed up. To prevent this from happening, the file
.CW #c/kprint
.ix [/dev/kprint]
may be used. If a process has
.CW #c/kprint
open for reading, the kernel will not print in the screen whatever is written at
.CW #c/cons .
Instead, all that text is used to satisfy reads for
.CW #c/kprint .
For example, executing
.CW cat
on this file, prior to doing the
.CW echo
above, produces this effect:
.P1
; cat /dev/kprint
where will this go?
.P2
.LP
All text sent to the console will now go to that window.
For the record, it might help to print also
.CW /dev/kmesg ,
.ix [/dev/kmesg]
which records all the messages printed in the console so far, before reading
.CW kprint .
.P1
; cat /dev/kmesg /dev/kprint
Plan 9
E820: 00000000 0009f800 memory
E820: 0009f800 000a0000 reserved
.I "..."
where will this go?
.P2
.LP
When we implemented programs to read from the console, it gave us a line at a
time. We could even
.I edit
the line before hitting return. However, this time, using
.CW cat
to read
.CW #c/cons
returned characters, as we typed them. What is going on?
.ix "console read
.PP
Usually, the console device driver reads characters from the keyboard's hardware, and
\fBcooks\fP
.ix "cooked mode
what you type a little bit, before supplying such characters to any process reading
.CW /dev/cons .
This is the cooking recipe used by the console:
.IP •
A
.I backspace ,
.ix backspace
removes the previous character read from the keyboard.
.IP •
A
.I control-u
.ix "control-u
removes all the characters read from the keyboard, thus it cancels the current
input line.
.IP •
A
.I newline
.ix newline
terminates the cooking from the current line, which is made available to the
application reading from the console.
.IP •
The
.I compose
.ix compose
(usually
.I Alt )
key, followed by a few other keys, produces a character that is a function
of the other keys. This is used to type characters not usually found in the
keyboard, like α and Ж.
.IP •
Any other character stands for itself, and is queued to be cooked along with
the rest of the line.
.LP
The virtual version for
.CW /dev/cons
provided by the window system gives also a special meaning to a few other
characters, most notably:
.IP •
.I Delete
.ix [Delete]
posts an
.I interrupt
note to the process group associated to the window.
.IP •
.ix "arrow keys
Arrow keys ↑ and ↓ scroll backward and forward.
.IP •
Arrow keys → and ← move the text insertion point to the right and to the left.
.IP •
The
.ix [Escape]
.I Escape
key puts the window in a, so called,
.I hold
.ix "hold mode
mode. All the text typed while in hold mode is not supplied to any application
reading from
.CW /dev/cons .
Therefore, you can freely edit multiple lines of text. When
.I Escape
.ix "escape key
is preseed again, and the window leaves hold mode, the text is given to any
process reading from
.CW /dev/cons .
.LP
This is called the console's
.B "cooked mode" .
When it is enabled, lines can be edited as dictated by the rules stated above. This is
also called a
.I "line discipline" .
.ix "line discipline
But the console can be also put in a, so called,
.B "raw mode" .
In raw mode, the console does not cook the characters at all. It gives them to
the process reading from the console, as they arrive from the keyboard.
.PP
The file
.CW /dev/consctl
can be used to activate and de-activate the raw mode.
A write of the string
.CW rawon
.ix [rawon]
into such file puts the console in raw mode, until the file is closed or the string
.CW rawoff
.ix [rawoff]
is written.
The next program echoes what it can read from the console. But it
puts the console in raw mode when called with
.CW -r .
.so progs/raw.c.ms
.ix [raw.c]
.LP
This is what happens when we run it using the console's cooked mode and its
raw mode.
.P1
; 8.raw
!!hi
[hi
]
\fBDelete\fP
;
.P2
.P1
; 8.raw -r
[h]
[i]
[ \fI the program reads "\en"\fP
]
[␣] \fI the program reads "Del"\fP
[␣] \fI If we type "Esc", the program reads "Esc"\fP
.P2
.LP
There are some things to note. First, in cooked mode we can see the
characters we type as we type them. We could type
.CW hi ,
and its characters were echoed to the screen by the console. The program
.CW 8.raw
did not read anything as we typed them. Not yet. However, in raw mode,
the console does
.I not
.ix "character echo
.ix "console echo
echo back to the screen what we type. It assumes that the program reading
in raw mode does want to do it all by itself, and echo is suppressed.
.PP
Another effect of raw mode is that the program reads one character at a time,
as we type them. In cooked mode, only when we type a newline the program will
get its input.
.PP
A final and interesting difference is that we
.I cannot
.ix "program interrupt
interrupt the program pressing
.I Delete .
In fact, if
.CW /dev/cons
was
.CW #c/cons ,
it would know nothing about
.I Delete .
This key is an invention of the cooked mode in consoles provided for windows by
the window system. In raw mode, \f(CWrio\fP decides not to do anything special with this
key, and the application can read it as any other key.
.PP
Using the hold mode (provided by rio's consoles in cooked mode) this is what happens.
.P1
; 8.out
\fBEscape\fP
!!hi \fRhold mode is active...\fP
!!there \fRwe can edit this until...\fP
\fBEscape\fP
[hi
]
[there
]
.P2
.LP
The behavior is like in cooked mode (one line at a time), but we could type and
edit while in hold mode.
.PP
To answer our pending question. The program
.CW cat ,
that we used to experiment with reading
.CW #c/cons ,
got characters and not lines because rio keeps the system console in raw mode.
The file
.CW #c/cons
returns characters as we type them. These characters are processed by \f(CWrio\fP,
which uses them to supply a virtual console for the window were you are typing.
.ix "virtual console
Again, the virtual console for this window has both cooked and raw modes.
In shell windows, that operate in cooked mode,
the window cooks the characters before giving lines to programs
reading them. When acme is run in a window, it puts its (virtual) console device
in raw mode, to do the editing by itself.
.BS 2 "Characters and runes
.LP
.ix "rune
.ix "text representation
.ix "text symbol
.ix "ASCII
But that was not all about the console. The console, like most other devices
using text, and like all Plan 9 programs using text, does
.I not
use characters. This may be a surprise, but think about “characters”
like ☺, α, and Ж. For languages like English or Spanish, all text is made up
with characters, that might be letters, numbers, and other symbols. Spanish
has also accented letters like á and ñ. And this is just the start of the problem.
Other languages use symbols to represent concepts, or what would be words or
lexemes, for a spanish person.
When computers were used for english text, the standard ASCII for codifying
characters as bytes was enough. Today, it is not. There are many symbols and
one byte is not enough.
.PP
Plan 9 uses
.B Unicode ,
which is a standard for representing symbols used for
text writing. Indeed, Plan 9 was the first system to use Unicode.
The symbols used to write text are not called characters, but \fBrunes\fP.
Each rune is represented in Plan 9 as a 16-bit (two bytes) number. Most
programs processing text are expected to use runes to do their job. The data type
.CW Rune
is defined in
.CW libc.h ,
as a short integer.
.PP
However,
using a stream of 16-bit numbers to exchange text between different programs
would be a nightmare because it would break all the programs written to use
just ASCII, which uses a single byte for each character. Furthermore, many C programs
use strings codified as a sequence of bytes terminated by a final null byte. Sending
a stream of 16-bit runes to such programs will make them fail.
.PP
To maintain compatibility with the huge amount of software that existed when
Unicode was invented, a encoding was designed to transform an array of runes
into a byte stream that could be backward compatible with ASCII. This encoding is
called
.B UTF-8 ,
(Universal character set Transformation Format, 8 bits)
or just UTF (for short).
UTF-8 was
invented by Ken Thompson (apparently in a dinner's table, shared with Rob Pike).
.ix "Ken Thompson
.ix "Rob Pike
Runes like ☺, α, and Ж do not use a single byte when codified in UTF. A rune
may use up to three bytes in Plan 9's UTF.
.PP
A program reading text, reads a UTF byte stream, that is
exactly the same used by ASCII when the text contains characters present in
7-bit ASCII (most characters but for accentuated letters and other special symbols).
After having read some text, if it is to be processed as such, the program converts
the UTF representation into Unicode. Then it is processed. Afterwards, to output
some text as a result, the program is expected to convert the text from Unicode
back into UTF, before sending it to the output stream. Files that keep text
used as input (or coming as output) for programs, are also maintained in UTF.
.PP
The file
.CW /dev/cons
does not provide characters when read. It provides runes. In many cases, a rune
may fit in a single byte. In other cases, it will not. The console keyboard driver knows how
to compose multiple keys to type runes not in the keyboard. The whole set of rules
is described in
.I keyboard (6).
.ix keyboard
Many runes may be generated by using the
.I compose
key, usually
.I Alt ,
and a couple of keys that remind the rune generated. For example, typing
.I Alt
.CW -
.CW >
will produce →.
.I Alt
.CW <
.CW -
will produce ←.
.I Alt
.CW s
.CW o
leads to ⁰ ,
and
.I Alt
.CW s
.CW a
leads to ª.
.ix "greek letter
Greek letters can be generated by typing
.I Alt
.CW *
and their roman counterparts. Thus,
.I Alt
.CW *
.CW m
leads to μ.
The file
.CW /lib/keyboard
lists many runes that can be composed using several other keys in this way.
.PP
In general,
any Unicode rune may be also generated by typing
.I Alt
.CW X
.I nnnn ,
where
.I nnnn
is the code in Unicode for the rune. So,
.I Alt
.CW X
.CW 00fe
leads to þ.
The file
.CW /lib/unicode
lists unicode runes along with their codes.
.ix "unicode code
.PP
Programs that
read and write data without assuming that it is text, may still operate
one byte at a time, if they want. Or many at a time.
However, programs reading text and looking
into it, should use the functions in
.I rune (2),
or they would misbehave for non-english text.
The
functions in the C library described in
.I rune (2)
provide conversion from UTF to runes and vice-versa. Among others, we have these ones.
.P1
; sig runetochar chartorune
int runetochar(char *s, Rune *r)
int chartorune(Rune *r, char *s)
.P2
.ix [runetochar]
.ix [chartorune]
.ix [Rune]
.LP
Now we can read
“characters” properly from the console, for the first time. The next program
converts what it reads to uppercase.
.so progs/rune.c.ms
.ix [rune.c]
.LP
It processes one rune at a time. The function
.CW chartorune
extracts a rune from the byte string pointed to by
.CW s ,
and places it at
.CW &r .
The number of bytes occupied by the rune in UTF (that is, in the string at
.CW s ),
is the return value from the function. The function
.CW runetochar
does the opposite conversion, and returns also the number of bytes used. It is
guaranteed that a rune will not occupy more than
.CW UTFmax
.ix [UTFmax]
bytes (3 bytes in Plan 9). Other convenience routines, like
.CW toupperrune ,
.ix [toupperrune]
replace the traditional ones for characters.
Our program works perfectly with runes that do not fit in ASCII.
.P1
; 8.out
!!I feel ☺ today.
I FEEL ☺ TODAY.
.P2
.LP
An equivalent program, but unaware of unicode, would fail. Using this loop to do
the conversion instead of the Rune routines
.ix "rune conversion
.P1
for (i = 0; i < nr; i++)
buf[i] = toupper(buf[i]);
.P2
.LP
produces this result for this input.
.P1
!!España includes Espuña.
ESPAñA INCLUDES ESPUñA.
.P2
.LP
The letter
.CW ñ
was not properly capitalized into
.CW Ñ .
It could have been worse. We could have processed part of a rune, because
runes may span several bytes. For example, translating to uppercase by
.P1
buf[i] = buf[i] + 'A' - 'a'
.P2
.LP
will lead to a surprise (besides being wrong anyway).
.BS 2 "Mouse input
.LP
.ix "mouse input
Another popular input device is the mouse. The mouse interface is provided by
the mouse driver through a few
files in
.CW #m .
.ix "[#m] device driver
.ix "mouse device
.P1
; lc '#m'
cursor mouse mousectl
;
.P2
.LP
This name is usually bound along with other devices at
.CW /dev .
The file
.CW mousectl
.ix [/dev/mouse]
.ix [/dev/mousectl]
is used to write strings to configure and adjust mouse settings. For example,
.P1
; echo accelerated >/dev/mousectl
.P2
.LP
turns on mouse acceleration (a quick move in one direction will move the mouse
fast in that direction, many more pixels than implied by the actual movement).
On the other hand,
.P1
; echo linear >/dev/mousectl
.P2
.LP
disables mouse acceleration. There are several other messages. Depending on
the hardware for the mouse, some control requests may be ignored (if they
do not make sense for a particular mouse).
.PP
When the window system is running, \f(CWrio\fP is the one that reads and writes these
files. As with
.CW /dev/cons ,
\f(CWrio\fP provides its own (multiplexed) version for these files, on each window.
Reading
.CW #m/mouse
yields mouse events. However, this file may not be opened more than once at the
same time.
.ix "exclusive open
.P1
; cat '#m/mouse'
cat: can't open #m/mouse: '#m/mouse'
device or object already in use
.P2
.LP
Since \f(CWrio\fP has open
.CW #m/mouse ,
.ix "mouse event
to read mouse events, nobody else will be able to open it until \f(CWrio\fP terminates and
the file is closed. This is a safety measure to synchronize multiple programs trying to use this
device at the same time. In any case, the multiplexed version of the mouse,
.CW /dev/mouse ,
provided by \f(CWrio\fP for each window is for us to read.
.P1
.ps -1
; cat /dev/mouse
m 670 66 0 2257710 m 676
68 0 2257730 m 677 74
0 2257750 m 680 77 0 2257770
.ps +1
.P2
.LP
This file will never seem to terminate. No end of file indication for it. Indeed,
.CW /dev/mouse
.ix stream
is a stream of mouse events. Each read will block until the mouse produces
an event (it is moved or a button is pressed or released). At that point,
.CW /dev/mouse
returns 49 bytes. There is an initial letter
.CW m
followed by four numbers: the x and y coordinates for the mouse, a number
stating which buttons are pressed, and a time stamp.
.PP
.ix "time stamp
The time stamp is handy
when a program wants to detect double and triple clicks. In Plan 9, the mouse might even
be attached to a different machine. The time for the clicks that matters is that
of the machine with the mouse, when the mouse events were received from the
hardware by the mouse driver. The time as seen by the program reading the mouse
might differ a little bit (there may be delays between different mouse events
introduced because our program moved out of the processor, or because the system went
busy, etc.).
.PP
Mouse coordinates
.ix "mouse coordinate
.ix "pixel
.ix "picture element
.ix "screen
.ix "screen size
correspond to the position of the pointer in the screen. The screen is a matrix
of pixels. A typical screen size is 1024x768 (1024 pixels wide, on the
.I x
axis, and
768 pixels of height, on the
.I y
axis). Other popular screen sizes are 1280x1024 or
1600x1200. The origin is coordinate (0,0), at the upper left corner of the screen.
Thus, for a 1024x768 screen, the bottom right corner would be (1023,767).
There are
increasing values for
.I x
as you move to the right, and increasing
.I y
values as you move
down.
.PP
The first mouse event reported by
.CW cat
was for the coordinate (670,66). That is, the tip of the arrow used as a cursor
was pointing at the pixel number 670 on the x axis (counting from 0)
and number 66 on the y axis.
The mouse was then moved a little bit down-right, and the next coordinate reported
by
.CW cat
was (676,68).
.PP
.ix "mouse position
Following the two numbers reporting the pointer position, there is a number
that lets you know the state for mouse buttons (always zero in the example
above). To experiment with this, we
are going to write a small program that reads the mouse and prints
one mouse event per line, which is easier to read. Before looking at the source
for the program, this is an example run.
.P1
; 8.mouse
mouse pos=[896 189] buttons=0 \fIwe move the mouse...\fP
mouse pos=[895 190] buttons=0
mouse pos=[894 190] buttons=0
.I ...
.P2
.P1
mouse pos=[887 191] buttons=1 \fIbutton-1 down\fP
mouse pos=[887 191] buttons=3 \fIbutton-2 down\fP
mouse pos=[887 191] buttons=1 \fIbutton-2 up\fP
mouse pos=[887 191] buttons=0 \fIbutton-1 up\fP
.I ...
.P2
.P1
mouse pos=[887 191] buttons=0
mouse pos=[887 191] buttons=1 \fIbutton-1 down\fP
mouse pos=[887 191] buttons=3 \fIbutton-2 down\fP
mouse pos=[887 191] buttons=7 \fIbutton-3 down\fP
;
.P2
.LP
.ix "mouse button-1
.ix "mouse button2
.ix "mouse button2
As you could see, each button is codified as a single bit in the number. Button-1
is the bit 0, button-2 is the bit 1, button-3 is the bit 2, and so on. A click for button
one will yield
.CW 1
while it is down, and
.CW 0
when released. A click for button 3 will yield
.CW 4
(i.e.,
.CW 100
in binary)
when it is down and
.CW 0
when released. Our program exits when all the three buttons are down, that is,
when the number is
.CW 7
(i.e.,
.CW 111
in binary).
.PP
Instead of reading
.CW /dev/mouse
by itself, the program uses the
.I mouse (2)
.ix "mouse library
library. This library provides a mouse interface for threaded programs. Programs
using the mouse are likely to do several things concurrently (attend the keyboard,
do something for their user interface, etc.). Therefore, it is natural to write a
threaded program when the application requires a graphical user interface.
.so progs/mouse.c.ms
.LP
The program must include
.CW mouse.h ,
which contains the definitions for the library, along with
.CW draw.h ,
which defines some data types used by the library.
The function
.CW initmouse
.ix [initmouse]
.ix "mouse initialization
initializes the mouse interface provided by the library. It creates a process to
read the file given as an argument and obtain mouse events.
.P1
; sig initmouse
Mousectl *initmouse(char *file, Image *i)
.P2
The return value
is a pointer to a
.CW Mousectl
structure:
.ix [Mousectl]
.P1
typedef struct Mousectl Mousectl;
struct Mousectl
{
Channel *c; /* chan(Mouse) */
Channel *resizec; /* chan(int)[2] */
\fI...\fP
};
.P2
.ix "mouse event channel"
that contains a channel,
.CW Mousectl.c ,
where mouse events are sent by the process reading the mouse. Therefore, to
obtain mouse events all we have to do is to call
.CW recv
on this channel. Each mouse event is codified as a
.CW Mouse
.ix [Mouse]
structure, containing the buttons, the coordinates, and the time stamp for the
mouse (as read from the mouse file).
.P1
typedef struct Mouse Mouse;
struct Mouse
{
int buttons; /* bit array: LMR=124 */
Point xy;
ulong msec;
};
.P2
.LP
Thus, the call
.P1
recv(mctl->c, &m)
.P2
.ix [recv]
.LP
is the one reading mouse events in the program. The program prints the
coordinates, kept at
.CW Mouse.xy ,
and the buttons, kept at
.CW Mouse.buttons .
Using coordinates is so common that
.CW draw.h
defines a
.CW Point ,
.ix [Point]
along with some functions to operate on points.
.P1
typedef struct Point Point;
struct Point
{
int x;
int y;
};
.P2
.LP
So, the
.I x
coordinate for the mouse event stored at
.CW m
would be
.CW m.xy.x ,
and the
.CW y
coordinate would be
.CW m.xy.y .
.PP
To print
.CW Points ,
the function
.CW Pfmt ,
.ix [Pfmt]
.ix "[%P] format"
declared by
.CW draw.h ,
can be installed as a format function for the
.CW print
function family. The call
.P1
fmtinstall('P', Pfmt);
.P2
instructs
.CW print
to use
.CW Pftmt
to print any argument that corresponds to a
.CW %P
in its format string. This is very convenient for printing coordinates. By the way,
there are many other format functions defined in the standard library. And you
may define your own ones. It is all explained in
.I fmtinstall (2),
.ix [fmtinstall]
.ix "format install
which details the support for user-defined print formats.
.PP
Finally, the function
.CW closemouse
.ix [closemouse]
closes the mouse file and releases any resource related to the
.CW Mousectl
structure (most notably, its memory, the channel, and the process reading the mouse).
.PP
The rest of the mouse interface (not used by this program) will be deferred until we see something
about graphics.
.BS 2 "Devices for graphics
.LP
.ix "graphic devices
The whole idea behind graphic terminals is quite simple. A portion of memory
is used to keep the image(s) to be shown at the terminal. The hardware device
that updates the monitor image by reading this memory is called a graphics card.
But things are not so simple anymore.
.PP
.ix VGA
.ix monitor
Ultimately, graphics are supported by extremely complex hardware devices like
VGA cards (Video Graphic Arrays).
Such devices use system memory (and/or memory attached directly
to the graphics card) to store images to be shown at the monitor. It turns out
that monitors are also very complex these days. You only have to consider that
graphic cards and monitors speak together using particular protocols through the
video cable that goes from the card to the monitor
.PP
Games and other popular applications demanding graphics have lead to graphic
cards that know by themselves how to do many 2D and 3D graphics operations.
Sometimes, this is called
.B "hardware acceleration"
for video and graphics operations.
.PP
Fortunately, all this is hidden behind the device driver for the video card used in
your terminal. The
.I vga (3)
.ix "vga device
.ix "[#v] device driver
device is in charge for dealing with the VGA card in your PC. Its file interface is
available at
.CW #v .
.P1
; lc '#v'
vgabios vgactl vgaovl vgaovlctl
.P2
.LP
.ix [vgactl]
.ix BIOS
.ix ROM
The most interesting file is
.CW vgactl ,
which is the interface for configuring the card for a proper operation. Other
files provide access to extra features, like overlaid images, and for the software
kept in ROM in the PC (called BIOS, for Basic Input/Output System, but not basic)
that is useful to deal with the card.
.PP
.ix "text mode
Initially, while the system is booting, the graphics card operates in an ancient
text-only setting. It uses some memory to display a matrix of characters
in the screen, usually of 80 columns and 24 rows, or 80x24. But the hardware
can do much more. It knows how to display graphics. When the card operates to
show graphics, it can be adjusted to show a particular number of pixels. We saw
a little bit of this when describing the coordinates used by the mouse.
.PP
.ix "graphics mode
Most graphic cards can show 640x480 pixels, 1024x768 pixels, 1280x1024 pixels, and
perhaps even more. For each pixel, the number of colors that the card can show
is determined by the number of bits used to encode a value for the pixel. Using 8
bits per pixel leads to at most 256 colors. Therefore, a particular screen size
would not just be 1024x768, but rather 1024x768x8 or perhaps 1024x768x24.
.PP
Each one of these different configurations is usually called a
graphics \fBmode\fP.
So, the configuration for the VGA size 1280x1024x24 is also known as the
1280x1024x24 mode.
Because the size of the actual screen is fixed, the number of pixels determines the size
of each pixel in the screen. Thus, different modes are also referred to as different
.I resolutions .
.ix "screen resolution
.PP
Changing the mode in the VGA card can be very complex. An auxiliary program,
.CW aux/vga
.ix [aux/vga]
.ix [vga]
is in charge of adjusting the vga configuration.
You will use the file interface provided by the
.I vga
device driver just to adjust a few parameters, and not for doing other complex
things. For that, you have
.CW aux/vga .
For example,
.P1
aux/vga -l text
.P2
.LP
puts the machine back into text mode, as it was during boot. In the same way,
.P1
aux/vga -l 1024x768x8
.P2
.LP
loads the mode for 1024x768x8. On the other hand,
if our graphics card is not properly handled by
our device driver, we may disable hardware acceleration by using the interface
at
.CW #v
instead of
.CW aux/vga .
.P1
; echo hwaccel off >/dev/vgactl
.P2
.ix "hardware acceleration
.LP
Also, writing
.CW blank
to
.CW vgactl
.ix "screen blank
will blank the screen, until we move the mouse. And
.P1
; echo blanktime 30 >/dev/vgactl
.P2
.LP
will make the screen blank after 30 minutes of (mouse) inactivity.
.PP
The size used by
.CW aux/vga
to set the mode for the graphics card is kept in the environment variable
.CW vgasize .
The type of monitor is kept in the environment variable
.CW monitor .
.ix [$monitor]
.P1
; echo $vgasize
1280x800x24
; echo $monitor
cinema
.P2
.LP
Both are the primary parameters used by
.CW aux/vga
to set the VGA mode. This happens during the system startup, and you will
probably not be concerned about this, but in any case,
.CW $vgasize
.ix [$vgasize]
is a useful bit of information to write scripts that depend on the screen resolution.
.PP
In any case, reading
.CW vgactl
provides most of the configuration parameters for the graphics card that you
might want to use.
.P1
; cat /dev/vgactl
type vmware
size 1280x800x32 x8r8g8b8
blank time 30 idle 0 state on
hwaccel on
hwblank off
panning off
addr p 0xfa000000 v 0xe0000000 size 0xa8c000
.P2
.LP
The interface provided by the kernel for using graphics is not that of
.I vga .
That is a particular control interface for a particular kind of graphics card.
Graphics are provided by the
.I draw (3)
device driver. The
.I draw
.ix "draw device
device relies on the facilities provided by the graphics card
attached to the system, and provides the primary system interface to graphics.
.PP
.ix "draw connection
Draw maintains
.I connections
between processes using graphics, and the graphics device itself. Of course,
connections to the draw device are represented as files, similar to what happen
with network connections. Its file tree is available at
.CW #i ,
.ix "[#i] device driver
.ix [/dev/draw]
but is also bound at
.CW /dev .
.P1
; lc /dev/draw
1 2 42 new
; lc /dev/draw/1
colormap ctl data refresh
.P2
.LP
Here, directories
.CW 1 ,
.CW 2 ,
and
.CW 42
are the interface for three different connections maintained as of this moment
in my terminal. The directory for a connection (besides other files) has a
.CW ctl
and a
.CW data
.ix "[ctl] file
.ix "[data] file
.ix "line directory
file, like we saw with network line directories. Opening the file
.CW /dev/draw/new
establishes a new connection. So, a process that wants to use graphics must
open
.CW /dev/draw/new ,
and then write to the
.CW data
file for its connection messages that encode the graphic operations to be
performed.
.PP
The draw device provides the
.I Image
.ix image
abstraction, along with operations to allocate, deallocate, and draw on it.
All the graphics operations are performed by this device. Programs using graphics
talk directly to the device, by establishing connections to it, and asking it to
perform operations on images. Instead of using the device interface directly,
most programs use the
.I draw (3)
library, as shown next.
.BS 2 "Graphics
.LP
.ix "graphics
Graphics are provided through the file interface for the draw device. This happens
both when using the console (before the window system runs) and after running
the window system. When run in the console, a graphics program will use the entire
screen as its window, when run within the window system, it will use just the window.
That is the only difference regarding graphics, which is why you can execute
\f(CWrio\fP in a window, as we did some time ago when connecting to a CPU server.
.PP
The following program draws the entire
.B screen
in black for 10 seconds. Like many other programs, it uses the
functions from the draw library, as described in
.I graphics (2),
and
.I draw (2),
instead of speaking to the draw device by itself.
.so progs/black.c.ms
.ix [black.c]
.LP
The program calls
.CW initdraw
.ix [initdraw]
.ix "graphics initialization
to
establish a connection to the draw device. This function initializes
some global variables, including
.CW screen ,
and
.CW display ,
.ix [screen]
.ix [display]
that are used later in the program.
.P1
.ps -1
; sig initdraw
int initdraw(void (*errf)(Display*, char*),
char *font, char *label)
.ps +1
.P2
.LP
.ix [errfun]
.ix font
.ix [/dev/label]
.ix "window label
The first parameter points to a function called by the library upon errors. Passing
a nil pointer means that the draw library will use its own, which prints a diagnostic
message and terminates the program. Usually, that is all you will want to do.
The second parameter states which font to use for drawing text. Again, passing
a nil value means that the library will use a reasonable default. The last parameter
is simply a textual label for the window, which we define to be the program name.
The function writes the text in
.CW label
to the file
.CW /dev/label ,
to let \f(CWrio\fP know how the window is named, in case it is hidden.
.PP
The
.CW display
variable points to a
.CW Display
.ix [Display]
structure that represents the connection to the draw device. It maintains all the
information necessary to speak with the device, for drawing. In particular, it
keeps the file descriptor for the
.CW /dev/draw/\fIn\fP/data
file, that is, for the connection to the device.
Calling
.CW closedisplay(display)
.ix [closedisplay]
as the program does after 10 seconds, closes the connection and releases any
graphic resources associated to it.
.PP
Another useful global variable, also initialized by
.CW initdraw ,
is
.CW screen .
This variable points to a structure representing the screen (i.e., the memory)
where you may draw and use graphics.
When running in the console,
.CW screen
corresponds to the entire screen. When running inside a \f(CWrio\fP window,
.CW screen
corresponds to the part of the screen used by the window. In what
follows, we will always speak about
.I "the window"
used by the program. But it should be clear that such “window” may be
the entire screen if no window system is running.
.PP
To which data type does
.CW screen
point to? Where can you draw things on? It turns out that
the screen is an image, the data abstraction provided by
.I draw (3).
It represents a piece of memory used as an image by the graphics card. It is
just a rectangular picture.
.ix "drawing graphics
A program may draw by changing bits in the image for its screen. Most of
things a program uses for drawing are also images. For example, colors
are images (with pixels in the appropriate color), to write text in the screen
a program draws images for the appropriate characters, a window is
essentially an image (that a program will use as its screen), the entire
screen (also called the display) is an image as well.
The data type
.CW Image ,
.ix [Image]
is defined in
.CW draw.h .
.P1
.ps -2
typedef struct Image Image;
struct Image
{
Display *display; /* display; connection to draw(3) */
int id; /* id of draw(3) Image */
Rectangle r; /* rectangle for the image */
Rectangle clipr; /* clipping rectangle */
int depth; /* number of bits per pixel */
ulong chan; /* how to encode colors */
int repl; /* flag: replicated to tile clipr */
Screen *screen; /* or nil if not a window */
};
.ps +2
.P2
.LP
Together,
.CW display
and
.CW id
identify an image as the one named
.I id
in the draw device at the other end of the connection represented by the
.I display .
.PP
An interesting piece of information in this structure is
.CW Image.r ,
It describes the rectangle in the entire screen used by the image. Thus,
.ix "[screen] rectangle
.CW screen->r
describes the (rectangular) area used in the screen by our window. Like
coordinates (or
.CW Points ),
rectangles are a popular data type when doing graphics. The draw library
defines the appropriate data type.
.ix [Rectangle]
.P1
typedef struct Rectangle Rectangle;
struct Rectangle
{
Point min;
Point max;
};
.P2
.LP
A rectangle is defined by two points (the upper left corner and the bottom right one).
Choosing (0,0) as the origin simplifies arithmetic operations for points. In
accordance with this, the convention is that a rectangle
.I includes
its
.CW min
point (upper left corner) but does
.I not
include its
.CW max
point (bottom right corner). The point with biggest coordinates inside a rectangle would
be (\f(CWmax.x\fP-1,\f(CWmax.y\fP-1).
.ix "window coordinates
.PP
We are close to understanding the line
.P1
draw(screen, screen->r, display->black, nil, ZP);
.P2
.LP
that calls the function
.CW draw
.ix [draw]
.ix [mask]
.P1
.ps -2
; sig draw
void draw(Image *dst, Rectangle r, Image *src, Image *mask, Point p)
.ps +2
.P2
.LP
You might think that after understanding how to use this function, there might be
many other ones that will be hard to understand. That is not the case. The
function
.CW draw
is the only thing you need for drawing. There are other routines as a convenience
to draw particular things, but all of them use just
.CW draw .
.PP
Basically,
.CW draw
takes a image as the source and draws it (over) on a destination image. That is,
each pixel (\fIi\fP, \fIj\fP) in the source is copied to the pixel (\fIi\fP, \fIj\fP) in the
destination. Here,
.CW screen
was the destination image, and
.CW display->black
.ix [black]
was the source image.
.is "source image
.PP
The source image represents the color
black, because it is an image with all its pixels in that color.
Although we could draw the entire
screen by copying black pixels from
.CW display->black ,
this image is not that large. Images that have their
.CW repl
field set to true are used as
.I tiles .
.ix "tiling
The implementation for
.CW draw
tiles the image as many times as necessary to fill the rectangle where it is to be
drawn. So,
.CW display->black
might have just one black pixel. Only that before copying any pixel from it,
.CW draw
replicated it to obtain an image of the appropriate size.
.PP
The second parameter is the rectangle where to confine the drawing
of the source in the target. This is called a
.B clip
rectangle, because no drawing occurs outside it.
The program used
.CW screen->r ,
and so it draws in the screen
the whole rectangle used by
.CW screen .
Drawing in a target image will not draw outside that image. Thus, the drawing
is confined to the intersection of the target image's rectangle and the rectangle
given to
.CW draw .
In this case, we draw in the intersection of
.CW screen->r
(the target's rectangle)
and
.CW screen->r
(the parameter for draw). That is, of course, just
.CW screen->r .
.PP
The image for the screen uses real screen coordinates. In other
cases, you may have images that do not use screen coordinates. To draw one of
these images you must
.I translate
the coordinates for the source so that they match the area in the target where you
want to draw. The last parameter for
.CW draw
is a point that indicates which translation to do. Passing the point (0,0), which is
defined as
.CW ZP
.ix [ZP]
.ix "screen origin
in
.CW draw.h ,
.ix "coordinate translation
.ix "image copy
performs no translation: each pixel (\fIi\fP, \fIj\fP) in the source is
copied to the pixel (\fIi\fP, \fIj\fP) in the
destination. Passing other point will ask
.CW draw
to translate the source image (coordinates) so that the given point is aligned
with the top-left corner of the rectangle where to draw.
.PP
The
.CW mask
.ix [mask]
parameter allows an image to be used as a mask. This is useful to draw things
like cursors and the like. In most cases you may use nil, and not a mask.
We do not discuss this parameter here,
the
.I draw (2)
manual page has all the details.
.PP
One thing that remains to be discussed about our program is the call to
.CW flushimage .
.ix "flushimage
.ix "draw~operation flush
Writing to the draw device for each single operation performed by the draw
library would be very costly. To improve efficiency, the library includes buffering
for writes to the draw device's files. This is similar to what we saw regarding
buffered input/output. Only that in this case, draw is always doing
buffered output. As a result, if you draw, it many happen that your operations
are still sitting in the buffer, and the actual device may not have received them.
A call to
.P1
flushimage(display ,1)
.P2
flushes the buffer for the display. The last parameter is usually set to true, to
indicate to the driver that it must update the actual screen (in case it also
maintains another buffer for it).
.PP
If you remove this line from the program, it will draw, but the window will remain
white (because the operation will not take effect).
Fortunately, you will not need to worry about this in many cases, because the
functions for drawing graphics and text call
.CW flushimage
on their own. Nevertheless, you may have to do it by yourself if you use
.CW draw .
.BS 2 "A graphic slider
.LP
.ix "graphic slider
We want to implement a small graphical application, to let the user adjust
a value between 0% and 100%. This is a graphical slider, that can be run in
a window. The program will print to its standard output the value corresponding
to the position of the slider as set by the user using the mouse or the keyboard.
.PP
.ix "window resize
The real display does not have that problem, but windows can be resized.
The window system supplies its own menus and mouse language to let the user
resize, move, and even hide and show windows. For our program, this means
that the screen might change!
.PP
.CW Rio
assumes that a program using graphics is also reading from the mouse.
And note that the mouse is the virtual mouse file \f(CWrio\fP provides for
the window!
Upon a resize, \f(CWrio\fP delivers a weird mouse event to the program
reading
.CW /dev/mouse .
This event does not start with the character
.CW m ,
it starts with the character
.CW r ,
to alert of the resize.
After the program is alerted, it should update the image it is using as its
.CW screen
(that is, as the window). The program can do so because the file
.CW /dev/winname
.ix [/dev/winname]
.ix "window name
contains the name for the image to be used as a window, and this can be used
to lookup the appropriate image for the window using its name.
.PP
The function
.CW getwindow
.ix [getwindow]
.ix "acquiring window
updates the
.CW screen
variable, after locating the image to be used as the new window.
As a curiosity, the window system draws a border for the window in the image
for the
.CW screen .
However, your program is unaware of this because
.CW getwindow
adjusts
.CW screen
to refer to the portion of the image inside the border.
.PP
But how do we know of resize events from the mouse? Simple. Look back
to see the fields for a
.CW Mousectl
structure,
which we obtained before by calling
.CW initmouse .
You will notice that besides the channel
.CW Mouse.c ,
used to report mouse events, it contains a channel
.CW Mouse.resizec .
.ix "window resize
.ix "resize event
Resize events are sent through this channel. The receipt of an integer
value from this channel means that the window was resized and that the
program must call
.CW getwindow
to reestablish its
.CW screen
for the new window.
.PP
The following program draws the entire window in black, like before. However,
this program re-acquires its window when it is resized. It creates a separate
thread to attend the mouse, and another one to process resizes of the window,
removing all that processing from the rest of the
program. In this case, it may be considered an overkill. In more complex
programs, placing separate processing in separate threads will simplify things.
After starting the thread for attending the mouse, and the one attending
resizes, the program calls the function
.CW blank
.ix [blank]
that draws the entire window in black.
.so progs/resize.c.ms
.ix [resize.c]
.LP
Try running the program
.CW 8.black
and using the arrow keys to scroll up/down the window. It scrolls!
.CW Rio
thinks
that nobody is using graphics in the window. That does not happen to
.CW 8.resize ,
which keeps the mouse file open.
.PP
The implementation for
.CW blank
is taken from our previous program. It draws the entire window image in black and
flushes the draw operations to the actual device.
.P1
void
blank(void)
{
draw(screen, screen->r, display->black, nil, ZP);
flushimage(display, 1);
}
.P2
.LP
.ix "mouse event processing
Mouse processing for our program is simple. Any button click terminates the program.
But users expect the action to happen during the button release, and not
during the previous press. Therefore,
.CW mousethread
.ix [mousethread]
loops receiving mouse events. When a button is pressed, the function reads more
events until no button is pressed. At that point,
.CW closedisplay
terminates the connection to the display,
.CW closemouse
.ix [closemouse]
closes the mouse device, and the program exits.
.P1
void
mousethread(void* arg)
{
Mousectl*mctl = arg;
Mouse m;
for(;;){
recv(mctl->c, &m);
if(m.buttons){
do {
recv(mctl->c, &m);
} while(m.buttons);
closedisplay(display);
closemouse(mctl);
threadexitsall(nil);
}
}
}
.P2
.LP
Note how by placing mouse processing in its own thread, the programming language
can be used to program the behavior of the mouse almost like when describing it
in natural language.
.PP
The new and interesting part in this program is the code for the thread reading
resize events.
.ix "resize event
.ix [resizethread]
.P1
void
resizethread(void* arg)
{
Mousectl*mctl = arg;
for(;;){
recvul(mctl->resizec);
if (getwindow(display, Refnone) < 0)
sysfatal("getwindow: %r");
blank();
}
}
.P2
.LP
After receiving a resize event, through
.CW mctl->resizec ,
the program calls
.CW getwindow
on the display, which updates
.CW screen .
Afterwards, it blanks the image for the new window.
The second parameter to
.CW getwindow
has to do with window overlapping. It identifies the method used to refresh the
window contents after being hidden. When two windows overlap, someone must
maintain a copy of what is hidden behind the window at the top. This
.I backup
is called
.B "backing store" .
.CW Rio
provides backing store for windows, and the constant
.CW Refnone
.ix [Refnone]
asks for no further backup (i.e., no refresh method).
.PP
We now want this program to draw a slider, like those of figure [[!slider!]].
The slider draws in yellow a bar representing the value set by the slider, and fills
the rest of the window with the same background color used by \f(CWrio\fP. Using the
mouse, it can be adjusted to the left (the one above in the figure) and to the right
(the one below in the figure). When the slider is at the left, it represents a value of 0
(or 0% of a value set by the slider). When it is at the right, it represents a value of 100.
.LS
.BP slider.ps 2.3i
.LE F Two example windows for the slider application. One at 30%, another at 84%.
.PP
Maintaining the slider is a separate part of the processing done by the program,
which uses
a different thread for that purpose. We will call it
.CW sliderthread .
The existing code also requires changes. First,
.CW threadmain
.ix [threadname]
.ix channel
must create now a channel to
send new values for the slider to the slider thread, and must create the thread itself. Also,
we must get rid of the call to
.CW blank()
in
.CW threadmain .
This program does not blank its window.
Since we decided that
.CW sliderthread
is in charge of the slider,
.CW threadmain
will no longer draw anything. Instead, it may
send a value to the slider, to adjust it to a reasonable initial value (and draw it).
.P1
.ps -1
.ti -1i
.B
.BX slider.c
.ps +1
.CW
.vs .2i
.I "...Initially, all the code as before, but for the changes explained in the text...
Channel*sliderc;
.I "..."
void
threadmain(int, char*argv[])
{
\fI...all code here as before...\fP
sliderc = chancreate(sizeof(ulong), 0);
threadcreate(sliderthread, sliderc, 8*1024);
sendul(sliderc, 50);
threadexits(nil);
}
.P2
.LP
The application must redraw the window when the resize thread receives a
resize event. To do so,
.CW resizethread
will no longer call
.CW blank .
Instead, it asks the slider thread to redraw the slider on the new window
(as if the value had changed). Because only values between 0 and 100 are
meaningful to the slider, we can adopt
the convention that when the slider receives any number not in the range
[0,100], it simply redraws for its current value. So, we replace
.P1
blank();
.P2
.LP
in
.CW resizethread
with
.P1
.ps -1
sendul(sliderc, ~0); // A value not in 0..100
.ps +1
.P2
.LP
This is the code for the new thread. It will be blocked most of the time, waiting
for a value to arrive through
.CW sliderc .
Upon receiving a value, the slider value kept in
.CW val
is updated if the value is in range. Otherwise, the value is discarded. In any case,
the slider is drawn and its value printed in the output. That is the utility of the
program, to generate a value adjusted by the user using the slider. As an optimization,
we do not draw the slider if the value received through the channel is the current
value for the slider.
The code for
drawing the slider will be encapsulated in
.CW drawslider ,
to keep the function readable.
.ix "slider drawing
.P1
void
sliderthread(void*)
{
uint val, nval;
val = ~0;
for(;;){
nval = recvul(sliderc);
if (nval >= 0 && nval <= 100){
if (nval == val)
continue;
val = nval;
}
drawslider(val);
print("%d\en", val);
}
}
.P2
.LP
Note how different parts of the program can be kept simple, and without race
conditions. This thread is the only one in charge of the value for the slider.
Each other thread is also in charge of other type of
processing, using its own data. Communication
between threads happens through channels, which at the same time synchronizes
them and allows them to exchange data.
.PP
To draw the slider, we must draw three elements: A yellow rectangle for the part set,
a grey rectangle for the unset part, and a black thick line to further mark them apart.
After defining rectangles
.CW set ,
.CW unset ,
and
.CW mark ,
for each element, we can draw the slider as follows.
.P1
draw(screen, setrect, setcol, nil, ZP);
draw(screen, unsetrect, unsetcol, nil, ZP);
draw(screen, markrect, display->black, nil, ZP);
.P2
.LP
Provided that
.CW setcol
.ix color
is an image for the color of the set part, and
.CW unsetcol
is an image for the color of the unset part.
An image for the black color was available, but we also needed two other colors.
.PP
The function
.CW allocimage
can be used to allocate a new image. We are going to use it to build two new images
for the yellow and the grey colors used for the set and the unset parts. We declare
both images as globals, along with
.CW sliderc ,
.P1
Channel*sliderc;
Image* setcol;
Image* unsetcol;
.P2
.LP
and add these two lines to
.CW threadmain ,
right after the call to
.CW initdraw .
.P1
setcol = allocimage(display, Rect(0,0,1,1),
screen->chan, 1, DYellow);
unsetcol = allocimage(display, Rect(0,0,1,1),
screen->chan, 1, 0x777777FF);
.P2
.LP
A call to
.CW allocimage
.ix [allocimage]
.ix "image allocation
allocates a new image, associated to the
.CW Display
.ix [Display]
given as an argument.
.P1
.ps -2
; sig allocimage
Image *allocimage(Display *d, Rectangle r,
ulong chan, int repl, int col)
.ps +2
.P2
.LP
When the display is closed (and the connection to
.I draw
is closed as a result), the images are deallocated. Note that the images are kept
inside the draw device. The function talks to the device, to allocate the images,
and initializes a couple of data structures to describe the images (you might call
them
.I "image descriptors" ).
.ix "image descriptor
.PP
The second argument
for
.CW allocimage
is the rectangle occupied by the image. In this case, we use a rectangle with
points (0,0) and (1,1) as its
.CW min
and
.CW max
points.
If you remember the convention that the minimum point is included in the rectangle,
but the maximum point is not (it just marks the limit), you will notice that
both images have just one pixel. That is, the point with coordinates (0,0).
For declaring a literal (i.e., a constant) for a
.CW Rectangle
data type, we used
.CW Rect ,
which returns a
.CW Rectangle
given the four integer values for both coordinates of both extreme points. Another
function, useful to obtain a
.CW Rectangle
from two
.CW Point
values, is
.CW Rpt .
.P1
; sig Rect Rpt
Rectangle Rect(int x0, int y0, int x1, int y1)
Rectangle Rpt(Point p, Point q)
.P2
.LP
By the way, the function
.CW Pt
.ix [Pt]
.ix [Rect]
.ix [Rpt]
does the same for a
.CW Point .
Indeed,
.CW ZP
is defined as
.CW Pt(0,0) .
.P1
; sig Pt
Point Pt(int x, int y)
.P2
.LP
Images for colors need just one pixel, because we ask
.CW allocimage
to set the
.CW repl
.ix "replicated image
.ix "[repl]
flag for both images. This is done passing true as a value for its
.CW repl
parameter. Remember that when this flag is set,
.CW draw
tiles the image as many times as needed to fill the area being drawn.
.PP
Two arguments for
.CW allocimage
remain to be described, but we will not provide much detail about them. The argument
.CW chan
is an integer value that indicates how the color will be codified for the pixels. There
are several possible ways to codify colors, but we use that employed by the screen
image. So, we used
.CW screen->chan
.ix "image chan
as an argument. The last parameter is the value that states which one is the code
for the color. Given both
.CW chan
and the number for the color,
.CW allocimage
can specify to the draw device which color is going to use the pixels in the new image.
.PP
In our program, we used the constant
.CW DYellow
.ix [DYellow]
for the color of the set part, and the number
.CW 0x777777FF
for the unset part. This number codifies a color by giving values for red, blue,
and green. We borrowed the constant by looking at the source code for \f(CWrio\fP, to use
exactly its background color.
.PP
At last, this is
.CW drawslider .
.P1
void
drawslider(int val)
{
Rectangle setrect, unsetrect, markrect;
int dx;
dx = Dx(screen->r) * val / 100;
setrect = unsetrect = markrect = screen->r;
setrect.max.x = setrect.min.x + dx;
markrect.min.x = setrect.max.x;
markrect.max.x = setrect.max.x + 2;
unsetrect.min.x = markrect.max.x;
draw(screen, setrect, setcol, nil, ZP);
draw(screen, unsetrect, unsetcol, nil, ZP);
draw(screen, markrect, display->black, nil, ZP);
flushimage(display, 1);
}
.P2
.LP
If the value represented by the slider is
.I val ,
in the range [0,100],
and our window is
.I Dx
.ix [Dx]
.ix "rectangle width
pixels wide, then, the offset for the
.I x
coordinate in the window that corresponds to
.I val
is defined by
.EQ
x = Dx times val over 100
.EN
.LP
A zero value would be a zero offset. A 100 value would mean a
.I Dx
offset. The function
.CW Dx
returns the width of a rectangle
(there is also a
.CW Dy
.ix [Dy]
.ix "rectangle height
function that returns its height). So,
.P1
dx = Dx(screen->r) * val / 100;
.P2
.LP
computes the offset along the
.I x
axis that corresponds to the value for the slider.
Once we know
.CW dx ,
defining the rectangle for
.CW setrect
is straightforward. We take initially the rectangle for the window
and change the
.CW max.x
coordinate to cut the rectangle at the offset
.CW dx
in the window. The
.CW markrect
is initialized in the same way, but occupies just the next two pixels on the
.I x
axis, past
.CW setrect .
The rectangle
.CW unsetrect
goes from that point to the end of the
.I x
axis.
.ix axis
.PP
What remains to be done is to change
.CW mousethread
to let the user adjust the slider using the mouse.
.ix "mouse button-1
.ix "click
The idea is that holding down the button 1 and moving it will change the
slider to the point under the mouse.
.P1
.ps -1
void
mousethread(void* arg)
{
Mousectl*mctl = arg;
Mouse m;
int dx, val;
.ps +1
.P2
.P1
.ps -1
for(;;){
recv(mctl->c, &m);
if(m.buttons == 1){
do {
dx = m.xy.x - screen->r.min.x;
val = dx * 100 / Dx(screen->r);
sendul(sliderc, val);
recv(mctl->c, &m);
} while(m.buttons == 1);
}
}
}
.ps +1
.P2
.LP
Executing the program, moving the slider, and pressing
.I Delete
to kill it, leads to this output.
.P1
; 8.slider > /tmp/values
\fBDelete\fP
; cat /tmp/values
50
32
30
.I ...
.P2
.LP
Usually, the output for the program will be the input for an application requiring
a user adjustable value. For example, the following uses the slider to adjust
the volume level for the sound card in the terminal.
.P1
; 8.out | while(v=`{read}) echo audio out $v >>/dev/volume
.I "Changing the slider changes the volume level...
.P2
.BS 2 "Keyboard input
.LP
.ix "keyboard input
Using
.I Delete
to terminate the program is rather unpolite. The program might understand
a few keyboard commands. Typing
.CW q
might terminate the slider. Typing two decimal digits might set the slider to
the corresponding value. The library
.I keyboard (2)
.ix "keyboard library
is similar to
.I mouse (2),
but provides keyboard input instead of mouse input. Using it may fix another
problem that we had with the slider. The program kept the console
in cooked mode. Typing characters in the slider window will make the console
device (provided by \f(CWrio\fP) echo them. That was ugly.
.PP
To process the keyboard, one character at a time, hence putting the console
in raw mode, the main function may call
.CW initkeyboard .
.ix [initkeyboard]
.ix "keyboard initialization
.P1
; sig initkeyboard
Keyboardctl *initkeyboard(char *file)
.P2
.LP
This function opens the console file given as an argument, and creates
a process that reads characters from it. The console is put in raw mode by
assuming that if the file is named
.CW /a/cons/file ,
there will be another file named
.CW /a/cons/filectl
that accepts a
.CW rawon
.ix [rawon]
command. So, giving
.CW /dev/cons
as an argument will mean that
.CW rawon
is written to
.CW /dev/consctl
(and the file is kept open).
.PP
The function returns a pointer to a
.CW Keyboardctl
.ix [Keyboardctl]
structure, similar to a
.CW Mousectl .
It contains a channel where the I/O process sends runes (not characters!)
as they are received.
.P1
typedef struct Keyboardctl Keyboardctl;
struct Keyboardctl
{
Channel *c; /* chan(Rune)[20] */
\fI...\fP
};
.P2
.LP
Like we did for the mouse, to process the keyboard input, we will change
.CW threadmain
to call
.CW initkeyboard
and to create a separate thread for processing keyboard input. This is the
resulting code for the program, omitting the various functions that we have
seen, and a couple of other ones that are shown later.
.so progs/slider.c.ms
.ix [slider.c]
.LP
The function
.CW keyboardthread
.ix [keyboardthread]
is executed on its own thread. It receives runes
from
.CW kctl.c
and processes them without paying much attention to the rest
of the program.
.P1
.ps -2
void
keyboardthread(void* a)
{
Keyboardctl*kctl = a;
Rune r,rr;
int nval;
for(;;){
recv(kctl->c, &r);
switch(r){
case Kdel:
case Kesc:
case 'q':
terminate();
break;
.ps +2
.P2
.P1
.ps -2
default:
if (utfrune("0123456789", r) != nil){
recv(kctl->c, &rr);
if (utfrune("0123456789", rr) != nil){
nval = (r-'0')*10 + (rr-'0');
sendul(sliderc, nval);
}
}
}
}
}
.ps +2
.P2
.LP
The constants
.CW Kdel
and
.CW Kesc
are defined in
.CW keyboard.h
with the codes for the
.I Delete
and the
.I Escape
runes. We terminate the program when either key is pressed, or when a
.CW q
is typed. Otherwise, if the rune received from
.CW kctl->c
is a digit, we try to obtain another digit to build a slider value and send it
through
.CW sliderc .
.PP
To terminate the program, we must now call
.CW closekeyboard ,
.ix [closekeyboard]
which releases the
.CW Keyboardctl
structure and puts the console back in cooked mode. So, both control
structures were kept as globals in this version for the program. The next function
does all the final cleanup.
.P1
void
terminate(void)
{
closekeyboard(kctl);
closemouse(mctl);
closedisplay(display);
threadexitsall(nil);
}
.P2
.BS 2 "Drawing text
.LP
.ix "drawing text
With all the examples above it should be clear how to use the abstractions
for using the devices related to graphical user interfaces. Looking through the
manual pages to locate functions (and other abstractions) not described here
should not be hard after going this far.
.PP
Nevertheless, it is instructive to see how programs can write text. For example,
the implementation for the console in \f(CWrio\fP writes text. Both because the echo and
because of writes to the
.CW /dev/cons
file. But can this be on a graphic terminal?
.PP
There are many convenience functions in
.I draw (2)
.ix "drawing functions
to draw lines, polygons, arcs, etc. One of them is
.CW string ,
.ix [string]
.ix "draw string
which can be used to
.I draw
a string. Note: not to
.I write
a string.
.P1
.ps -2
; sig string
Point string(Image *dst, Point p,
Image *src, Point sp, Font *f, char *s)
.ps +2
.P2
.LP
Suppose that we want to modify the slider program to write the slider value using
text, near the left border of the slider window. This could be done by adding a line
to
.CW sliderthread ,
similar to this one
.P1
string(screen, pos, display->black, ZP, font, "68");
.P2
.LP
This draws the characters in the string
.CW "68"
on the image
.CW screen
(the destination image). The point
.CW pos
is the pixel where drawing starts. Each character is a small rectangular image.
The image for the first character has its top-left corner placed
at
.CW pos ,
and other characters follow to the right. The source image is
.I not
the image for the characters. The source image is the one for the black
color in this example. Character images are used as masks, so that black pixels
are drawn where each character shape determines that there has to be a pixel
drawn. To say it in another way, the source image is the one providing the pixels
for the drawing (e.g., the color). Characters decide just which pixels to draw.
The point given as
.CW ZP
is used to translate the image used as a source, like when calling
.CW draw .
Here, drawing characters in a solid color,
.CW ZP
.ix [ZP]
works just fine.
.PP
But where are the images for the characters? Even if they are used as masks,
there has to be images for them. Which images to use is determined by the
.CW Font
.ix [Font]
parameter.
.PP
A
.B font
is just a series of pictures (or other graphical descriptions) for runes or characters.
There are many fonts, and each one includes a lot of images for characters.
Images for font runes are kept in files under
.CW /lib/font .
Many files there include images just for a certain contiguous range of runes
(e.g., letters, numbers, symbols, etc.)
Other files, conventionally with names ending in
.CW .font ,
describe which ones of the former files are used by a font for certain ranges of unicode
values.
.PP
The
.I draw
library provides a data type representing a font, called
.CW Font .
It includes functions like
.P1
Font* openfont(Display *d, char *file)
.P2
.ix [openfont]
.ix "font file
.LP
that reads a font description from the file given as an argument and
returns a pointer to a
.CW Font
that may be used to employ that font.
.PP
To use a loaded font, it suffices to give it as an argument to functions like
.CW string .
We used
.CW font ,
which is a global for the font used by default. To see which font you are using by default,
you may see which file name is in the
.CW $font
.ix [$font]
environment variable.
.P1
; echo $font
/lib/font/bit/VeraMono/VeraMono.12.font
.P2
.LP
That variable is used to locate the font you want to use. The window system supplies a
reasonable default otherwise.
.PP
The following function, that may be called from
.CW sliderthread ,
draws the slider value (given as a parameter) in the window.
.P1
.ps -1
void
writeval(int val)
{
Point sz, pos;
char str[5]; // "0%" to "100%"
seprint(str, str+5, "%d%%", val);
sz = stringsize(font, str);
if (sz.x > Dx(screen->r)/2 || sz.y > Dy(screen->r))
return;
pos = screen->r.min;
pos.x += 10;
pos.y += (Dy(screen->r)- sz.y) / 2;
string(screen, pos, display->black, ZP, font, str);
}
.ps +1
.P2
.LP
It prints the integer value as a string, in
.CW str .
adding a
.CW %
sign after the number.
The window could be so small (or perhaps the font so big) that there could be
not enough space to draw the text. The function
.CW stringsize
.ix [stringsize]
returns the size for a string in the given font. We use it to know how much
screen space will the string need. To avoid making our window too bizarre,
.CW writeval
does not draw anything when the window is not as tall as the
height for the string, that is, when
.CW "sz.y > Dy(screen->r)" .
Also, the string is not shown either when it needs more than the half of the
width available in the window.
.BS 2 "The window system
.LP
.ix "window system
.ix [rio]
.ix terminal
.ix console
A
.B window
is an abstraction provided by the window system,
.CW rio
in this case.
It mimics the behavior of a graphic terminal, including its own mouse and
keyboard input, and both text and graphics output.
.PP
In other systems, the abstraction used for windows differs from the one used for
the entire console. Programs must be aware of the window system, and use its
programming interface to create, destroy, and operate windows.
.PP
Instead, the model used in Plan 9 is that each application uses the console,
understood as the terminal devices used to talk to the user, including
the draw device and the mouse. In this way, applications
may be kept unaware of where are they actually running (the console or a window).
Running the window system in a window is also a natural consequence of this.
.PP
.ix "console multiplexing
Nevertheless, it may be useful to know how to use the window system from a program.
Like other services, the window system is also a file server. You already know that
its primary task is to multiplex the files for the underlying console and mouse to provide
virtual ones, one per window. Such files are the interface for using the window, like
the real ones are the interface for using the real console.
.PP
Each time the
.CW rio
.ix "[rio] file~system
.ix "window creation
.ix "attach specifier
file system is mounted, it creates a new window. The attach specifier (the optional
file tree name given to mount) must be
.CW new ,
possibly followed by some flags for the newly created window.
.CW Rio
posts at a file in
.CW /srv
.ix [/srv]
a file descriptor that can be used to mount it. The name for this file is kept at
the environment variable
.CW $wsys .
.ix [$wsys]
Therefore, these commands create a new window.
.P1
; echo $wsys
/srv/rio.nemo.557
; mount $wsys /n/rio new
.P2
.LP
After doing this, the screen might look like the one shown in figure [[!mounting rio!]],
where the empty window is the one that has just been created. Which files are
provided by \f(CWrio\fP? We are going to use the window were we executed the previous
commands to experiment at little bit.
.LS
.BP newwindow.ps
.LE F Mounting rio creates a new window. In this one, no shell is running.
.P1
; lc /n/rio
cons kbdin screen wctl winid
consctl label snarf wdir winname
cursor mouse text window wsys
.P2
.LP
We see
.CW cons ,
.CW consctl ,
.CW cursor ,
and
.ix [/dev/cons]
.ix [/dev/consctl]
.ix [/dev/cursor]
.ix [/dev/mouse]
.CW mouse ,
among others. They are virtual versions for the ones that were mounted at
.CW /dev
prior to running rio. The convention in Plan 9 is to mount the window system files
at
.CW /mnt/wsys ,
.ix [/mnt/wsys]
and not at
.CW /n/rio .
We use
.CW /n/rio
just to make it clear that these files come from the file tree that we have mounted.
In your system, you may browse
.CW /mnt/wsys
and you will see a file tree with same aspect.
.PP
Binding
.CW /n/rio
(before other files) at
.CW /dev
will make any new process in our window to use not this window, but the new
one that we have created. So, these commands
.P1
; bind -b /n/rio /dev
; stats
.P2
.LP
cause
.CW stats
.ix [stats]
.ix "alternate window
.ix "new window
to use the new window instead of the one we had, like shown in figure
[[!Binding new window!]]. For
.CW stats ,
using the screen, mouse, and keyboard is just a matter of opening files at
.CW /dev .
It does not really care about where do the files come from. Regarding
.CW /dev/draw ,
that device multiplexes by its own means among multiple processes (each one
keeps a separate connection to the device, as we saw). The other files
are provided by \f(CWrio\fP.
.LS
.BP statswindow.ps
.LE F Binding the files for the new window at \f(CW/dev\fP makes \f(CWstats\fP use it.
.PP
Hitting
.I Delete
in the new window will not kill
.CW stats .
The window system does not know where to post the
.I interrupt
.ix "[interrupt] note
note for that window. To interrupt the program, we must hit
.I Delete
.ix [Delete]
in the old window, where the command was running. This can be fixed.
Unmounting the files for the new \f(CWrio\fP window will destroy it (nobody would be using
it).
.P1
; unmount /n/rio /dev
; unmount /n/rio \fRand the window goes away\fP
.P2
.LP
And now we mount \f(CWrio\fP again (creating another window). This time, we use the
option
.CW -pid
within the attach specifier to let \f(CWrio\fP know that notes for this window should go
the process group for the process with pid
.CW $pid .
.ix "window pid
That is, to our shell. Afterwards, we start
.CW stats
like before.
.P1
; mount $wsys /n/rio 'new -pid '$pid
; bind -b /n/rio /dev
; stats \fRIt uses the new window\fP
; \fRUntil hitting \fP\fBDelete\fP\fR in that window\fP
.P2
.LP
This time, hitting
.I Delete
in either window will stop
.CW stats .
The new window has been instructed to post the note to the note process group
of our shell. It will do so. Our old window, of course, does the same.
.PP
In almost all the cases, the
.CW window
command (a script) is used to create new windows. It creates a new window
like we have done. Most of its arguments are given to \f(CWrio\fP to let it know where
to place the window and which pid to use to deliver notes.
.CW Window
.ix [window]
accepts as an argument the command to run in the new window, which is
.CW /bin/rc
by default. For example,
.P1
; window -r 0 0 90 100 stats
.P2
.LP
creates a new window in the rectangle going from the point (0,0) to the point
(90,100). It will run
.CW stats .
There is a C library,
.I window (2),
.ix "[window] library
that provides a C interface for creating windows (among other things related
to windows). The window system and the graphics library may use it,
but it is not likely you
will ever need to use it from your programs. Your programs are expected to
use their “console”, whatever that might be.
.PP
Going back to the files served by \f(CWrio\fP,
the files
.CW winid
and
.CW winname
.ix [/dev/winid]
.ix [/dev/winname]
contain strings that identify the window used. You can see them for the new
window at
.CW /n/rio .
And because of the (customary) bind of these files at
.CW /dev ,
you will always see them at
.CW /dev/winid
and
.CW /dev/winname .
In what follows, we will use file names at
.CW /dev ,
but it should be clear that they are provided by \f(CWrio\fP.
.P1
; cat /dev/winid
3 ; \fInewline supplied by us\fP
; cat /dev/winname
window.3.3; ; \fInewline supplied by us\fP
.P2
.LP
The window id, kept at
.CW winid ,
is a number that identifies the window. The directory
.CW /dev/wsys
.ix [/dev/wsys]
contains one directory per window, named after its identifier.
In our case, \f(CWrio\fP is running just
two windows.
.P1
; lc /dev/wsys
1 3
; lc /dev/wsys/3
cons kbdin screen wctl winid
consctl label snarf wdir winname
cursor mouse text window wsys
.P2
.LP
Each window directory contains all the files we are accustomed to expect for
using the console and related devices. For each window,
.CW rio
makes its files
also available in its root directory, so that a bind of the
.CW rio
file system at
.CW /dev
will leave the appropriate files in
.CW /dev ,
and not just in
.CW /dev/wsys/3
or a similar directory.
.PP
The file
.CW winname
contains the name for the image in the draw device that is used as the screen
for the window. The draw device may keep names for images, and the window
system relies on this to coordinate with programs using windows. Rio creates
the image for each window, and gives a name to it that is kept also in
.CW winname .
The function
.CW getwindow ,
.ix [getwindow]
.ix [screen]
called by
.CW initdraw ,
uses this name to locate the image used for the window. That is how your
graphic programs know which images are to be used as their
.CW screens .
.PP
The file
.CW label
.ix [/dev/label]
.ix "window label
contains a text string for labeling the window. That is, the file
.CW /dev/label
for the current window, or
.CW /dev/wsys/3/label
for the window with identifier 3,
contain strings to let us know which program is using which window.
.P1
; cat /dev/label
rc 839;
; cat /dev/wsys/3/label
stats;
.P2
.LP
A convenience script,
.CW wloc ,
lists all the windows along with their labels.
.P1
; wloc
window -r 125 32 576 315 rc 839 # /dev/wsys/1
window -r 69 6 381 174 stats # /dev/wsys/3
;
.P2
.LP
Basically, it lists
.CW /dev/wsys
to see which windows exist, and reads
.CW /dev/label
for each one, to describe it. The following command would do something
similar.
.P1
; for (w in /dev/wsys/*)
;; echo window `{cat $w/label}
window rc 839
window stats
.P2
.LP
Other useful files are
.CW /dev/screen ,
.CW /dev/window ,
and
.CW /dev/text .
.ix "/dev/text
.ix "window text
They are provided for each window. The first one is an image for the entire
screen. It can be used to take a snapshot for it. The second one is the same,
but only for the window image. The last one contains all the text shown in the window
(although it is read-only). For example, this can be used to see the first three lines
in the current window.
.P1
; sed 3q /dev/text
;\ echo $wsys
/srv/rio.nemo.832
;\ mount $wsys /n/rio new
;
.P2
.LP
Note that we only typed the first one. The next command prints all the
.CW mount
commands that we executed in our window, assuming the prompt is the one
used in this book.
.P1
; grep '^; mount' /dev/text
;\ mount $wsys /n/rio new
.P2
.LP
In the same way, this executes the first
.CW mount
command that we executed in our window
.P1
; grep '^; mount' /dev/text | sed 1q | rc
.P2
.LP
Each window provides a control interface, through its
.CW wctl
.ix "[rio] menu
file. Many of the operations that can be performed by the user, using the
mouse and the menus provided by \f(CWrio\fP, can be performed through this file as well.
.PP
Windows may be hidden, to put them apart without occupying screen space
while they are not necessary by the moment. The
.I Hide
command from button-3 menu in \f(CWrio\fP hides a window. While hidden, the window label
is shown in that menu, and selecting it shows the window again. The next command
line
hides the window for 3 seconds using its control file.
.P1
; echo hide >/dev/wctl ; sleep 3 ; echo unhide >/dev/wctl
.I "hidden for 3 seconds... and back again!
;
.P2
.LP
.ix "window hide
We typed the three commands in the same line because after
.P1
; echo hide >/dev/wctl
.P2
.LP
the window would no longer be visible to accept input. This remains of the
.B "input focus" .
The window where you did click last is the one receiving keyboard input and mouse
input. The place where the window system sends input events is also known as the
.I focus
because you seem to be focusing on that window. Manually, focus can be changed
by using the mouse to click on a different window. From a program, the
.CW wctl
file can be used.
.P1
; echo current >/dev/wsys/3/ctl
.P2
.LP
Sets the focus to window
.CW 3 .
It is also said that window
.CW 3
becomes the
.I current
.ix "current window
window, hence the control command name. By the way, most of the control
operations done to a
.CW wctl
file make its window current. Only the
.CW top
and
.CW bottom
.ix "top window
.ix "bottom window
commands do not affect the focus.
.PP
.ix "window overlap
Windows may overlap. The window system maintains a stack of windows. Those
down in the stack are in the back, and may be obscured by windows more close
to the top of the stack (which are up front).
You
may reclaim a window to the top of the stack to make it fully visible. With the mouse,
a click on the window suffices. From a program, you can move it to the top easily.
.P1
; echo top >/dev/wsys/3/ctl
.P2
.LP
And also to the back, something that you cannot do directly using the mouse.
.P1
; echo bottom >/dev/wsys/3/ctl
.P2
.LP
By now, you know that windows may scroll down automatically or not, depending
on their scroll status, as selected by the
.ix "scroll mode
.I Scroll
and
.I Noscroll
options from their button-2 menu. This is how to do it through the control file,
this time, for window
.CW 3 .
.P1
; echo scroll >/dev/wsys/3/wctl \fRputs the window 3 in scroll mode\fP
; echo noscroll >/dev/wsys/3/wctl
;
.P2
.LP
There are several other control commands described in the
.I rio (4)
manual page, including some that might seem to be available only when
using the mouse to perform them manually. The next command resizes a window
to be just 100 pixels wide.
.ix "window resize
.P1
; echo 'resize -dx 100' >/dev/wctl \fRmake it 100 pixels wide\fP
.P2
.LP
It is not important to remember all the commands accepted, but it is to know
that they can be used to automate things that would have to be done manually
otherwise. Tired of manually adjusting a window, after running acme, to use most
available screen space? Just write a shell script for the task.
.PP
The first thing to be
done by the script is to determine how much space is available at our terminal.
This was recorded in
.CW $vgasize .
.ix [$vgasize]
.ix "screen size
Later, we can define variables for the width and height (in pixels) that we might use.
.P1
; echo $vgasize
1280x800x24
; wid=`{echo $vgasize | sed 's/x.*//'}
; echo $wid
1280
; ht=`{echo $vgasize | sed 's/.*x(.*)x.*/\1/'}
; echo $ht
800
.P2
.LP
Because most of the times we want some space to use \f(CWrio\fP (e.g., to recall
its menus), we may save 90 pixels from the height. To keep an horizontal
row with 90 pixels of height just for other \f(CWrio\fP windows and menus.
.P1
; ht=`{echo $ht - 90 | hoc}
; echo $ht
710
.P2
.LP
.ix "automatic layout
.ix "screen layout
And now, we can resize the window, placing it in the rectangle computed for our
screen.
.P1
echo resize -r 0 0 $wid $ht >/dev/wctl
.P2
.LP
The arguments for the
.CW move
and
.CW resize
commands (understood by the
.CW wctl
file) are similar to those of the
.CW window
command.
.PP
If in the future you find yourself multiple times carefully adjusting windows to
a particular layout that is easy to compute, you know what to do.
.SH
Problems
.IP 1
Record mouse events and try to reproduce them later.
.IP 2
Use the window system to provide virtual desktops. You do not need to implement
anything to answer this problem.
.IP 3
Write a program that implements console cooked mode by itself.
It must write to standard output one line at a time, but it must use raw mode.
.IP 4
Write a program that draws the pixels under the mouse while a button
is pressed.
.IP 5
Make the program draw text when a key is pressed. The text to draw is
the character typed and the position would be the last position given by
the mouse
.IP 6
There is an alternate library, called
.CW event
that provides event-driven mouse and keyboard processing. Implement
the previous programs using this library. Compare.
.IP 7
The
.CW /dev/kbmap
file provides keyboard maps. Look through the manual and try to change the map.
Locate one defining several keyboard keys as mouse buttons.
.ds CH
.bp
\c