microwindows_architecture.html

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

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.4&nbsp;&nbsp;&nbsp; Rectangles,
Circles, Ellipses</h3>

<p>Rectangles, circles and ellipses are drawn using the GdRect and GdEllipse
routines.&nbsp; A circle is an ellipse with the same x and y radius.&nbsp; As with lines,
rectangles and ellipses are drawn using the current foreground color and mode.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.5&nbsp;&nbsp;&nbsp; Polygons</h3>

<p>Microwindows supports polygon drawing by specifying an array of x, y points.&nbsp; The
points are then connected using the GdLine function.&nbsp; The current foreground color,
drawing mode, and clip region is used during output.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.6&nbsp;&nbsp;&nbsp; Area Fills</h3>

<p>Microwindows supports filled rectangular areas using the GdFillRect function.&nbsp; The
rectangle's outline and contents are filled using the current foreground color.&nbsp;
Filled circles and ellipses are performed with GdFillEllipse, and polygon fills with
GdFillPoly.&nbsp; Area filling is implemented through successive calls to the DrawHorzLine
in the screen driver, and are much faster if fully not clipped.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.7&nbsp;&nbsp;&nbsp; Fonts</h3>

<p>Both fixed pitch and proportional fonts are supported in Microwindows.&nbsp; Because of
potentially large differences in display hardware, the actual font format is known only to
the screen driver, although a set of standard functions are supplied for dealing with
converted .bdf fonts and Microsoft Windows fonts, if you have a license.&nbsp; The engine
function GdSetFont specifies a font number that is passed to the driver and used to index
a static array of linked in fonts.&nbsp; Screen driver entry points GetTextSize return the
font height and width for a passed string, and GetTextBits returns an individual character
bitmap.&nbsp; The engine layer uses these values to calculate a clipping region for text
drawing, as well as to draw the character as a monochrome bitmap.</p>

<p>The screen drivers currently supplied implement both fixed pitch PC ROM based fonts, as
well as a proportional font format that is linked into the screen driver.&nbsp; A few
conversion programs allow conversion of fonts from different formats to the driver
format.&nbsp; Bdftobogl converts X Window System .bdf files to Microwindows format.&nbsp;
Convfnt32 converts raster and truetype Microsoft Windows fonts, if you have a license, to
Microwindows format.&nbsp; Convrom converts PC ROM bios fonts.</p>

<p>A number of free fonts are supplied with the system, a heavier proportional 14x16
system font, and a sans-serif 11x13 font for title bar and edit box displays.&nbsp; Any
number of fonts can be linked into the system, and it's fairly easy to dynamically load
fonts if one writes the routines for it.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.8&nbsp;&nbsp;&nbsp; Text Drawing</h3>

<p>Text output is performed by first selecting the desired font with GdSetFont, and then
calling the GdText function.&nbsp; Full text clipping is performed, although currently
there is no &quot;fast&quot; text output entry point in the screen driver, so each
character bitmap is grabbed using the GetTextBits entrypoint and then drawn using
Drawpixel.&nbsp; While this will have to remain the same for partially clipped text, a
screen driver entry point to draw fast text will probably be required shortly.</p>

<p>Text is drawn using the current foreground color.&nbsp; The background is drawn if the
current &quot;use background&quot; mode set via GdUseBackground is TRUE.&nbsp; In this
case the background is drawn using the current background color set via
GdSetBackground.&nbsp; The GdText function also takes a bottomAlign parameter that
specifies whether the text is to be bottom or top aligned, to help with differing API's.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.9&nbsp;&nbsp;&nbsp; Color model and
palettes</h3>

<p>The Microwindows graphics engine requires all colors to be specified as either 24-bit
RGB color values, or in rare cases, as palette indices for speed.&nbsp; The palette index
method will only work on systems that have hardware palettes, so it's not
recommended.&nbsp; All of the upper-level color parameters are specified to the engine
routines using a COLORVAL value, which is a long containing the desired RGB color, created
using the RGB() macro.&nbsp; The engine then converts the COLORVAL to a PIXELVAL value,
which is normally a long also, but on some smaller systems can be compiled as an unsigned
char.&nbsp; The PIXELVAL value is the actual value passed to any screen driver entry point
requiring a color.&nbsp; So the mid level routines all work with RGB COLORVALs, while the
device driver routines all work with PIXELVALs.&nbsp; The graphics engine converts these
values using two routines, GdFindColor and GdFindNearestColor, described below.</p>

<p>GdFindColor takes a hardware independent RGB value and converts it to a hardware
dependent PIXELVAL pixel value.&nbsp; In the case of 32bpp display drivers, no conversion
is required.&nbsp; Otherwise for truecolor systems, Microwindows converts the RGB value to
a 5/5/5 15-bit or 5/6/5 16 bit truecolor value.&nbsp; For 8bpp truecolor displays, the RGB
value is converted to 3/3/2.&nbsp; For palletized displays, the GdFindNearestColor
function is called to convert the RGB color to the nearest palette index in the current
system palette.&nbsp; GdFindNearestColor uses a weighted distance-cubed method to find the
palette value nearest to the requested color, and returns it.&nbsp; Standard palettes for
1, 2, 4 and 8bpp are included in the files devpal1, devpal2, devpal4 and devpal8.c.&nbsp;
These palettes associate an RGB value with an index, but may be overwritten.</p>

<p>The GdSetPalette function determines whether there are any free entries in the system
palette (discussed shortly) and if so, adds entries to the system palette, and calls the
screen driver SetPalette entry point to set the hardware palette.&nbsp; There is a single
global variable, gr_firstuserpalentry, that contains the index of the next available
system palette entry.&nbsp; Initially, this is set to 24.&nbsp; Thus, systems with less
than 24 total palette entries will never have an available palette entry to remap.&nbsp;
On systems that do, like 256 color systems, then images requiring more color entries keep
calling GdSetPalette until the system palette is full.&nbsp; To reset marker, the function
GdResetPalette is called.&nbsp; This allows upper level API's to distinguish between
different images and force the system palette to be rewritten.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.10&nbsp; Image Drawing</h3>

<p>Microwindows supports two styles of images, monochrome and palettized.&nbsp; Monochrome
images are specified with an IMAGEBITS structure, which is an array of words with 1 bits
specifying the foreground color and 0 bits the background.&nbsp; The IMAGEBITS bits are
short-word padded to the width of the bitmap.&nbsp; The GdBitmap routine draws monochrome
bitmaps, similar to GdText, by drawing all the 1 bits in the foreground color, and the 0
bits in the background color if the &quot;use background&quot; set by GdUseBackground is
TRUE.</p>

<p>Color bitmaps are specified using a 1, 4 or 8bpp image palette, and an array of indices
into this palette, all stuffed into an IMAGEHDR structure, and drawn via
GdDrawImage.&nbsp; First, the system creates a conversion palette by calling
GdMakePaletteConversionTable, which converts the images' palette entries into system
indices.&nbsp; At the same time, the system attempts to increase the system palette if
necessary by calling the GdSetPalette function described above.&nbsp; At the end of this
operation, the image has a converted palette which necessarily corresponds to the system
palette.&nbsp; In the case of truecolor hardware, the image's palette entries are
converted to hardware truecolor pixel values, and output directly.</p>

<p>After converting the image color entries the GdDrawImage determines the whether the
image is clipped, and outputs the image, pixel by pixel.&nbsp; In the future, a blitting
routine could be used for faster image drawing.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1.11&nbsp; Blitting</h3>

<p>Blitting functionality is required in the screen driver for offscreen drawing
capability, discussed earlier in the screen drivers section.&nbsp; The engine function
GdBlit allows upper level APIs to implement copy operations from offscreen memory to the
display, or vice versa.&nbsp; The blit format is driver specific, and generally only works
for memory images created by the screen driver during runtime.&nbsp; The upper level APIs
implement this by allocating a new SCREENDRIVER structure, copying an existing
SCREENDRIVER structure into it, replacing the address field with a malloc()'d value, and
setting the PSF_MEMORY bit, which indicates to the display driver that this is now an
offscreen surface.&nbsp; Any subsequent calls to the engine routines then draw onto this
surface.&nbsp; When it is desired to copy the offscreen surface back to the physical
display, the GdBlit routine is called.&nbsp; Currently, only SRCCOPY operations are
performed, but future plans will add blitting opcodes.</p>

<p>&nbsp;</p>

<h3>3. Microwindows API</h3>

<h3>&nbsp;&nbsp;&nbsp; 3.1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Message-passing
architecture</h3>

<p>The fundamental communications mechanism in the Microwindows API is the message.&nbsp;
A message consists of a well-known message number, and two parameters, known as wParam and
lParam.&nbsp; Messages are stored in an application's message-queue, and retrieved via the
GetMessage function.&nbsp; The application blocks while waiting for a message.&nbsp; There
are messages that correspond to hardware events, like WM_CHAR for keyboard input or
WM_LBUTTONDOWN for mouse button down.&nbsp; In addtiion, events signaling window creation
and destruction WM_CREATE and WM_DESTROY are sent.&nbsp; In most cases, a message is
associated with a window, identified as an HWND.&nbsp; After retrieving the message, the
application sends the message to the associated window's handling procedure using
DispatchMessage.&nbsp; When a window class is created, it's associated message handling
procedure is specified, so the system knows where to send the message.</p>

<p>The message-passing architecture allows the core API to manage many system functions by
sending messages on all sorts of events, like window creation, painting needed, moving,
etc.&nbsp; By default, the associated window handling function gets a &quot;first
pass&quot; at the message, and then calls the DefWindowProc function, which handles
default actions for all the messages.&nbsp; In this way, all windows can behave the same
way when dragged, etc, unless specifically overridden by the user.&nbsp; Major window
management policies can be redefined by merely re-implementing DefWindowProc, rather than
making changes throughout the system.</p>

<p>The following functions deal with messages directly:</p>

<p>&nbsp;&nbsp;&nbsp;
SendMessage&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Send a message directly to a window<br>
&nbsp;&nbsp;&nbsp;
PostMessage&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Queue a message on the application's message queue for later dispatch<br>
&nbsp;&nbsp;&nbsp; PostQuitMessage&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Queue a WM_QUIT message telling the application to terminate when read<br>
&nbsp;&nbsp;&nbsp;
GetMessage&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Block until a message is queued for this application<br>
&nbsp;&nbsp;&nbsp; TranslateMessage&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Translate up/down keystrokes to WM_CHAR messages<br>
&nbsp;&nbsp;&nbsp;
DispatchMessage&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Send a
messages to it's associated window procedure</p>

<p>A Microwindows application's entry point is the function WinMain, rather than main.</p>

<h3>&nbsp;&nbsp;&nbsp; 3.2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Window creation and
destruction</h3>

<p>The basic unit of screen organization in Microwindows API is the window.&nbsp; Windows
describe an area of the screen to draw onto, as well as an associate &quot;window
procedure&quot; for handling messages destined for this window.&nbsp; Applications
programmers can create windows from pre-defined classes, like buttons, edit boxes, and the
like, or define their own window classes.&nbsp; In both cases, the method of creating and
communicating with the windows remains exactly the same.&nbsp; The following functions
deal with window registration, creation, and destruction:</p>

<p>&nbsp;&nbsp;&nbsp;
RegisterClass&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Define a new window class name and associated window procedure<br>
&nbsp;&nbsp;&nbsp;
UnRegisterClass&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Undefine
a window class<br>