microwindows_architecture.html

Nano-x的设计架及相关文档----这是网上下载的中文翻译版本, E文的可以在其网站上下载.

graphics engine, which calls the screen, mouse and keyboard drivers to interface with the
hardware.  User applications programs never all the core graphics engine routines
directly, but rather through the programmer API's, discussed in the next sections. 
The core engine routines are separated from the applications API's is for a variety of
reasons.  The core routines will always reside on the server in a client/server
environment.  Also, the core routines use internal text font and bitmap formats that
are designed for speed and may or may not be the same as the structures used in standard
API's.  In addition, the core routines always use pointers, never ID's, and can then
be used together to implement more complex functions without always converting handles,
etc.</p>

<p>In Microwindows, the core routines all begin as GdXXX() functions, and are concerned
with graphics output, not window management.&nbsp; In addition, all clipping and color
conversion is handled within this layer.&nbsp; The following files comprise the core
modules of Microwindows:</p>

<p>&nbsp;&nbsp;&nbsp; devdraw.c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Core graphics
routines for line, circle, polygon draw and fill, text and bitmap drawing, color
conversion</p>

<p>&nbsp;&nbsp;&nbsp; devclip.c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Core
clipping routines.&nbsp; (devclip2.c is the new y-x-banding algorithm, devclip1.c an older
method)</p>

<p>&nbsp;&nbsp;&nbsp; devrgn.c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
New dynamically allocated routines for intersect/union/subtract/xor region creation.</p>

<p>&nbsp;&nbsp;&nbsp; devmouse.c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Core routines for keeping
the mouse pointer updated or clipped from the screen.</p>

<p>&nbsp;&nbsp;&nbsp; devkbd.c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Core
keyboard handling routines.</p>

<p>&nbsp;&nbsp;&nbsp; devpalX.c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Linked in
static palettes for 1, 2, 4 and 8bpp palletized systems.</p>

<p>Section 2 following discusses the MicroGUI graphics engine routines in detail.</p>

<h3>1.4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Applications Programmer Interfaces</h3>

<p>Microwindows currently supports two different application programming interfaces.&nbsp;
This set of routines handles client/server activity, window manager activities like
drawing title bars, close boxes, etc, as well as, of course, handling the programmer's
requests for graphics output.&nbsp; Both the API's run on top of the core graphics engine
routines and device drivers. </p>

<p>The basic model of any API on top of Microwindows is to hang in initialize the screen,
keyboard and mouse drivers, then hang in a select() loop waiting for an event.&nbsp; When
an event occurs, if it's a system event like keyboard or mouse activity, then this
information is passed to the user program converted to an expose event, paint message,
etc.&nbsp; If it's a user requesting a graphics operation, then the parameters are decoded
and passed to the appropriate GdXXX engine routine.&nbsp; Note that the concept of a
window versus raw graphics operations are handled at this API level.&nbsp; That is, the
API defines the concepts of what a window is, what the coordinate systems are, etc, and
then the coordinates are all converted to &quot;screen coordinates&quot; and passed to the
core GdXXX engine routines to do the real work.&nbsp; This level also defines graphics or
display contexts and passes that information, including clipping information, to the core
engine routines.</p>

<p>Currently, the Microwindows API code is in win*.c, while the Nano-X API code is in
nanox/srv*.c.</p>

<h3>1.4.1&nbsp;&nbsp;&nbsp; Microwindows API</h3>

<p>The Microwindows API tries to be compliant with the European ECMA APIW standard.&nbsp;
Currently, there is support for most of the graphics drawing and clipping routines, as
well as automatic window title bar drawing and dragging windows for movement. The
Microwindows API is message-based, and allows programs to be written without regard to the
eventual window management policies implemented by the system.&nbsp; The Microwindows API
is not currently client/server, and will be discussed in more detail in section 4.</p>

<h3>1.4.2&nbsp;&nbsp;&nbsp; Nano-X API</h3>

<p>The Nano-X API is modeled after the mini-x server written initially by David Bell,
which was a reimplementation of X on the MINIX operating system.&nbsp; It loosely follows
the X Window System Xlib API, but the names all being with GrXXX() rather than
X...().&nbsp; Currently, the Nano-X API is client/server, but does not have any provisions
for automatic window dressings, title bars, or user window moves.&nbsp; There are several
groups writing widget sets currently, which will provide such things.&nbsp; Unfortunately,
the user programs must also then write only to a specific widget set API, rather than
using the Nano-X API directly, which means that only the functionality provided by the
widget set will be upwardly available to the applications programmer.&nbsp; (Although this
could be considerable, in the case that, say Gdk was ported.)</p>

<h3>2. Device-Independent Engine Features</h3>

<p>This section discusses in the capabilities and implementation of Microwindows' core
graphics engine in detail.&nbsp; It's purpose is both educational and to allow extending
an API by understanding how the engine works.</p>

<h3>&nbsp;&nbsp;&nbsp; 2.1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Graphics Engine
Features and Implementation</h3>

<p>These routines concern themselves with drawing operations to off-screen or screen
surfaces.&nbsp; Each routine starts with Gd... and is passed a pointer to the SCREENDEVICE
structure (PSD) as it's first parameter.&nbsp; The PSD parameter specifies the low level
display details, like the x, y size of the device and the color model used by the
hardware, for example.&nbsp; In addition, the actual routines to perform drawing are
function pointers in this structure.&nbsp; All screen coordinates are of type COORD, and
specified in device coordinates, that is, offsets from the upper left corner of the
screen.</p>

<p>Colors are always specified as an RGB COLORVAL value into the graphics engine.&nbsp;
They are then possibly converted to palette indices and sent to the display hardware as
PIXELVAL values.&nbsp; In the case of 32bpp truecolor displays, no conversion is
required.&nbsp; The color model will be discussed in detail below.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.1&nbsp;&nbsp;&nbsp; Regions</h3>

<p>Regions are used to describe arbitrary sets of pixels on the screen.&nbsp; A simple,
square region of pixels can be described by a single rectangle.&nbsp; More complex sets of
pixels require more complex data structures.&nbsp; In Microwindows, regions are described
by an array of non-overlapping rectangles.&nbsp; Currently, there are two different
implementations of regions in Microwindows, as I've been enhancing the capabilities in
this area.&nbsp; The original design used a single static array of CLIPRECTs to describe
complex regions.&nbsp; Any point within any rectangle in the array was considered to be in
the region.&nbsp; The array wasn't sorted in any particular order, but was always
guaranteed to contain non-overlapping rectangles.&nbsp; Another global variable,
clipcount, specified the number of rectangles in the array.&nbsp; This original design had
no engine entry points for region management, the entire array was passed to the clipping
functions, described below. </p>

<p>In the new design, any number of regions can be created, as the regions (CLIPREGION *)
are stored as dynamically allocated arrays of rectangles.&nbsp; In this implementation,
the non-overlapping rectangles are always kept in &quot;y-x&quot; sorted bands, such that
each band's y height is the same for all rectangles in the band.&nbsp; This means that
only the x position and width of the rectangles in each band varied.&nbsp; Because of
this, it is easier to create a set of functions for combining regions, since effectively
only a single dimension had to be compared for each region operation.&nbsp; The new region
handling routines allow for creating and destroying regions, as well as combining
rectangles and regions with regions using Intersection, Union, Subtraction, and Exclusive
Or.&nbsp; This model allows regions to be implemented apart from the clipping routines,
unlike the first version.&nbsp; Following are the new region routines:</p>

<p>&nbsp;&nbsp;&nbsp;
GdAllocRegion&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
- Create a region<br>
&nbsp;&nbsp;&nbsp;
GdDestroyRegion&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
- Destroy a region<br>
&nbsp;&nbsp;&nbsp;
GdCopyRegion&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
- Copy a region<br>
&nbsp;&nbsp;&nbsp; GdUnionRectWithRegion&nbsp;&nbsp;&nbsp;&nbsp; - Union a rectangle with
a region<br>
&nbsp;&nbsp;&nbsp;
GdIntersectRegion&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
- Create a region from the intersection of two regions<br>
&nbsp;&nbsp;&nbsp;
GdSubtractRegion&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
- Create a region from the difference of two regions<br>
&nbsp;&nbsp;&nbsp;
GdUnionRegion&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
- Create a region from the union of two regions<br>
&nbsp;&nbsp;&nbsp;
GdXorRegion&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
- Create a region from the XOR of two regions<br>
&nbsp;&nbsp;&nbsp; </p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.2&nbsp;&nbsp;&nbsp; Clipping</h3>

<p>Clipping in Microwindows is closely tied to the region management code.&nbsp; At any
point in time, the graphics engine has a single clipping region, that is a set of
rectangles, defined for any graphics operation.&nbsp; A point is drawn if it is
&quot;inside&quot; any of the current set of clip rectangles.&nbsp; Two slightly modified
versions of the clipping algorithm are supplied, devclip1.c for the original, static
rectangle array, and devclip2.c for the newer dynamically allocated array.&nbsp; A single
entry point GdSetClipRects, takes the passed region and specifies it's use for all
subsequent graphics operations.&nbsp; All the drawing routines then use the two additional
routines to determine whether or not to draw.&nbsp; GdClipPoint takes an x,y point in
screen coordinates and returns TRUE if the point can be drawn, that is, the point is
within one of the region rectangles.&nbsp; GdClipArea takes an upper left and lower right
point, and returns one of the following: CLIP_VISIBLE, if the specified area is completely
within the region, CLIP_INVISIBLE, if the area is completely not in the region, which
means that no drawing should be performed, or CLIP_PARTIAL, if a part but not the whole
area is within the region.&nbsp; A typical graphics primitive will call the screen driver
with unmodified passed inputs if CLIP_VISIBLE is returned, or return if CLIP_INIVISIBLE is
returned.&nbsp; In the CLIP_PARTIAL case, the primitive must break up the original request
into areas that are within the clip region before calling the screen driver.&nbsp; This
slows down the operation considerably.</p>

<p>Because the clipping code is called constantly before drawing operations, Microwindows
keeps a global cache rectangle of the last rectangle checked with GdClipArea, for speed
and also to allow the mid level to quickly calculate how partial drawing lengths.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.3&nbsp;&nbsp;&nbsp; Line Drawing</h3>

<p>Line drawing is the simplest of graphics operations.&nbsp; Microwindows supports
GdPoint to draw a point, and GdLine to draw a horizontal, vertical or diagonal (using
Bresenham algorithm) line.&nbsp; Just before any call to the screen driver, a call to
GdCheckCursor assures that the software cursor is removed prior to drawing.&nbsp;
GdFixCursor restores the cursor if previously visible.</p>

<p>There is a tricky part to line drawing that had to be added during the support for
multiple API's.&nbsp; This has to do with whether or not the last point in specified line
segment is drawn or not.&nbsp; There are two schools of thought on this, and to make it
short, Microwindows supports both of them.&nbsp; The last parameter to GdLine specifies
whether or not to draw the last point.&nbsp; The Microwindows API doesn't draw the last
point, but the Nano-X API does.</p>

<p>Most drawing functions, including line drawing draw using the &quot;current&quot;
foreground color, specified using GdSetForeground.&nbsp; In addition a drawing mode,
currently either MODE_SET or MODE_XOR can be specified using GdSetMode.</p>