<html>
|
<html>
|
|
|
<head>
|
<head>
|
<meta http-equiv="Content-Language" content="en-us">
|
<meta http-equiv="Content-Language" content="en-us">
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
<title>MicroWindows Architecture</title>
|
<title>MicroWindows Architecture</title>
|
</head>
|
</head>
|
|
|
<body>
|
<body>
|
|
|
<h1 align="left"><img border="0" src="file:///C:/My%20Documents/My%20Webs/myweb2/images/clouds.gif" width="72" height="33">Microwindows Architecture</h1>
|
<h1 align="left"><img border="0" src="file:///C:/My%20Documents/My%20Webs/myweb2/images/clouds.gif" width="72" height="33">Microwindows Architecture</h1>
|
|
|
<p align="left">1999/12/04 Copyright (c) 1999 Greg Haerr <<a href="mailto:greg@censoft.com">greg@censoft.com</a>> All Rights Reserved.</p>
|
<p align="left">1999/12/04 Copyright (c) 1999 Greg Haerr <<a href="mailto:greg@censoft.com">greg@censoft.com</a>> All Rights Reserved.</p>
|
|
|
<p align="left">This is my first cut at getting the architecture and implementation
|
<p align="left">This is my first cut at getting the architecture and implementation
|
spilled out. Please let me know if there's more detail needed in some areas, or
|
spilled out. Please let me know if there's more detail needed in some areas, or
|
whether you're confused by my explanations. This document is for educational and
|
whether you're confused by my explanations. This document is for educational and
|
porting purposes, so please read on.</p>
|
porting purposes, so please read on.</p>
|
|
|
<h3>Contents</h3>
|
<h3>Contents</h3>
|
|
|
<p>1. Architecture<br>
|
<p>1. Architecture<br>
|
1.1 Layered Design<br>
|
1.1 Layered Design<br>
|
1.2 Device Drivers<br>
|
1.2 Device Drivers<br>
|
1.2.1 Screen Driver<br>
|
1.2.1 Screen Driver<br>
|
1.2.2 Mouse Driver<br>
|
1.2.2 Mouse Driver<br>
|
1.2.3 Keyboard Driver<br>
|
1.2.3 Keyboard Driver<br>
|
1.3 MicroGUI - Device
|
1.3 MicroGUI - Device
|
Independent Graphics Engine <br>
|
Independent Graphics Engine <br>
|
1.4 Applications Programmer
|
1.4 Applications Programmer
|
Interfaces<br>
|
Interfaces<br>
|
1.4.1 Microwindows API<br>
|
1.4.1 Microwindows API<br>
|
1.4.2 Nano-X API</p>
|
1.4.2 Nano-X API</p>
|
|
|
<p>2. Device-Independent Engine Features<br>
|
<p>2. Device-Independent Engine Features<br>
|
2.1 Graphics Engine Features
|
2.1 Graphics Engine Features
|
and Implementation<br>
|
and Implementation<br>
|
2.1.1 Regions<br>
|
2.1.1 Regions<br>
|
2.1.2 Clipping<br>
|
2.1.2 Clipping<br>
|
2.1.3 Line Drawing<br>
|
2.1.3 Line Drawing<br>
|
2.1.4 Rectangles, Circles,
|
2.1.4 Rectangles, Circles,
|
Ellipses<br>
|
Ellipses<br>
|
2.1.5 Polygons<br>
|
2.1.5 Polygons<br>
|
2.1.6 Area Fills<br>
|
2.1.6 Area Fills<br>
|
2.1.7 Fonts<br>
|
2.1.7 Fonts<br>
|
2.1.8 Text Drawing<br>
|
2.1.8 Text Drawing<br>
|
2.1.9 Color model and
|
2.1.9 Color model and
|
palettes<br>
|
palettes<br>
|
2.1.10 Image Drawing<br>
|
2.1.10 Image Drawing<br>
|
2.1.11 Blitting</p>
|
2.1.11 Blitting</p>
|
|
|
<p>3. Microwindows API<br>
|
<p>3. Microwindows API<br>
|
3.1 Message-passing
|
3.1 Message-passing
|
architecture<br>
|
architecture<br>
|
3.2 Window creation and
|
3.2 Window creation and
|
destruction<br>
|
destruction<br>
|
3.3 Window showing, hiding
|
3.3 Window showing, hiding
|
and moving<br>
|
and moving<br>
|
3.4 Window painting<br>
|
3.4 Window painting<br>
|
3.4.1 Client and screen
|
3.4.1 Client and screen
|
coordinates<br>
|
coordinates<br>
|
3.4.2 Device contexts<br>
|
3.4.2 Device contexts<br>
|
3.4.3 Graphics drawing API<br>
|
3.4.3 Graphics drawing API<br>
|
3.5 Utility functions<br>
|
3.5 Utility functions<br>
|
3.5.1 Setting window focus<br>
|
3.5.1 Setting window focus<br>
|
3.5.2 Mouse capture<br>
|
3.5.2 Mouse capture<br>
|
3.5.3 Rectangle and Region
|
3.5.3 Rectangle and Region
|
management</p>
|
management</p>
|
|
|
<p>4. Nano-X API<br>
|
<p>4. Nano-X API<br>
|
4.1 Client/Server model<br>
|
4.1 Client/Server model<br>
|
4.2 Events<br>
|
4.2 Events<br>
|
4.3 Window creation and
|
4.3 Window creation and
|
destruction<br>
|
destruction<br>
|
4.4 Window showing, hiding
|
4.4 Window showing, hiding
|
and moving<br>
|
and moving<br>
|
4.5 Drawing to a window<br>
|
4.5 Drawing to a window<br>
|
4.5.1 Graphics contexts<br>
|
4.5.1 Graphics contexts<br>
|
4.5.2 Graphics drawing API<br>
|
4.5.2 Graphics drawing API<br>
|
4.6 Utility functions</p>
|
4.6 Utility functions</p>
|
|
|
<h3>1. Architecture</h3>
|
<h3>1. Architecture</h3>
|
|
|
<h3>1.1 Layered Design</h3>
|
<h3>1.1 Layered Design</h3>
|
|
|
<p>Microwindows is essentially a layered design that allows different layers to be used or
|
<p>Microwindows is essentially a layered design that allows different layers to be used or
|
rewritten to suite the needs of the implementation. At the lowest level, screen,
|
rewritten to suite the needs of the implementation. At the lowest level, screen,
|
mouse/touchpad and keyboard drivers provide access to the actual display and other
|
mouse/touchpad and keyboard drivers provide access to the actual display and other
|
user-input hardware. At the mid level, a portable graphics engine is implemented,
|
user-input hardware. At the mid level, a portable graphics engine is implemented,
|
providing support for line draws, area fills, polygons, clipping and color models.
|
providing support for line draws, area fills, polygons, clipping and color models.
|
At the upper level, various API's are implemented providing access to the graphics
|
At the upper level, various API's are implemented providing access to the graphics
|
applications programmer. These APIs may or may not provide desktop and/or window
|
applications programmer. These APIs may or may not provide desktop and/or window
|
look and feel. Currently, Microwindows supports the ECMA APIW and Nano-X APIs.
|
look and feel. Currently, Microwindows supports the ECMA APIW and Nano-X APIs.
|
These APIs provide close compatibility with the Win32 and X Window systems, allowing
|
These APIs provide close compatibility with the Win32 and X Window systems, allowing
|
programs to be ported from other systems easily.</p>
|
programs to be ported from other systems easily.</p>
|
|
|
<h3>1.2 Device Drivers</h3>
|
<h3>1.2 Device Drivers</h3>
|
|
|
<p>The device driver interfaces are defined in device.h. A given implementation of
|
<p>The device driver interfaces are defined in device.h. A given implementation of
|
Microwindows will link at least one screen, mouse and keyboard driver into the
|
Microwindows will link at least one screen, mouse and keyboard driver into the
|
system. The mid level routines in the device-independent graphics engine core then
|
system. The mid level routines in the device-independent graphics engine core then
|
call the device driver directly to perform the hardware-specific operations. This
|
call the device driver directly to perform the hardware-specific operations. This
|
setup allows varying hardware devices to be added to the Microwindows system without
|
setup allows varying hardware devices to be added to the Microwindows system without
|
affecting the way the entire system works.</p>
|
affecting the way the entire system works.</p>
|
|
|
<h3>1.2.1 Screen Driver</h3>
|
<h3>1.2.1 Screen Driver</h3>
|
|
|
<p>There are currently screen drivers written for Linux 2.2.x framebuffer systems, as well
|
<p>There are currently screen drivers written for Linux 2.2.x framebuffer systems, as well
|
as 16-bit ELKS and MSDOS drivers for real-mode VGA cards. The real mode drivers
|
as 16-bit ELKS and MSDOS drivers for real-mode VGA cards. The real mode drivers
|
(scr_bios.c, vgaplan4.c, mempl4.c, scr_her.c) can be configured to initialize the VGA
|
(scr_bios.c, vgaplan4.c, mempl4.c, scr_her.c) can be configured to initialize the VGA
|
hardware directly, or utilize the PC BIOS to begin and end graphics mode. The
|
hardware directly, or utilize the PC BIOS to begin and end graphics mode. The
|
framebuffer drivers (scr_fb.c, fb.c, fblin?.c) have routines for 1, 2, 4 and 8bpp
|
framebuffer drivers (scr_fb.c, fb.c, fblin?.c) have routines for 1, 2, 4 and 8bpp
|
palletized displays, as well as 8, 15, 16, and 32 bpp truecolor displays. The
|
palletized displays, as well as 8, 15, 16, and 32 bpp truecolor displays. The
|
framebuffer system works in Linux by opening /dev/fd0 (or getenv("FRAMEBUFFER"))
|
framebuffer system works in Linux by opening /dev/fd0 (or getenv("FRAMEBUFFER"))
|
and mmap()ing the display memory into a linear buffer in memory. Some display modes,
|
and mmap()ing the display memory into a linear buffer in memory. Some display modes,
|
like the VGA 4 planes mode, require that OUT instructions be issued by the screen driver,
|
like the VGA 4 planes mode, require that OUT instructions be issued by the screen driver,
|
while packed pixel drivers typically can get away with just reading and writing the
|
while packed pixel drivers typically can get away with just reading and writing the
|
framebuffer only. All the graphics mode initialization and deinitialization is
|
framebuffer only. All the graphics mode initialization and deinitialization is
|
handled by the Linux kernel. Getting this set up can be a real pain.</p>
|
handled by the Linux kernel. Getting this set up can be a real pain.</p>
|
|
|
<p>The screen driver is the most complex driver in the system, but was designed so that it
|
<p>The screen driver is the most complex driver in the system, but was designed so that it
|
can be extremely easy to port new hardware to Microwindows. For this reason, there
|
can be extremely easy to port new hardware to Microwindows. For this reason, there
|
are but a few entry points that must actually talk to the hardware, while other routines
|
are but a few entry points that must actually talk to the hardware, while other routines
|
are provided that allow just the small set of core routines to be used, if desired.
|
are provided that allow just the small set of core routines to be used, if desired.
|
For example, a screen driver must implement ReadPixel, DrawPixel, DrawHorzLine, and
|
For example, a screen driver must implement ReadPixel, DrawPixel, DrawHorzLine, and
|
DrawVertLine. These routines read and write a pixel from display memory, as well as
|
DrawVertLine. These routines read and write a pixel from display memory, as well as
|
draw a horizontal and vertical line. Clipping is handled at the device-independent
|
draw a horizontal and vertical line. Clipping is handled at the device-independent
|
layer. Currently, all mouse movement, text drawing, and bitmap drawing run on top of
|
layer. Currently, all mouse movement, text drawing, and bitmap drawing run on top of
|
these low level functions. In the future, entry points will be provided for fast
|
these low level functions. In the future, entry points will be provided for fast
|
text and bitmap drawing capabilities. If the display is palletized, a SetPalette
|
text and bitmap drawing capabilities. If the display is palletized, a SetPalette
|
routine must be included, unless a static palette that matches the system palette is
|
routine must be included, unless a static palette that matches the system palette is
|
linked into the system. The screen driver, on initialization, returns values telling
|
linked into the system. The screen driver, on initialization, returns values telling
|
the system the x,y size of the screen, along with the color model supported.</p>
|
the system the x,y size of the screen, along with the color model supported.</p>
|
|
|
<p>Two font models are currently provided, to be linked in at your desire. The
|
<p>Two font models are currently provided, to be linked in at your desire. The
|
proportional font model has in-core font tables built from .bdf and other font conversion
|
proportional font model has in-core font tables built from .bdf and other font conversion
|
utilities provided. The rom-based font uses the PC BIOS to find the character
|
utilities provided. The rom-based font uses the PC BIOS to find the character
|
generator table address and has routines to draw that fixed-pitch font format.</p>
|
generator table address and has routines to draw that fixed-pitch font format.</p>
|
|
|
<p>The screen driver can choose to implement bitblitting, by ORing in PSF_HAVEBLIT into
|
<p>The screen driver can choose to implement bitblitting, by ORing in PSF_HAVEBLIT into
|
the returned flags field. When present, bit blitting allows Microwindows to perform
|
the returned flags field. When present, bit blitting allows Microwindows to perform
|
off-screen drawing. Microwindows allows any graphics operation that can be performed
|
off-screen drawing. Microwindows allows any graphics operation that can be performed
|
on a physical screen to be performed off-screen, and then copied (bit-blitted) to the
|
on a physical screen to be performed off-screen, and then copied (bit-blitted) to the
|
physical screen. Implementing a blitting screen driver can be fairly complex.
|
physical screen. Implementing a blitting screen driver can be fairly complex.
|
The first consideration in implementing a blitting driver is whether the low-level display
|
The first consideration in implementing a blitting driver is whether the low-level display
|
hardware can be passed a hardware address for a framebuffer. If so, then the same
|
hardware can be passed a hardware address for a framebuffer. If so, then the same
|
routines that draw to the physical screen can be used to draw to off-screen buffers.
|
routines that draw to the physical screen can be used to draw to off-screen buffers.
|
This is the method used for the linear framebuffer drivers provided for Linux packed-pixel
|
This is the method used for the linear framebuffer drivers provided for Linux packed-pixel
|
displays. The system replaces the mmap()'d physical framebuffer address with a
|
displays. The system replaces the mmap()'d physical framebuffer address with a
|
malloc()'d memory address and calls the original screen driver entry point. In the
|
malloc()'d memory address and calls the original screen driver entry point. In the
|
case where the system doesn't use an actual physical memory address, like when running on
|
case where the system doesn't use an actual physical memory address, like when running on
|
top of X or MS Windows, then two sets of routines must be written; one to write the the
|
top of X or MS Windows, then two sets of routines must be written; one to write the the
|
underlying graphics system hardware, and another to write to memory addresses. In
|
underlying graphics system hardware, and another to write to memory addresses. In
|
addition, the blit entry point must then know how to copy both ways between the two
|
addition, the blit entry point must then know how to copy both ways between the two
|
formats. In fact, all four operations, screen-to-memory, memory-to-screen,
|
formats. In fact, all four operations, screen-to-memory, memory-to-screen,
|
memory-to-memory, and screen-to-screen are supported by Microwindows and may need to be
|
memory-to-memory, and screen-to-screen are supported by Microwindows and may need to be
|
performed. And of course the bit blitting routine must be _fast_. See the
|
performed. And of course the bit blitting routine must be _fast_. See the
|
files fblin8.c and mempl4.c for examples of supporting both types of display hardware.</p>
|
files fblin8.c and mempl4.c for examples of supporting both types of display hardware.</p>
|
|
|
<p>If writing your first screen driver, I would recommend you start with the PC BIOS real
|
<p>If writing your first screen driver, I would recommend you start with the PC BIOS real
|
mode driver, scr_bios.c, or take a look at the framebuffer driver, scr_fb.c, which is
|
mode driver, scr_bios.c, or take a look at the framebuffer driver, scr_fb.c, which is
|
essentially a wrapper around all the fblin?.c routines to read and write various
|
essentially a wrapper around all the fblin?.c routines to read and write various
|
framebuffer formats. Don't set the PSF_HAVEBLIT flag at first, and you won't have to
|
framebuffer formats. Don't set the PSF_HAVEBLIT flag at first, and you won't have to
|
write a bitblit routine from the start.</p>
|
write a bitblit routine from the start.</p>
|
|
|
<p>Note that currently, all SCREENDEVICE function pointers must be filled in to at least a
|
<p>Note that currently, all SCREENDEVICE function pointers must be filled in to at least a
|
void function. For speed reasons, the system always assumes that the function
|
void function. For speed reasons, the system always assumes that the function
|
pointers are valid. Thus, even if not implementing bitblit, a do-nothing bit-blit
|
pointers are valid. Thus, even if not implementing bitblit, a do-nothing bit-blit
|
procedure must be provided.</p>
|
procedure must be provided.</p>
|
|
|
<h3>1.2.2 Mouse Driver</h3>
|
<h3>1.2.2 Mouse Driver</h3>
|
|
|
<p>There are three mouse drivers currently included in Microwindows. A GPM driver
|
<p>There are three mouse drivers currently included in Microwindows. A GPM driver
|
for Linux, mou_gpm.c, as well as a serial port mouse driver for Linux and ELKS,
|
for Linux, mou_gpm.c, as well as a serial port mouse driver for Linux and ELKS,
|
mou_ser.c. For MSDOS, an int33 driver mou_dos.c is provided. The provided
|
mou_ser.c. For MSDOS, an int33 driver mou_dos.c is provided. The provided
|
mouse drivers decode MS, PC and Logitech mice formats. A mouse driver's basic
|
mouse drivers decode MS, PC and Logitech mice formats. A mouse driver's basic
|
function is to decode the mouse data and return either relative or absolute data for the
|
function is to decode the mouse data and return either relative or absolute data for the
|
mouse position and buttons.</p>
|
mouse position and buttons.</p>
|
|
|
<p>In addition, Brad LaRonde has written a touch panel driver mou_tp.c, which masquerades
|
<p>In addition, Brad LaRonde has written a touch panel driver mou_tp.c, which masquerades
|
as a mouse driver. It returns the value of x, y value of the pen on the display
|
as a mouse driver. It returns the value of x, y value of the pen on the display
|
surface, and can be used like a mouse.</p>
|
surface, and can be used like a mouse.</p>
|
|
|
<p>Under Linux, the main loop of Microwindows is a select() statement, with file
|
<p>Under Linux, the main loop of Microwindows is a select() statement, with file
|
descriptors for the mouse and keyboard driver always passed in. If the system that
|
descriptors for the mouse and keyboard driver always passed in. If the system that
|
Microwindows is running on doesn't support select() or doesn't pass mouse data through a
|
Microwindows is running on doesn't support select() or doesn't pass mouse data through a
|
file descriptor, a Poll() entry point is provided.</p>
|
file descriptor, a Poll() entry point is provided.</p>
|
|
|
<h3>1.2.3 Keyboard Driver</h3>
|
<h3>1.2.3 Keyboard Driver</h3>
|
|
|
<p>There are two keyboard drivers provided. The first, kbd_tty.c, is used for Linux
|
<p>There are two keyboard drivers provided. The first, kbd_tty.c, is used for Linux
|
and ELKS systems where the keyboard is opened and read as through a file descriptor.
|
and ELKS systems where the keyboard is opened and read as through a file descriptor.
|
The second, kbd_bios.c, read the PC BIOS for keystrokes and is used in MSDOS real
|
The second, kbd_bios.c, read the PC BIOS for keystrokes and is used in MSDOS real
|
mode. The keyboard driver currently returns 8-bit data from the keyboard, but
|
mode. The keyboard driver currently returns 8-bit data from the keyboard, but
|
doesn't decode multi-character function key codes. This functionality will need to be
|
doesn't decode multi-character function key codes. This functionality will need to be
|
added soon, by reading termcap files or the like.</p>
|
added soon, by reading termcap files or the like.</p>
|
|
|
<h3>1.3 MicroGUI - Device Independent Graphics
|
<h3>1.3 MicroGUI - Device Independent Graphics
|
Engine</h3>
|
Engine</h3>
|
|
|
<p> The core graphics functionality of Microwindows resides in the device independent
|
<p> The core graphics functionality of Microwindows resides in the device independent
|
graphics engine, which calls the screen, mouse and keyboard drivers to interface with the
|
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
|
hardware. User applications programs never all the core graphics engine routines
|
directly, but rather through the programmer API's, discussed in the next sections.
|
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
|
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
|
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
|
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
|
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
|
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,
|
be used together to implement more complex functions without always converting handles,
|
etc.</p>
|
etc.</p>
|
|
|
<p>In Microwindows, the core routines all begin as GdXXX() functions, and are concerned
|
<p>In Microwindows, the core routines all begin as GdXXX() functions, and are concerned
|
with graphics output, not window management. In addition, all clipping and color
|
with graphics output, not window management. In addition, all clipping and color
|
conversion is handled within this layer. The following files comprise the core
|
conversion is handled within this layer. The following files comprise the core
|
modules of Microwindows:</p>
|
modules of Microwindows:</p>
|
|
|
<p> devdraw.c Core graphics
|
<p> devdraw.c Core graphics
|
routines for line, circle, polygon draw and fill, text and bitmap drawing, color
|
routines for line, circle, polygon draw and fill, text and bitmap drawing, color
|
conversion</p>
|
conversion</p>
|
|
|
<p> devclip.c Core
|
<p> devclip.c Core
|
clipping routines. (devclip2.c is the new y-x-banding algorithm, devclip1.c an older
|
clipping routines. (devclip2.c is the new y-x-banding algorithm, devclip1.c an older
|
method)</p>
|
method)</p>
|
|
|
<p> devrgn.c
|
<p> devrgn.c
|
New dynamically allocated routines for intersect/union/subtract/xor region creation.</p>
|
New dynamically allocated routines for intersect/union/subtract/xor region creation.</p>
|
|
|
<p> devmouse.c Core routines for keeping
|
<p> devmouse.c Core routines for keeping
|
the mouse pointer updated or clipped from the screen.</p>
|
the mouse pointer updated or clipped from the screen.</p>
|
|
|
<p> devkbd.c Core
|
<p> devkbd.c Core
|
keyboard handling routines.</p>
|
keyboard handling routines.</p>
|
|
|
<p> devpalX.c Linked in
|
<p> devpalX.c Linked in
|
static palettes for 1, 2, 4 and 8bpp palletized systems.</p>
|
static palettes for 1, 2, 4 and 8bpp palletized systems.</p>
|
|
|
<p>Section 2 following discusses the MicroGUI graphics engine routines in detail.</p>
|
<p>Section 2 following discusses the MicroGUI graphics engine routines in detail.</p>
|
|
|
<h3>1.4 Applications Programmer Interfaces</h3>
|
<h3>1.4 Applications Programmer Interfaces</h3>
|
|
|
<p>Microwindows currently supports two different application programming interfaces.
|
<p>Microwindows currently supports two different application programming interfaces.
|
This set of routines handles client/server activity, window manager activities like
|
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
|
drawing title bars, close boxes, etc, as well as, of course, handling the programmer's
|
requests for graphics output. Both the API's run on top of the core graphics engine
|
requests for graphics output. Both the API's run on top of the core graphics engine
|
routines and device drivers. </p>
|
routines and device drivers. </p>
|
|
|
<p>The basic model of any API on top of Microwindows is to hang in initialize the screen,
|
<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. When
|
keyboard and mouse drivers, then hang in a select() loop waiting for an event. When
|
an event occurs, if it's a system event like keyboard or mouse activity, then this
|
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,
|
information is passed to the user program converted to an expose event, paint message,
|
etc. If it's a user requesting a graphics operation, then the parameters are decoded
|
etc. If it's a user requesting a graphics operation, then the parameters are decoded
|
and passed to the appropriate GdXXX engine routine. Note that the concept of a
|
and passed to the appropriate GdXXX engine routine. Note that the concept of a
|
window versus raw graphics operations are handled at this API level. That is, the
|
window versus raw graphics operations are handled at this API level. That is, the
|
API defines the concepts of what a window is, what the coordinate systems are, etc, and
|
API defines the concepts of what a window is, what the coordinate systems are, etc, and
|
then the coordinates are all converted to "screen coordinates" and passed to the
|
then the coordinates are all converted to "screen coordinates" and passed to the
|
core GdXXX engine routines to do the real work. This level also defines graphics or
|
core GdXXX engine routines to do the real work. This level also defines graphics or
|
display contexts and passes that information, including clipping information, to the core
|
display contexts and passes that information, including clipping information, to the core
|
engine routines.</p>
|
engine routines.</p>
|
|
|
<p>Currently, the Microwindows API code is in win*.c, while the Nano-X API code is in
|
<p>Currently, the Microwindows API code is in win*.c, while the Nano-X API code is in
|
nanox/srv*.c.</p>
|
nanox/srv*.c.</p>
|
|
|
<h3>1.4.1 Microwindows API</h3>
|
<h3>1.4.1 Microwindows API</h3>
|
|
|
<p>The Microwindows API tries to be compliant with the European ECMA APIW standard.
|
<p>The Microwindows API tries to be compliant with the European ECMA APIW standard.
|
Currently, there is support for most of the graphics drawing and clipping routines, as
|
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
|
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
|
Microwindows API is message-based, and allows programs to be written without regard to the
|
eventual window management policies implemented by the system. The Microwindows API
|
eventual window management policies implemented by the system. The Microwindows API
|
is not currently client/server, and will be discussed in more detail in section 4.</p>
|
is not currently client/server, and will be discussed in more detail in section 4.</p>
|
|
|
<h3>1.4.2 Nano-X API</h3>
|
<h3>1.4.2 Nano-X API</h3>
|
|
|
<p>The Nano-X API is modeled after the mini-x server written initially by David Bell,
|
<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. It loosely follows
|
which was a reimplementation of X on the MINIX operating system. It loosely follows
|
the X Window System Xlib API, but the names all being with GrXXX() rather than
|
the X Window System Xlib API, but the names all being with GrXXX() rather than
|
X...(). Currently, the Nano-X API is client/server, but does not have any provisions
|
X...(). Currently, the Nano-X API is client/server, but does not have any provisions
|
for automatic window dressings, title bars, or user window moves. There are several
|
for automatic window dressings, title bars, or user window moves. There are several
|
groups writing widget sets currently, which will provide such things. Unfortunately,
|
groups writing widget sets currently, which will provide such things. Unfortunately,
|
the user programs must also then write only to a specific widget set API, rather than
|
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
|
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. (Although this
|
widget set will be upwardly available to the applications programmer. (Although this
|
could be considerable, in the case that, say Gdk was ported.)</p>
|
could be considerable, in the case that, say Gdk was ported.)</p>
|
|
|
<h3>2. Device-Independent Engine Features</h3>
|
<h3>2. Device-Independent Engine Features</h3>
|
|
|
<p>This section discusses in the capabilities and implementation of Microwindows' core
|
<p>This section discusses in the capabilities and implementation of Microwindows' core
|
graphics engine in detail. It's purpose is both educational and to allow extending
|
graphics engine in detail. It's purpose is both educational and to allow extending
|
an API by understanding how the engine works.</p>
|
an API by understanding how the engine works.</p>
|
|
|
<h3> 2.1 Graphics Engine
|
<h3> 2.1 Graphics Engine
|
Features and Implementation</h3>
|
Features and Implementation</h3>
|
|
|
<p>These routines concern themselves with drawing operations to off-screen or screen
|
<p>These routines concern themselves with drawing operations to off-screen or screen
|
surfaces. Each routine starts with Gd... and is passed a pointer to the SCREENDEVICE
|
surfaces. Each routine starts with Gd... and is passed a pointer to the SCREENDEVICE
|
structure (PSD) as it's first parameter. The PSD parameter specifies the low level
|
structure (PSD) as it's first parameter. The PSD parameter specifies the low level
|
display details, like the x, y size of the device and the color model used by the
|
display details, like the x, y size of the device and the color model used by the
|
hardware, for example. In addition, the actual routines to perform drawing are
|
hardware, for example. In addition, the actual routines to perform drawing are
|
function pointers in this structure. All screen coordinates are of type COORD, and
|
function pointers in this structure. All screen coordinates are of type COORD, and
|
specified in device coordinates, that is, offsets from the upper left corner of the
|
specified in device coordinates, that is, offsets from the upper left corner of the
|
screen.</p>
|
screen.</p>
|
|
|
<p>Colors are always specified as an RGB COLORVAL value into the graphics engine.
|
<p>Colors are always specified as an RGB COLORVAL value into the graphics engine.
|
They are then possibly converted to palette indices and sent to the display hardware as
|
They are then possibly converted to palette indices and sent to the display hardware as
|
PIXELVAL values. In the case of 32bpp truecolor displays, no conversion is
|
PIXELVAL values. In the case of 32bpp truecolor displays, no conversion is
|
required. The color model will be discussed in detail below.</p>
|
required. The color model will be discussed in detail below.</p>
|
|
|
<h3> 2.1.1 Regions</h3>
|
<h3> 2.1.1 Regions</h3>
|
|
|
<p>Regions are used to describe arbitrary sets of pixels on the screen. A simple,
|
<p>Regions are used to describe arbitrary sets of pixels on the screen. A simple,
|
square region of pixels can be described by a single rectangle. More complex sets of
|
square region of pixels can be described by a single rectangle. More complex sets of
|
pixels require more complex data structures. In Microwindows, regions are described
|
pixels require more complex data structures. In Microwindows, regions are described
|
by an array of non-overlapping rectangles. Currently, there are two different
|
by an array of non-overlapping rectangles. Currently, there are two different
|
implementations of regions in Microwindows, as I've been enhancing the capabilities in
|
implementations of regions in Microwindows, as I've been enhancing the capabilities in
|
this area. The original design used a single static array of CLIPRECTs to describe
|
this area. The original design used a single static array of CLIPRECTs to describe
|
complex regions. Any point within any rectangle in the array was considered to be in
|
complex regions. Any point within any rectangle in the array was considered to be in
|
the region. The array wasn't sorted in any particular order, but was always
|
the region. The array wasn't sorted in any particular order, but was always
|
guaranteed to contain non-overlapping rectangles. Another global variable,
|
guaranteed to contain non-overlapping rectangles. Another global variable,
|
clipcount, specified the number of rectangles in the array. This original design had
|
clipcount, specified the number of rectangles in the array. This original design had
|
no engine entry points for region management, the entire array was passed to the clipping
|
no engine entry points for region management, the entire array was passed to the clipping
|
functions, described below. </p>
|
functions, described below. </p>
|
|
|
<p>In the new design, any number of regions can be created, as the regions (CLIPREGION *)
|
<p>In the new design, any number of regions can be created, as the regions (CLIPREGION *)
|
are stored as dynamically allocated arrays of rectangles. In this implementation,
|
are stored as dynamically allocated arrays of rectangles. In this implementation,
|
the non-overlapping rectangles are always kept in "y-x" sorted bands, such that
|
the non-overlapping rectangles are always kept in "y-x" sorted bands, such that
|
each band's y height is the same for all rectangles in the band. This means that
|
each band's y height is the same for all rectangles in the band. This means that
|
only the x position and width of the rectangles in each band varied. Because of
|
only the x position and width of the rectangles in each band varied. Because of
|
this, it is easier to create a set of functions for combining regions, since effectively
|
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. The new region
|
only a single dimension had to be compared for each region operation. The new region
|
handling routines allow for creating and destroying regions, as well as combining
|
handling routines allow for creating and destroying regions, as well as combining
|
rectangles and regions with regions using Intersection, Union, Subtraction, and Exclusive
|
rectangles and regions with regions using Intersection, Union, Subtraction, and Exclusive
|
Or. This model allows regions to be implemented apart from the clipping routines,
|
Or. This model allows regions to be implemented apart from the clipping routines,
|
unlike the first version. Following are the new region routines:</p>
|
unlike the first version. Following are the new region routines:</p>
|
|
|
<p>
|
<p>
|
GdAllocRegion
|
GdAllocRegion
|
- Create a region<br>
|
- Create a region<br>
|
|
|
GdDestroyRegion
|
GdDestroyRegion
|
- Destroy a region<br>
|
- Destroy a region<br>
|
|
|
GdCopyRegion
|
GdCopyRegion
|
- Copy a region<br>
|
- Copy a region<br>
|
GdUnionRectWithRegion - Union a rectangle with
|
GdUnionRectWithRegion - Union a rectangle with
|
a region<br>
|
a region<br>
|
|
|
GdIntersectRegion
|
GdIntersectRegion
|
- Create a region from the intersection of two regions<br>
|
- Create a region from the intersection of two regions<br>
|
|
|
GdSubtractRegion
|
GdSubtractRegion
|
- Create a region from the difference of two regions<br>
|
- Create a region from the difference of two regions<br>
|
|
|
GdUnionRegion
|
GdUnionRegion
|
- Create a region from the union of two regions<br>
|
- Create a region from the union of two regions<br>
|
|
|
GdXorRegion
|
GdXorRegion
|
- Create a region from the XOR of two regions<br>
|
- Create a region from the XOR of two regions<br>
|
</p>
|
</p>
|
|
|
<h3> 2.1.2 Clipping</h3>
|
<h3> 2.1.2 Clipping</h3>
|
|
|
<p>Clipping in Microwindows is closely tied to the region management code. At any
|
<p>Clipping in Microwindows is closely tied to the region management code. At any
|
point in time, the graphics engine has a single clipping region, that is a set of
|
point in time, the graphics engine has a single clipping region, that is a set of
|
rectangles, defined for any graphics operation. A point is drawn if it is
|
rectangles, defined for any graphics operation. A point is drawn if it is
|
"inside" any of the current set of clip rectangles. Two slightly modified
|
"inside" any of the current set of clip rectangles. Two slightly modified
|
versions of the clipping algorithm are supplied, devclip1.c for the original, static
|
versions of the clipping algorithm are supplied, devclip1.c for the original, static
|
rectangle array, and devclip2.c for the newer dynamically allocated array. A single
|
rectangle array, and devclip2.c for the newer dynamically allocated array. A single
|
entry point GdSetClipRects, takes the passed region and specifies it's use for all
|
entry point GdSetClipRects, takes the passed region and specifies it's use for all
|
subsequent graphics operations. All the drawing routines then use the two additional
|
subsequent graphics operations. All the drawing routines then use the two additional
|
routines to determine whether or not to draw. GdClipPoint takes an x,y point in
|
routines to determine whether or not to draw. GdClipPoint takes an x,y point in
|
screen coordinates and returns TRUE if the point can be drawn, that is, the point is
|
screen coordinates and returns TRUE if the point can be drawn, that is, the point is
|
within one of the region rectangles. GdClipArea takes an upper left and lower right
|
within one of the region rectangles. GdClipArea takes an upper left and lower right
|
point, and returns one of the following: CLIP_VISIBLE, if the specified area is completely
|
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
|
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
|
means that no drawing should be performed, or CLIP_PARTIAL, if a part but not the whole
|
area is within the region. A typical graphics primitive will call the screen driver
|
area is within the region. A typical graphics primitive will call the screen driver
|
with unmodified passed inputs if CLIP_VISIBLE is returned, or return if CLIP_INIVISIBLE is
|
with unmodified passed inputs if CLIP_VISIBLE is returned, or return if CLIP_INIVISIBLE is
|
returned. In the CLIP_PARTIAL case, the primitive must break up the original request
|
returned. 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. This
|
into areas that are within the clip region before calling the screen driver. This
|
slows down the operation considerably.</p>
|
slows down the operation considerably.</p>
|
|
|
<p>Because the clipping code is called constantly before drawing operations, Microwindows
|
<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
|
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>
|
and also to allow the mid level to quickly calculate how partial drawing lengths.</p>
|
|
|
<h3> 2.1.3 Line Drawing</h3>
|
<h3> 2.1.3 Line Drawing</h3>
|
|
|
<p>Line drawing is the simplest of graphics operations. Microwindows supports
|
<p>Line drawing is the simplest of graphics operations. Microwindows supports
|
GdPoint to draw a point, and GdLine to draw a horizontal, vertical or diagonal (using
|
GdPoint to draw a point, and GdLine to draw a horizontal, vertical or diagonal (using
|
Bresenham algorithm) line. Just before any call to the screen driver, a call to
|
Bresenham algorithm) line. Just before any call to the screen driver, a call to
|
GdCheckCursor assures that the software cursor is removed prior to drawing.
|
GdCheckCursor assures that the software cursor is removed prior to drawing.
|
GdFixCursor restores the cursor if previously visible.</p>
|
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
|
<p>There is a tricky part to line drawing that had to be added during the support for
|
multiple API's. This has to do with whether or not the last point in specified line
|
multiple API's. This has to do with whether or not the last point in specified line
|
segment is drawn or not. There are two schools of thought on this, and to make it
|
segment is drawn or not. There are two schools of thought on this, and to make it
|
short, Microwindows supports both of them. The last parameter to GdLine specifies
|
short, Microwindows supports both of them. The last parameter to GdLine specifies
|
whether or not to draw the last point. The Microwindows API doesn't draw the last
|
whether or not to draw the last point. The Microwindows API doesn't draw the last
|
point, but the Nano-X API does.</p>
|
point, but the Nano-X API does.</p>
|
|
|
<p>Most drawing functions, including line drawing draw using the "current"
|
<p>Most drawing functions, including line drawing draw using the "current"
|
foreground color, specified using GdSetForeground. In addition a drawing mode,
|
foreground color, specified using GdSetForeground. In addition a drawing mode,
|
currently either MODE_SET or MODE_XOR can be specified using GdSetMode.</p>
|
currently either MODE_SET or MODE_XOR can be specified using GdSetMode.</p>
|
|
|
<h3> 2.1.4 Rectangles,
|
<h3> 2.1.4 Rectangles,
|
Circles, Ellipses</h3>
|
Circles, Ellipses</h3>
|
|
|
<p>Rectangles, circles and ellipses are drawn using the GdRect and GdEllipse
|
<p>Rectangles, circles and ellipses are drawn using the GdRect and GdEllipse
|
routines. A circle is an ellipse with the same x and y radius. As with lines,
|
routines. A circle is an ellipse with the same x and y radius. As with lines,
|
rectangles and ellipses are drawn using the current foreground color and mode.</p>
|
rectangles and ellipses are drawn using the current foreground color and mode.</p>
|
|
|
<h3> 2.1.5 Polygons</h3>
|
<h3> 2.1.5 Polygons</h3>
|
|
|
<p>Microwindows supports polygon drawing by specifying an array of x, y points. The
|
<p>Microwindows supports polygon drawing by specifying an array of x, y points. The
|
points are then connected using the GdLine function. The current foreground color,
|
points are then connected using the GdLine function. The current foreground color,
|
drawing mode, and clip region is used during output.</p>
|
drawing mode, and clip region is used during output.</p>
|
|
|
<h3> 2.1.6 Area Fills</h3>
|
<h3> 2.1.6 Area Fills</h3>
|
|
|
<p>Microwindows supports filled rectangular areas using the GdFillRect function. The
|
<p>Microwindows supports filled rectangular areas using the GdFillRect function. The
|
rectangle's outline and contents are filled using the current foreground color.
|
rectangle's outline and contents are filled using the current foreground color.
|
Filled circles and ellipses are performed with GdFillEllipse, and polygon fills with
|
Filled circles and ellipses are performed with GdFillEllipse, and polygon fills with
|
GdFillPoly. Area filling is implemented through successive calls to the DrawHorzLine
|
GdFillPoly. Area filling is implemented through successive calls to the DrawHorzLine
|
in the screen driver, and are much faster if fully not clipped.</p>
|
in the screen driver, and are much faster if fully not clipped.</p>
|
|
|
<h3> 2.1.7 Fonts</h3>
|
<h3> 2.1.7 Fonts</h3>
|
|
|
<p>Both fixed pitch and proportional fonts are supported in Microwindows. Because of
|
<p>Both fixed pitch and proportional fonts are supported in Microwindows. Because of
|
potentially large differences in display hardware, the actual font format is known only to
|
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
|
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. The engine
|
converted .bdf fonts and Microsoft Windows fonts, if you have a license. The engine
|
function GdSetFont specifies a font number that is passed to the driver and used to index
|
function GdSetFont specifies a font number that is passed to the driver and used to index
|
a static array of linked in fonts. Screen driver entry points GetTextSize return the
|
a static array of linked in fonts. Screen driver entry points GetTextSize return the
|
font height and width for a passed string, and GetTextBits returns an individual character
|
font height and width for a passed string, and GetTextBits returns an individual character
|
bitmap. The engine layer uses these values to calculate a clipping region for text
|
bitmap. 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>
|
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
|
<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. A few
|
well as a proportional font format that is linked into the screen driver. A few
|
conversion programs allow conversion of fonts from different formats to the driver
|
conversion programs allow conversion of fonts from different formats to the driver
|
format. Bdftobogl converts X Window System .bdf files to Microwindows format.
|
format. Bdftobogl converts X Window System .bdf files to Microwindows format.
|
Convfnt32 converts raster and truetype Microsoft Windows fonts, if you have a license, to
|
Convfnt32 converts raster and truetype Microsoft Windows fonts, if you have a license, to
|
Microwindows format. Convrom converts PC ROM bios fonts.</p>
|
Microwindows format. Convrom converts PC ROM bios fonts.</p>
|
|
|
<p>A number of free fonts are supplied with the system, a heavier proportional 14x16
|
<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. Any
|
system font, and a sans-serif 11x13 font for title bar and edit box displays. Any
|
number of fonts can be linked into the system, and it's fairly easy to dynamically load
|
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>
|
fonts if one writes the routines for it.</p>
|
|
|
<h3> 2.1.8 Text Drawing</h3>
|
<h3> 2.1.8 Text Drawing</h3>
|
|
|
<p>Text output is performed by first selecting the desired font with GdSetFont, and then
|
<p>Text output is performed by first selecting the desired font with GdSetFont, and then
|
calling the GdText function. Full text clipping is performed, although currently
|
calling the GdText function. Full text clipping is performed, although currently
|
there is no "fast" text output entry point in the screen driver, so each
|
there is no "fast" text output entry point in the screen driver, so each
|
character bitmap is grabbed using the GetTextBits entrypoint and then drawn using
|
character bitmap is grabbed using the GetTextBits entrypoint and then drawn using
|
Drawpixel. While this will have to remain the same for partially clipped text, a
|
Drawpixel. 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>
|
screen driver entry point to draw fast text will probably be required shortly.</p>
|
|
|
<p>Text is drawn using the current foreground color. The background is drawn if the
|
<p>Text is drawn using the current foreground color. The background is drawn if the
|
current "use background" mode set via GdUseBackground is TRUE. In this
|
current "use background" mode set via GdUseBackground is TRUE. In this
|
case the background is drawn using the current background color set via
|
case the background is drawn using the current background color set via
|
GdSetBackground. The GdText function also takes a bottomAlign parameter that
|
GdSetBackground. 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>
|
specifies whether the text is to be bottom or top aligned, to help with differing API's.</p>
|
|
|
<h3> 2.1.9 Color model and
|
<h3> 2.1.9 Color model and
|
palettes</h3>
|
palettes</h3>
|
|
|
<p>The Microwindows graphics engine requires all colors to be specified as either 24-bit
|
<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. The palette index
|
RGB color values, or in rare cases, as palette indices for speed. The palette index
|
method will only work on systems that have hardware palettes, so it's not
|
method will only work on systems that have hardware palettes, so it's not
|
recommended. All of the upper-level color parameters are specified to the engine
|
recommended. 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
|
routines using a COLORVAL value, which is a long containing the desired RGB color, created
|
using the RGB() macro. The engine then converts the COLORVAL to a PIXELVAL value,
|
using the RGB() macro. 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
|
which is normally a long also, but on some smaller systems can be compiled as an unsigned
|
char. The PIXELVAL value is the actual value passed to any screen driver entry point
|
char. The PIXELVAL value is the actual value passed to any screen driver entry point
|
requiring a color. So the mid level routines all work with RGB COLORVALs, while the
|
requiring a color. So the mid level routines all work with RGB COLORVALs, while the
|
device driver routines all work with PIXELVALs. The graphics engine converts these
|
device driver routines all work with PIXELVALs. The graphics engine converts these
|
values using two routines, GdFindColor and GdFindNearestColor, described below.</p>
|
values using two routines, GdFindColor and GdFindNearestColor, described below.</p>
|
|
|
<p>GdFindColor takes a hardware independent RGB value and converts it to a hardware
|
<p>GdFindColor takes a hardware independent RGB value and converts it to a hardware
|
dependent PIXELVAL pixel value. In the case of 32bpp display drivers, no conversion
|
dependent PIXELVAL pixel value. In the case of 32bpp display drivers, no conversion
|
is required. Otherwise for truecolor systems, Microwindows converts the RGB value to
|
is required. Otherwise for truecolor systems, Microwindows converts the RGB value to
|
a 5/5/5 15-bit or 5/6/5 16 bit truecolor value. For 8bpp truecolor displays, the RGB
|
a 5/5/5 15-bit or 5/6/5 16 bit truecolor value. For 8bpp truecolor displays, the RGB
|
value is converted to 3/3/2. For palletized displays, the GdFindNearestColor
|
value is converted to 3/3/2. For palletized displays, the GdFindNearestColor
|
function is called to convert the RGB color to the nearest palette index in the current
|
function is called to convert the RGB color to the nearest palette index in the current
|
system palette. GdFindNearestColor uses a weighted distance-cubed method to find the
|
system palette. GdFindNearestColor uses a weighted distance-cubed method to find the
|
palette value nearest to the requested color, and returns it. Standard palettes for
|
palette value nearest to the requested color, and returns it. Standard palettes for
|
1, 2, 4 and 8bpp are included in the files devpal1, devpal2, devpal4 and devpal8.c.
|
1, 2, 4 and 8bpp are included in the files devpal1, devpal2, devpal4 and devpal8.c.
|
These palettes associate an RGB value with an index, but may be overwritten.</p>
|
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
|
<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
|
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. There is a single
|
screen driver SetPalette entry point to set the hardware palette. There is a single
|
global variable, gr_firstuserpalentry, that contains the index of the next available
|
global variable, gr_firstuserpalentry, that contains the index of the next available
|
system palette entry. Initially, this is set to 24. Thus, systems with less
|
system palette entry. Initially, this is set to 24. Thus, systems with less
|
than 24 total palette entries will never have an available palette entry to remap.
|
than 24 total palette entries will never have an available palette entry to remap.
|
On systems that do, like 256 color systems, then images requiring more color entries keep
|
On systems that do, like 256 color systems, then images requiring more color entries keep
|
calling GdSetPalette until the system palette is full. To reset marker, the function
|
calling GdSetPalette until the system palette is full. To reset marker, the function
|
GdResetPalette is called. This allows upper level API's to distinguish between
|
GdResetPalette is called. This allows upper level API's to distinguish between
|
different images and force the system palette to be rewritten.</p>
|
different images and force the system palette to be rewritten.</p>
|
|
|
<h3> 2.1.10 Image Drawing</h3>
|
<h3> 2.1.10 Image Drawing</h3>
|
|
|
<p>Microwindows supports two styles of images, monochrome and palettized. Monochrome
|
<p>Microwindows supports two styles of images, monochrome and palettized. Monochrome
|
images are specified with an IMAGEBITS structure, which is an array of words with 1 bits
|
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. The IMAGEBITS bits are
|
specifying the foreground color and 0 bits the background. The IMAGEBITS bits are
|
short-word padded to the width of the bitmap. The GdBitmap routine draws monochrome
|
short-word padded to the width of the bitmap. The GdBitmap routine draws monochrome
|
bitmaps, similar to GdText, by drawing all the 1 bits in the foreground color, and the 0
|
bitmaps, similar to GdText, by drawing all the 1 bits in the foreground color, and the 0
|
bits in the background color if the "use background" set by GdUseBackground is
|
bits in the background color if the "use background" set by GdUseBackground is
|
TRUE.</p>
|
TRUE.</p>
|
|
|
<p>Color bitmaps are specified using a 1, 4 or 8bpp image palette, and an array of indices
|
<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
|
into this palette, all stuffed into an IMAGEHDR structure, and drawn via
|
GdDrawImage. First, the system creates a conversion palette by calling
|
GdDrawImage. First, the system creates a conversion palette by calling
|
GdMakePaletteConversionTable, which converts the images' palette entries into system
|
GdMakePaletteConversionTable, which converts the images' palette entries into system
|
indices. At the same time, the system attempts to increase the system palette if
|
indices. At the same time, the system attempts to increase the system palette if
|
necessary by calling the GdSetPalette function described above. At the end of this
|
necessary by calling the GdSetPalette function described above. At the end of this
|
operation, the image has a converted palette which necessarily corresponds to the system
|
operation, the image has a converted palette which necessarily corresponds to the system
|
palette. In the case of truecolor hardware, the image's palette entries are
|
palette. In the case of truecolor hardware, the image's palette entries are
|
converted to hardware truecolor pixel values, and output directly.</p>
|
converted to hardware truecolor pixel values, and output directly.</p>
|
|
|
<p>After converting the image color entries the GdDrawImage determines the whether the
|
<p>After converting the image color entries the GdDrawImage determines the whether the
|
image is clipped, and outputs the image, pixel by pixel. In the future, a blitting
|
image is clipped, and outputs the image, pixel by pixel. In the future, a blitting
|
routine could be used for faster image drawing.</p>
|
routine could be used for faster image drawing.</p>
|
|
|
<h3> 2.1.11 Blitting</h3>
|
<h3> 2.1.11 Blitting</h3>
|
|
|
<p>Blitting functionality is required in the screen driver for offscreen drawing
|
<p>Blitting functionality is required in the screen driver for offscreen drawing
|
capability, discussed earlier in the screen drivers section. The engine function
|
capability, discussed earlier in the screen drivers section. The engine function
|
GdBlit allows upper level APIs to implement copy operations from offscreen memory to the
|
GdBlit allows upper level APIs to implement copy operations from offscreen memory to the
|
display, or vice versa. The blit format is driver specific, and generally only works
|
display, or vice versa. The blit format is driver specific, and generally only works
|
for memory images created by the screen driver during runtime. The upper level APIs
|
for memory images created by the screen driver during runtime. The upper level APIs
|
implement this by allocating a new SCREENDRIVER structure, copying an existing
|
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
|
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
|
setting the PSF_MEMORY bit, which indicates to the display driver that this is now an
|
offscreen surface. Any subsequent calls to the engine routines then draw onto this
|
offscreen surface. Any subsequent calls to the engine routines then draw onto this
|
surface. When it is desired to copy the offscreen surface back to the physical
|
surface. When it is desired to copy the offscreen surface back to the physical
|
display, the GdBlit routine is called. Currently, only SRCCOPY operations are
|
display, the GdBlit routine is called. Currently, only SRCCOPY operations are
|
performed, but future plans will add blitting opcodes.</p>
|
performed, but future plans will add blitting opcodes.</p>
|
|
|
<p> </p>
|
<p> </p>
|
|
|
<h3>3. Microwindows API</h3>
|
<h3>3. Microwindows API</h3>
|
|
|
<h3> 3.1 Message-passing
|
<h3> 3.1 Message-passing
|
architecture</h3>
|
architecture</h3>
|
|
|
<p>The fundamental communications mechanism in the Microwindows API is the message.
|
<p>The fundamental communications mechanism in the Microwindows API is the message.
|
A message consists of a well-known message number, and two parameters, known as wParam and
|
A message consists of a well-known message number, and two parameters, known as wParam and
|
lParam. Messages are stored in an application's message-queue, and retrieved via the
|
lParam. Messages are stored in an application's message-queue, and retrieved via the
|
GetMessage function. The application blocks while waiting for a message. There
|
GetMessage function. The application blocks while waiting for a message. There
|
are messages that correspond to hardware events, like WM_CHAR for keyboard input or
|
are messages that correspond to hardware events, like WM_CHAR for keyboard input or
|
WM_LBUTTONDOWN for mouse button down. In addtiion, events signaling window creation
|
WM_LBUTTONDOWN for mouse button down. In addtiion, events signaling window creation
|
and destruction WM_CREATE and WM_DESTROY are sent. In most cases, a message is
|
and destruction WM_CREATE and WM_DESTROY are sent. In most cases, a message is
|
associated with a window, identified as an HWND. After retrieving the message, the
|
associated with a window, identified as an HWND. After retrieving the message, the
|
application sends the message to the associated window's handling procedure using
|
application sends the message to the associated window's handling procedure using
|
DispatchMessage. When a window class is created, it's associated message handling
|
DispatchMessage. When a window class is created, it's associated message handling
|
procedure is specified, so the system knows where to send the message.</p>
|
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
|
<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,
|
sending messages on all sorts of events, like window creation, painting needed, moving,
|
etc. By default, the associated window handling function gets a "first
|
etc. By default, the associated window handling function gets a "first
|
pass" at the message, and then calls the DefWindowProc function, which handles
|
pass" at the message, and then calls the DefWindowProc function, which handles
|
default actions for all the messages. In this way, all windows can behave the same
|
default actions for all the messages. In this way, all windows can behave the same
|
way when dragged, etc, unless specifically overridden by the user. Major window
|
way when dragged, etc, unless specifically overridden by the user. Major window
|
management policies can be redefined by merely re-implementing DefWindowProc, rather than
|
management policies can be redefined by merely re-implementing DefWindowProc, rather than
|
making changes throughout the system.</p>
|
making changes throughout the system.</p>
|
|
|
<p>The following functions deal with messages directly:</p>
|
<p>The following functions deal with messages directly:</p>
|
|
|
<p>
|
<p>
|
SendMessage
|
SendMessage
|
Send a message directly to a window<br>
|
Send a message directly to a window<br>
|
|
|
PostMessage
|
PostMessage
|
Queue a message on the application's message queue for later dispatch<br>
|
Queue a message on the application's message queue for later dispatch<br>
|
PostQuitMessage
|
PostQuitMessage
|
Queue a WM_QUIT message telling the application to terminate when read<br>
|
Queue a WM_QUIT message telling the application to terminate when read<br>
|
|
|
GetMessage
|
GetMessage
|
Block until a message is queued for this application<br>
|
Block until a message is queued for this application<br>
|
TranslateMessage
|
TranslateMessage
|
Translate up/down keystrokes to WM_CHAR messages<br>
|
Translate up/down keystrokes to WM_CHAR messages<br>
|
|
|
DispatchMessage Send a
|
DispatchMessage Send a
|
messages to it's associated window procedure</p>
|
messages to it's associated window procedure</p>
|
|
|
<p>A Microwindows application's entry point is the function WinMain, rather than main.</p>
|
<p>A Microwindows application's entry point is the function WinMain, rather than main.</p>
|
|
|
<h3> 3.2 Window creation and
|
<h3> 3.2 Window creation and
|
destruction</h3>
|
destruction</h3>
|
|
|
<p>The basic unit of screen organization in Microwindows API is the window. Windows
|
<p>The basic unit of screen organization in Microwindows API is the window. Windows
|
describe an area of the screen to draw onto, as well as an associate "window
|
describe an area of the screen to draw onto, as well as an associate "window
|
procedure" for handling messages destined for this window. Applications
|
procedure" for handling messages destined for this window. Applications
|
programmers can create windows from pre-defined classes, like buttons, edit boxes, and the
|
programmers can create windows from pre-defined classes, like buttons, edit boxes, and the
|
like, or define their own window classes. In both cases, the method of creating and
|
like, or define their own window classes. In both cases, the method of creating and
|
communicating with the windows remains exactly the same. The following functions
|
communicating with the windows remains exactly the same. The following functions
|
deal with window registration, creation, and destruction:</p>
|
deal with window registration, creation, and destruction:</p>
|
|
|
<p>
|
<p>
|
RegisterClass
|
RegisterClass
|
Define a new window class name and associated window procedure<br>
|
Define a new window class name and associated window procedure<br>
|
|
|
UnRegisterClass Undefine
|
UnRegisterClass Undefine
|
a window class<br>
|
a window class<br>
|
CreateWindowEx Create
|
CreateWindowEx Create
|
an instance of a window of a certain class<br>
|
an instance of a window of a certain class<br>
|
|
|
DestroyWindow Destroy a
|
DestroyWindow Destroy a
|
window instance</p>
|
window instance</p>
|
|
|
<p>The WM_CREATE message is just after window creation, before returning from
|
<p>The WM_CREATE message is just after window creation, before returning from
|
CreateWindowEx. The WM_DESTROY message is sent just before destroying a window with
|
CreateWindowEx. The WM_DESTROY message is sent just before destroying a window with
|
DestroyWindow. </p>
|
DestroyWindow. </p>
|
|
|
<p>When a window is registered, extra bytes can be allocated to the window structure when
|
<p>When a window is registered, extra bytes can be allocated to the window structure when
|
created. The GetWindowLong, GetWindowWord, SetWindowLong and SetWindowWord
|
created. The GetWindowLong, GetWindowWord, SetWindowLong and SetWindowWord
|
manipulate these bytes. In addition, a fixed number of extra bytes per window class
|
manipulate these bytes. In addition, a fixed number of extra bytes per window class
|
can be allocated on registration and retrieved via the GetClassLong function.</p>
|
can be allocated on registration and retrieved via the GetClassLong function.</p>
|
|
|
<h3> 3.3 Window showing,
|
<h3> 3.3 Window showing,
|
hiding and moving</h3>
|
hiding and moving</h3>
|
|
|
<p>The ShowWindow function allows windows to be made visible or hidden. In addition,
|
<p>The ShowWindow function allows windows to be made visible or hidden. In addition,
|
this can be specified during the creation of the window, through CreateWindowEx.
|
this can be specified during the creation of the window, through CreateWindowEx.
|
MoveWindow is called to change a window's position or size. A WM_MOVE message is
|
MoveWindow is called to change a window's position or size. A WM_MOVE message is
|
sent if the window's position changes, and WM_SIZE is sent on size changes.</p>
|
sent if the window's position changes, and WM_SIZE is sent on size changes.</p>
|
|
|
<h3> 3.4 Window painting</h3>
|
<h3> 3.4 Window painting</h3>
|
|
|
<p>The Microwindows system determines when a window needs to be initially painted or
|
<p>The Microwindows system determines when a window needs to be initially painted or
|
repainted as the result of other window movement, and a WM_PAINT message is sent to the
|
repainted as the result of other window movement, and a WM_PAINT message is sent to the
|
associated window procedure. At this point, it's up the the application to use the
|
associated window procedure. At this point, it's up the the application to use the
|
graphics primitives available to paint the window, described below. Microwindows
|
graphics primitives available to paint the window, described below. Microwindows
|
keeps track of a windows' "update" region, and sends WM_PAINT whenever the
|
keeps track of a windows' "update" region, and sends WM_PAINT whenever the
|
region is non-empty. For speed reasons, the WM_PAINT message is only sent when there
|
region is non-empty. For speed reasons, the WM_PAINT message is only sent when there
|
are no other messages in the application's queue. This allows the application to
|
are no other messages in the application's queue. This allows the application to
|
repaint in one, rather than possibly many, steps. To force a repaint rather than
|
repaint in one, rather than possibly many, steps. To force a repaint rather than
|
waiting, the UpdateWindow function can be called. The InvalidateRect function
|
waiting, the UpdateWindow function can be called. The InvalidateRect function
|
specifies a rectangle to add to the update region, causing a subsequent WM_PAINT.</p>
|
specifies a rectangle to add to the update region, causing a subsequent WM_PAINT.</p>
|
|
|
<p>The window title is automatically painted and is set with the SetWindowText function,
|
<p>The window title is automatically painted and is set with the SetWindowText function,
|
and retrieved with the GetWindowText function.</p>
|
and retrieved with the GetWindowText function.</p>
|
|
|
<h3> 3.4.1 Client and screen
|
<h3> 3.4.1 Client and screen
|
coordinates</h3>
|
coordinates</h3>
|
|
|
<p>Every window is drawn on the screen using the device global screen coordinate system
|
<p>Every window is drawn on the screen using the device global screen coordinate system
|
for absolute reference to any pixel on the screen. The Microwindows API allows
|
for absolute reference to any pixel on the screen. The Microwindows API allows
|
applications programmers to be concerned with only the relative coordinates from the upper
|
applications programmers to be concerned with only the relative coordinates from the upper
|
left portion of their window, not including the title bar and 3d effects. This
|
left portion of their window, not including the title bar and 3d effects. This
|
coordinate system is called "client coordinates." As will be explained
|
coordinate system is called "client coordinates." As will be explained
|
below, the Microwindows programmer has the option of getting a device context in either
|
below, the Microwindows programmer has the option of getting a device context in either
|
screen or client coordinates. If device coordinates are specified, then the
|
screen or client coordinates. If device coordinates are specified, then the
|
coordinate system is device-based and includes the title area and 3d areas of the
|
coordinate system is device-based and includes the title area and 3d areas of the
|
window. Otherwise, the drawable region is clipped to just that area that is
|
window. Otherwise, the drawable region is clipped to just that area that is
|
reserved by the system for the application's drawing. The GetClientRect and
|
reserved by the system for the application's drawing. The GetClientRect and
|
GetWindowRect functions return client or screen coordinates for the passed window.
|
GetWindowRect functions return client or screen coordinates for the passed window.
|
ClientToScreen and ScreenToClient can be called to translate between window coordinate
|
ClientToScreen and ScreenToClient can be called to translate between window coordinate
|
systems.</p>
|
systems.</p>
|
|
|
<h3> 3.4.2 Device contexts</h3>
|
<h3> 3.4.2 Device contexts</h3>
|
|
|
<p>An applications programmer must obtain a "device context" before calling any
|
<p>An applications programmer must obtain a "device context" before calling any
|
graphics drawing API functions. As explained above, this specifies to the system
|
graphics drawing API functions. As explained above, this specifies to the system
|
which window and what coordinate system are desired, so that these don't have to be passed
|
which window and what coordinate system are desired, so that these don't have to be passed
|
to every graphics function. In addition, various other attributes like foreground
|
to every graphics function. In addition, various other attributes like foreground
|
and background color are also set in a device context, so that these parameters don't have
|
and background color are also set in a device context, so that these parameters don't have
|
to be specified for every graphics operation. The device context selects the
|
to be specified for every graphics operation. The device context selects the
|
appropriate clipping region based on the window specified and the coordinate system.
|
appropriate clipping region based on the window specified and the coordinate system.
|
When a device context is obtained, various graphics values are set to default values.</p>
|
When a device context is obtained, various graphics values are set to default values.</p>
|
|
|
<p>To obtain a client device context, call GetDC. To obtain a screen device context,
|
<p>To obtain a client device context, call GetDC. To obtain a screen device context,
|
required when drawing onto title bars and the like, call GetWindowDC. In addition,
|
required when drawing onto title bars and the like, call GetWindowDC. In addition,
|
fancy clipping operations and child/sibling window clipping can be specified if GetDCEx is
|
fancy clipping operations and child/sibling window clipping can be specified if GetDCEx is
|
called. When finished drawing, the ReleaseDC function must be called to deallocate
|
called. When finished drawing, the ReleaseDC function must be called to deallocate
|
the DC.</p>
|
the DC.</p>
|
|
|
<p>On receipt of the WM_PAINT message, two special calls, BeginPaint and EndPaint are
|
<p>On receipt of the WM_PAINT message, two special calls, BeginPaint and EndPaint are
|
called, that serve as replacements to the GetDC/ReleaseDC functions. These functions
|
called, that serve as replacements to the GetDC/ReleaseDC functions. These functions
|
essentially allocate a DC but also validate the update region so that no subsequent
|
essentially allocate a DC but also validate the update region so that no subsequent
|
WM_PAINT messages are generated. BeginPaint also combines the update region and the
|
WM_PAINT messages are generated. BeginPaint also combines the update region and the
|
clipping region so that user output will only occur where previously invalidated.</p>
|
clipping region so that user output will only occur where previously invalidated.</p>
|
|
|
<h3> 3.4.3 Graphics drawing
|
<h3> 3.4.3 Graphics drawing
|
API</h3>
|
API</h3>
|
|
|
<p>There are many graphics drawing API's in the Microwindows API. Following is a
|
<p>There are many graphics drawing API's in the Microwindows API. Following is a
|
list, most of these match up to the engine GdXXX functions discussed in section 2.</p>
|
list, most of these match up to the engine GdXXX functions discussed in section 2.</p>
|
|
|
<p>
|
<p>
|
SetTextColor
|
SetTextColor
|
Set the foreground text color in a DC<br>
|
Set the foreground text color in a DC<br>
|
|
|
SetBkColor
|
SetBkColor
|
Set the background color in a DC<br>
|
Set the background color in a DC<br>
|
|
|
GetSysColor
|
GetSysColor
|
Get the system color defined for the current look and feel scheme<br>
|
Get the system color defined for the current look and feel scheme<br>
|
|
|
SetBkMode
|
SetBkMode
|
Set the use background flag in a DC<br>
|
Set the use background flag in a DC<br>
|
|
|
SetROP2
|
SetROP2
|
Set the drawing mode (XOR, SET, etc) for drawing<br>
|
Set the drawing mode (XOR, SET, etc) for drawing<br>
|
|
|
SetPixel
|
SetPixel
|
Draw a pixel in the current fg color<br>
|
Draw a pixel in the current fg color<br>
|
|
|
MoveToEx
|
MoveToEx
|
Prepare to draw a line<br>
|
Prepare to draw a line<br>
|
|
|
LineTo
|
LineTo
|
Draw a line from the last location to this one in the current fg color<br>
|
Draw a line from the last location to this one in the current fg color<br>
|
|
|
Rectangle
|
Rectangle
|
Draw a rectangle in the current pen color<br>
|
Draw a rectangle in the current pen color<br>
|
|
|
FillRect
|
FillRect
|
Fill a rectangle with the current brush color<br>
|
Fill a rectangle with the current brush color<br>
|
|
|
TextOut
|
TextOut
|
Draw text in the current fg/bg color<br>
|
Draw text in the current fg/bg color<br>
|
|
|
ExtTextOut
|
ExtTextOut
|
Draw text in the current fg/bg color<br>
|
Draw text in the current fg/bg color<br>
|
|
|
DrawText
|
DrawText
|
Draw text or compute text height and width sizes<br>
|
Draw text or compute text height and width sizes<br>
|
|
|
DrawDIB
|
DrawDIB
|
Draw a color bitmap<br>
|
Draw a color bitmap<br>
|
|
|
SelectObject
|
SelectObject
|
Select a pen, brush or font to use in a DC<br>
|
Select a pen, brush or font to use in a DC<br>
|
|
|
GetStockObject
|
GetStockObject
|
Get a predefined standard pen, brush or font<br>
|
Get a predefined standard pen, brush or font<br>
|
|
|
CreatePen
|
CreatePen
|
Create a pen of a certain color<br>
|
Create a pen of a certain color<br>
|
|
|
CreateSolidBrush
|
CreateSolidBrush
|
Create a brush of a certain color<br>
|
Create a brush of a certain color<br>
|
CreateCompatibleBitmap Create an offscreen area to draw onto<br>
|
CreateCompatibleBitmap Create an offscreen area to draw onto<br>
|
|
|
DeleteObject
|
DeleteObject
|
Delete a pen, brush or bitmap<br>
|
Delete a pen, brush or bitmap<br>
|
CreateCompatibleDC Create an
|
CreateCompatibleDC Create an
|
offscreen DC<br>
|
offscreen DC<br>
|
|
|
DeleteDC
|
DeleteDC
|
Delete an offscreen DC<br>
|
Delete an offscreen DC<br>
|
|
|
BitBlit
|
BitBlit
|
Copy from one bitmap in a DC to another<br>
|
Copy from one bitmap in a DC to another<br>
|
GetSystemPaletteEntries Get the currently in-use
|
GetSystemPaletteEntries Get the currently in-use
|
system palette entries<br>
|
system palette entries<br>
|
</p>
|
</p>
|
|
|
<h3> 3.5 Utility functions</h3>
|
<h3> 3.5 Utility functions</h3>
|
|
|
<p>A number of routines are provided for various purposes, described below. In
|
<p>A number of routines are provided for various purposes, described below. In
|
addition, Microwindows currently exports some helper routines, named WndXXX, that are
|
addition, Microwindows currently exports some helper routines, named WndXXX, that are
|
useful but subject to change. These are detailed following:</p>
|
useful but subject to change. These are detailed following:</p>
|
|
|
<p>
|
<p>
|
WndSetDesktopWallpaper
|
WndSetDesktopWallpaper
|
Set the desktop background image<br>
|
Set the desktop background image<br>
|
|
|
WndSetCursor
|
WndSetCursor
|
Set the cursor for a window<br>
|
Set the cursor for a window<br>
|
|
|
WndRaiseWindow
|
WndRaiseWindow
|
Raise a window's z-order<br>
|
Raise a window's z-order<br>
|
|
|
WndLowerWindow
|
WndLowerWindow
|
Lower a window's z-order<br>
|
Lower a window's z-order<br>
|
|
|
WndGetTopWindow
|
WndGetTopWindow
|
Return the topmost window's handle<br>
|
Return the topmost window's handle<br>
|
|
|
WndRegisterFdInput
|
WndRegisterFdInput
|
Register to send a message when file descriptor has read data available<br>
|
Register to send a message when file descriptor has read data available<br>
|
|
|
WndUnregisterFdInput
|
WndUnregisterFdInput
|
Unregister file descriptor for read data messages</p>
|
Unregister file descriptor for read data messages</p>
|
|
|
<p>
|
<p>
|
GetTickCount
|
GetTickCount
|
Return # milliseconds elapsed since startup<br>
|
Return # milliseconds elapsed since startup<br>
|
|
|
Sleep
|
Sleep
|
Delay processing for specified milliseconds</p>
|
Delay processing for specified milliseconds</p>
|
|
|
<h3> 3.5.1 Setting window
|
<h3> 3.5.1 Setting window
|
focus</h3>
|
focus</h3>
|
|
|
<p>The SetFocus routine is used to pass keyboard focus from one window to another.
|
<p>The SetFocus routine is used to pass keyboard focus from one window to another.
|
Keystrokes are always sent to the window with focus. The WM_SETFOCUS and
|
Keystrokes are always sent to the window with focus. The WM_SETFOCUS and
|
WM_KILLFOCUS messages are sent to windows just receiving and losing focus. The
|
WM_KILLFOCUS messages are sent to windows just receiving and losing focus. The
|
GetActiveWindow routines returns the first non-child ancestor of the focus window, which
|
GetActiveWindow routines returns the first non-child ancestor of the focus window, which
|
is the window that is currently highlighted. The GetDesktopWindow routine returns
|
is the window that is currently highlighted. The GetDesktopWindow routine returns
|
the window handle of the desktop window.</p>
|
the window handle of the desktop window.</p>
|
|
|
<h3> 3.5.2 Mouse capture</h3>
|
<h3> 3.5.2 Mouse capture</h3>
|
|
|
<p>Normally, Microwindows sends WM_MOUSEMOVE messages to the window the mouse is currently
|
<p>Normally, Microwindows sends WM_MOUSEMOVE messages to the window the mouse is currently
|
moving over. If desired, the 7applications programmer can "capture" the
|
moving over. If desired, the 7applications programmer can "capture" the
|
mouse and receive all mouse move messages by calling SetCapture. ReleaseCapture
|
mouse and receive all mouse move messages by calling SetCapture. ReleaseCapture
|
returns the processing to normal. In addition, the GetCapture function will return
|
returns the processing to normal. In addition, the GetCapture function will return
|
the window with capture, if any.</p>
|
the window with capture, if any.</p>
|
|
|
<h3> 3.5.3 Rectangle and
|
<h3> 3.5.3 Rectangle and
|
Region management</h3>
|
Region management</h3>
|
|
|
<p>There are a number of functions that are used for rectangles and regions.
|
<p>There are a number of functions that are used for rectangles and regions.
|
Following is the group:</p>
|
Following is the group:</p>
|
|
|
<p>
|
<p>
|
SetRect
|
SetRect
|
Define a rectangle structure<br>
|
Define a rectangle structure<br>
|
|
|
SetRectEmpty
|
SetRectEmpty
|
Define an empty rectangle<br>
|
Define an empty rectangle<br>
|
|
|
CopyRect
|
CopyRect
|
Copy a rectangle<br>
|
Copy a rectangle<br>
|
|
|
IsRectEmpty
|
IsRectEmpty
|
Return TRUE if empty rectangle<br>
|
Return TRUE if empty rectangle<br>
|
|
|
InflateRect
|
InflateRect
|
Enlarge a rectangle<br>
|
Enlarge a rectangle<br>
|
|
|
OffsetRect
|
OffsetRect
|
Move a rectangle<br>
|
Move a rectangle<br>
|
|
|
PtInRect
|
PtInRect
|
Determine if a point is in a rectangle<br>
|
Determine if a point is in a rectangle<br>
|
</p>
|
</p>
|
|
|
<p>A large number of region management routines are defined and declared in the winrgn.c
|
<p>A large number of region management routines are defined and declared in the winrgn.c
|
file. </p>
|
file. </p>
|
|
|
<p> </p>
|
<p> </p>
|
|
|
<h3>4. Nano-X API</h3>
|
<h3>4. Nano-X API</h3>
|
|
|
<p>The Nano-X API was originally designed by David Bell, with his mini-x package for the
|
<p>The Nano-X API was originally designed by David Bell, with his mini-x package for the
|
MINIX operating system. Nano-X is now running on top of the core graphics engine
|
MINIX operating system. Nano-X is now running on top of the core graphics engine
|
routines discussed in section 2. Nano-X was designed for a client/server
|
routines discussed in section 2. Nano-X was designed for a client/server
|
environment, as no pointers to structures are passed to the API routines, instead a call
|
environment, as no pointers to structures are passed to the API routines, instead a call
|
is made to the server to get an ID, which is passed to the API functions and is used to
|
is made to the server to get an ID, which is passed to the API functions and is used to
|
reference the data on the server. In addition, Nano-X is not message-oriented,
|
reference the data on the server. In addition, Nano-X is not message-oriented,
|
instead modeled after the X protocol which was designed for speed on systems where the
|
instead modeled after the X protocol which was designed for speed on systems where the
|
client and server machines were different.</p>
|
client and server machines were different.</p>
|
|
|
<h3> 4.1 Client/Server model</h3>
|
<h3> 4.1 Client/Server model</h3>
|
|
|
<p>In Nano-X, there are two linking mechanisms that can be used for applications
|
<p>In Nano-X, there are two linking mechanisms that can be used for applications
|
programs. In the client/server model, the application program is linked with a
|
programs. In the client/server model, the application program is linked with a
|
client library that forms a UNIX socket connection with the Nano-X server, a separate
|
client library that forms a UNIX socket connection with the Nano-X server, a separate
|
process. Each application then communicates all parameters over the UNIX
|
process. Each application then communicates all parameters over the UNIX
|
socket. For speed and debugging, it is sometimes desirable to link the application
|
socket. For speed and debugging, it is sometimes desirable to link the application
|
directly with the server. In this case, a stub library is provided that just passes
|
directly with the server. In this case, a stub library is provided that just passes
|
the client routines parameters to the server function.</p>
|
the client routines parameters to the server function.</p>
|
|
|
<p>The Nano-X naming convention uses GrXXX to designate client side callable routines,
|
<p>The Nano-X naming convention uses GrXXX to designate client side callable routines,
|
with a marshalling layer implemented in the files nanox/client.c, nanox/nxproto.c, and
|
with a marshalling layer implemented in the files nanox/client.c, nanox/nxproto.c, and
|
nanox/srvnet.c. The client/server network layer currently uses a fast approach to
|
nanox/srvnet.c. The client/server network layer currently uses a fast approach to
|
marshalling the data from the Gr routine into a buffer, and sent all at once to the
|
marshalling the data from the Gr routine into a buffer, and sent all at once to the
|
receiving stubs in nanox/srvnet.c, before calling the server drawing routines in
|
receiving stubs in nanox/srvnet.c, before calling the server drawing routines in
|
nanox/srvfunc.c. In the linked application scenario, the Nano-X client links
|
nanox/srvfunc.c. In the linked application scenario, the Nano-X client links
|
directly with the functions in nanox/srvfunc.c, and the nanox/client.c and nanox/srvnet.c
|
directly with the functions in nanox/srvfunc.c, and the nanox/client.c and nanox/srvnet.c
|
files are not required.</p>
|
files are not required.</p>
|
|
|
<p>A Nano-X application must call GrOpen before calling any other Nano-X function, and
|
<p>A Nano-X application must call GrOpen before calling any other Nano-X function, and
|
call GrClose before exiting. These functions establish a connection with the server
|
call GrClose before exiting. These functions establish a connection with the server
|
when running the client/server model, and return an error status if the server can't be
|
when running the client/server model, and return an error status if the server can't be
|
found or isn't currently running.</p>
|
found or isn't currently running.</p>
|
|
|
<p>The main loop in a Nano-X application is to create some windows, define the events you
|
<p>The main loop in a Nano-X application is to create some windows, define the events you
|
want with GrSelectEvents, and then wait for an event with GrGetNextEvent. If it is
|
want with GrSelectEvents, and then wait for an event with GrGetNextEvent. If it is
|
desired to merely check for an event, but not wait if there isn't one, GrCheckNextEvent
|
desired to merely check for an event, but not wait if there isn't one, GrCheckNextEvent
|
can be used. GrPeekEvent can be used to examine the next event without removing it
|
can be used. GrPeekEvent can be used to examine the next event without removing it
|
from the queue.</p>
|
from the queue.</p>
|
|
|
<p>When running Nano-X programs in the client/server model, it's currently necessary to
|
<p>When running Nano-X programs in the client/server model, it's currently necessary to
|
run the server first in a shell script, then wait a second, then run the
|
run the server first in a shell script, then wait a second, then run the
|
application. Some rewriting is needed to fire up the server when an application
|
application. Some rewriting is needed to fire up the server when an application
|
requires it, I believe.</p>
|
requires it, I believe.</p>
|
|
|
<h3> 4.2 Events</h3>
|
<h3> 4.2 Events</h3>
|
|
|
<p>Nano-X applications specify which events they would like to see on a per-window basis
|
<p>Nano-X applications specify which events they would like to see on a per-window basis
|
using GrSelectEvents. Then, in the main loop, the application calls GrGetNextEvent
|
using GrSelectEvents. Then, in the main loop, the application calls GrGetNextEvent
|
and waits for one of the event types selected for in any of the windows. Typically,
|
and waits for one of the event types selected for in any of the windows. Typically,
|
a switch statement is used to determine what to do after receiving the event. This
|
a switch statement is used to determine what to do after receiving the event. This
|
is similar to the Microwindows's API GetMessage/DispatchMessage loop, except that in
|
is similar to the Microwindows's API GetMessage/DispatchMessage loop, except that in
|
Microwindows API, DispatchMessage is used to send the event to the window's handling
|
Microwindows API, DispatchMessage is used to send the event to the window's handling
|
procedure, typically located with the window object. In Nano-X, all the event
|
procedure, typically located with the window object. In Nano-X, all the event
|
handling code for each of the windows must be placed together in the main event loop,
|
handling code for each of the windows must be placed together in the main event loop,
|
there is no automatic dispatching. Of course, widget sets serve to provide
|
there is no automatic dispatching. Of course, widget sets serve to provide
|
object-orientation, but this is in addition to the Nano-X API.</p>
|
object-orientation, but this is in addition to the Nano-X API.</p>
|
|
|
<p>Following are the event types that Nano-X programs can recieve:</p>
|
<p>Following are the event types that Nano-X programs can recieve:</p>
|
|
|
<p> GR_EVENT_TYPE_NONE, ERROR, EXPOSURE, BUTTON_DOWN, BUTTON_UP,
|
<p> GR_EVENT_TYPE_NONE, ERROR, EXPOSURE, BUTTON_DOWN, BUTTON_UP,
|
MOUSE_ENTER, MOUSE_EXIT, MOUSE_MOTION, MOUSE_POSITION, KEY_UP, KEY_DOWN, FOCUS_IN,
|
MOUSE_ENTER, MOUSE_EXIT, MOUSE_MOTION, MOUSE_POSITION, KEY_UP, KEY_DOWN, FOCUS_IN,
|
FOCUS_OUT, FDINPUT</p>
|
FOCUS_OUT, FDINPUT</p>
|
|
|
<p>Note that Nano-X API provides mouse enter and exit events whereas Microwindows API does
|
<p>Note that Nano-X API provides mouse enter and exit events whereas Microwindows API does
|
not. Also, the exposure events are calculated and sent immediately by the server,
|
not. Also, the exposure events are calculated and sent immediately by the server,
|
and not combined and possibly delayed for better paint throughput as in the Microwindows
|
and not combined and possibly delayed for better paint throughput as in the Microwindows
|
API.</p>
|
API.</p>
|
|
|
<h3> 4.3 Window creation and destruction</h3>
|
<h3> 4.3 Window creation and destruction</h3>
|
|
|
<p>Windows are created in Nano-X with the GrNewWindow function. Windows can be
|
<p>Windows are created in Nano-X with the GrNewWindow function. Windows can be
|
specified to be input-only, in which case the GrNewInputWindow function is used. The
|
specified to be input-only, in which case the GrNewInputWindow function is used. The
|
window border and color is specified in these calls, but will have to be rewritten when
|
window border and color is specified in these calls, but will have to be rewritten when
|
fancier window dressings are required. The return value from these functions is an
|
fancier window dressings are required. The return value from these functions is an
|
ID that can be used in later calls to get a graphics context or perform window
|
ID that can be used in later calls to get a graphics context or perform window
|
manipulation.</p>
|
manipulation.</p>
|
|
|
<h3> 4.4 Window showing,
|
<h3> 4.4 Window showing,
|
hiding and moving</h3>
|
hiding and moving</h3>
|
|
|
<p>Windows are shown by calling the GrMapWindow function, and hidden using
|
<p>Windows are shown by calling the GrMapWindow function, and hidden using
|
GrUnmapWindow. Mapping a window is required for all ancestors of a window in order
|
GrUnmapWindow. Mapping a window is required for all ancestors of a window in order
|
for it to be visible. The GrRaiseWindow call is used to raise the Z order of a
|
for it to be visible. The GrRaiseWindow call is used to raise the Z order of a
|
window, while GrLowerWindow is used to lower the Z order. GrMoveWindow is used to
|
window, while GrLowerWindow is used to lower the Z order. GrMoveWindow is used to
|
change the position of a window, and GrResizeWindow is used to resize a window.</p>
|
change the position of a window, and GrResizeWindow is used to resize a window.</p>
|
|
|
<h3> 4.5 Drawing to a window</h3>
|
<h3> 4.5 Drawing to a window</h3>
|
|
|
<p>Nano-X requires both a window ID and a graphics context ID in order to draw to a
|
<p>Nano-X requires both a window ID and a graphics context ID in order to draw to a
|
window. Nano-X sends expose events to the application when a window needs to be
|
window. Nano-X sends expose events to the application when a window needs to be
|
redrawn. Unlike the Microwindows API, Nano-X clients are typically required to
|
redrawn. Unlike the Microwindows API, Nano-X clients are typically required to
|
create their drawing graphics contexts early on and keep them for the duration of the
|
create their drawing graphics contexts early on and keep them for the duration of the
|
application. Like Microwindows though, the graphics contexts record information like
|
application. Like Microwindows though, the graphics contexts record information like
|
the current background and foreground colors so they don't have to be specified in every
|
the current background and foreground colors so they don't have to be specified in every
|
graphics API call.</p>
|
graphics API call.</p>
|
|
|
<h3> 4.5.1 Graphics contexts</h3>
|
<h3> 4.5.1 Graphics contexts</h3>
|
|
|
<p>To allocate a graphics context for a window, call GrNewGC. On termination, call
|
<p>To allocate a graphics context for a window, call GrNewGC. On termination, call
|
GrDestroyGC. GrCopyGC can be used to copy on GC to another. GrGetGCInfo is
|
GrDestroyGC. GrCopyGC can be used to copy on GC to another. GrGetGCInfo is
|
used to retrieve the settings contained in a GC. After creating a graphics context,
|
used to retrieve the settings contained in a GC. After creating a graphics context,
|
the server returns a graphics context ID. This is then used as a parameter in all
|
the server returns a graphics context ID. This is then used as a parameter in all
|
the graphics drawing API functions. In Nano-X programs, the current clipping region
|
the graphics drawing API functions. In Nano-X programs, the current clipping region
|
and window coordinate system aren't stored with the GC, as they are in Microwindows'
|
and window coordinate system aren't stored with the GC, as they are in Microwindows'
|
DCs. This is because, first, Nano-X doesn't support dual coordinate systems for
|
DCs. This is because, first, Nano-X doesn't support dual coordinate systems for
|
drawing to the "window dressing" area versus the "user" area of the
|
drawing to the "window dressing" area versus the "user" area of the
|
window (window and client coordinates in Microwindows). User programs can't draw the
|
window (window and client coordinates in Microwindows). User programs can't draw the
|
border area of the window, only a single color and width can be specified. Although
|
border area of the window, only a single color and width can be specified. Although
|
resembling X, this will have to change, so that widget sets can specify the look and feel
|
resembling X, this will have to change, so that widget sets can specify the look and feel
|
of all aspects of the windows they maintain. Since the clipping region isn't
|
of all aspects of the windows they maintain. Since the clipping region isn't
|
maintained with the graphics context, but instead with the window data structure, Nano-X
|
maintained with the graphics context, but instead with the window data structure, Nano-X
|
applications must specify both a window ID and a graphics context ID when calling any
|
applications must specify both a window ID and a graphics context ID when calling any
|
graphics API function. Because of this, many Nano-X applications allocate all
|
graphics API function. Because of this, many Nano-X applications allocate all
|
graphics contexts in the beginning of the program, and hold them throughout execution,
|
graphics contexts in the beginning of the program, and hold them throughout execution,
|
since the graphics contexts hold only things like foreground color, etc, and no window
|
since the graphics contexts hold only things like foreground color, etc, and no window
|
information. This cannot be done with Microwindows API because the DC's contain
|
information. This cannot be done with Microwindows API because the DC's contain
|
window clipping information and must be released before processing the next message.</p>
|
window clipping information and must be released before processing the next message.</p>
|
|
|
<h3> 4.5.2 Graphics drawing
|
<h3> 4.5.2 Graphics drawing
|
API</h3>
|
API</h3>
|
|
|
<p>Following are the graphics drawing functions available with Nano-X. Like
|
<p>Following are the graphics drawing functions available with Nano-X. Like
|
Microwindows API, these all match up eventually to the graphics engine GdXXX routines.</p>
|
Microwindows API, these all match up eventually to the graphics engine GdXXX routines.</p>
|
|
|
<p>
|
<p>
|
GrGetGCTextSize
|
GrGetGCTextSize
|
Return text width and height information<br>
|
Return text width and height information<br>
|
|
|
GrClearWindow
|
GrClearWindow
|
Clear a window to it's background color<br>
|
Clear a window to it's background color<br>
|
|
|
GrSetGCForeground
|
GrSetGCForeground
|
Set the foreground color in a graphics context<br>
|
Set the foreground color in a graphics context<br>
|
|
|
GrSetGCBackground
|
GrSetGCBackground
|
Set the background color in a graphics context<br>
|
Set the background color in a graphics context<br>
|
GrSetGCUseBackground
|
GrSetGCUseBackground
|
Set the "use background color" in a graphics context<br>
|
Set the "use background color" in a graphics context<br>
|
|
|
GrSetGCMode
|
GrSetGCMode
|
Set the drawing mode<br>
|
Set the drawing mode<br>
|
|
|
GrSetGCFont
|
GrSetGCFont
|
Set the font<br>
|
Set the font<br>
|
|
|
GrPoint
|
GrPoint
|
Draw a point in the passed gc's foreground color<br>
|
Draw a point in the passed gc's foreground color<br>
|
|
|
GrLine
|
GrLine
|
Draw a line in the passed gc's foreground color<br>
|
Draw a line in the passed gc's foreground color<br>
|
|
|
GrRect
|
GrRect
|
Draw a rectangle in passed gc's foreground color<br>
|
Draw a rectangle in passed gc's foreground color<br>
|
|
|
GrFillRect
|
GrFillRect
|
Fill a rectangle with the passed gc's foreground color<br>
|
Fill a rectangle with the passed gc's foreground color<br>
|
|
|
GrEllipse
|
GrEllipse
|
Draw a circle or ellipse with the passed gc's foreground color<br>
|
Draw a circle or ellipse with the passed gc's foreground color<br>
|
|
|
GrFillEllipse
|
GrFillEllipse
|
Fill a circle or ellipse with the passed gc's foreground color<br>
|
Fill a circle or ellipse with the passed gc's foreground color<br>
|
|
|
GrPoly
|
GrPoly
|
Draw a polygon using the passed gc's foreground color<br>
|
Draw a polygon using the passed gc's foreground color<br>
|
|
|
GrFillPoly
|
GrFillPoly
|
Fill a polygon using the passed gc's foreground color<br>
|
Fill a polygon using the passed gc's foreground color<br>
|
|
|
GrText
|
GrText
|
Draw a text string using the foreground and possibly background colors<br>
|
Draw a text string using the foreground and possibly background colors<br>
|
|
|
GrBitmap
|
GrBitmap
|
Draw an image using a passed monocrhome bitmap, use fb/bg colors<br>
|
Draw an image using a passed monocrhome bitmap, use fb/bg colors<br>
|
|
|
GrArea
|
GrArea
|
Draw a rectangular area using the passed device-dependent pixels<br>
|
Draw a rectangular area using the passed device-dependent pixels<br>
|
|
|
GrReadArea
|
GrReadArea
|
Read the pixel values from the screen and return them<br>
|
Read the pixel values from the screen and return them<br>
|
GrGetSystemPaletteEntries Get
|
GrGetSystemPaletteEntries Get
|
the currently in-use system palette entries<br>
|
the currently in-use system palette entries<br>
|
GrFindColor
|
GrFindColor
|
Translate an RGB color value to a PIXELVAL pixel value<br>
|
Translate an RGB color value to a PIXELVAL pixel value<br>
|
</p>
|
</p>
|
|
|
<h3> 4.6 Utility functions</h3>
|
<h3> 4.6 Utility functions</h3>
|
|
|
<p>Various functions serve as utility functions to manipulate windows and provide other
|
<p>Various functions serve as utility functions to manipulate windows and provide other
|
information. These include the following:</p>
|
information. These include the following:</p>
|
|
|
<p>
|
<p>
|
GrSetBorderColor
|
GrSetBorderColor
|
Set the border color of a window. Not suitable for 3d look and feel.<br>
|
Set the border color of a window. Not suitable for 3d look and feel.<br>
|
|
|
GrSetCursor
|
GrSetCursor
|
Set the cursor bitmap for the window.<br>
|
Set the cursor bitmap for the window.<br>
|
|
|
GrMoveCursor
|
GrMoveCursor
|
Move the cursor to absolute screen coordinates.<br>
|
Move the cursor to absolute screen coordinates.<br>
|
|
|
GrSetFocus
|
GrSetFocus
|
Set the keyboard input focus window.<br>
|
Set the keyboard input focus window.<br>
|
|
|
GrRedrawScreen
|
GrRedrawScreen
|
Redraw the entire screen.<br>
|
Redraw the entire screen.<br>
|
|
|
GrGetScreenInfo
|
GrGetScreenInfo
|
Return information about the size of the physical display.<br>
|
Return information about the size of the physical display.<br>
|
|
|
GrGetWindowInfo
|
GrGetWindowInfo
|
Return information about the passed window.<br>
|
Return information about the passed window.<br>
|
|
|
GrGetGCInfo
|
GrGetGCInfo
|
Return information about the passed graphics context.<br>
|
Return information about the passed graphics context.<br>
|
|
|
GrGetFontInfo
|
GrGetFontInfo
|
Return information about the passed font number.<br>
|
Return information about the passed font number.<br>
|
|
|
GrRegisterInput
|
GrRegisterInput
|
Register a file descriptor to return an event when read data available<br>
|
Register a file descriptor to return an event when read data available<br>
|
GrPrepareSelect
|
GrPrepareSelect
|
|
|
Prepare the fd_set and maxfd variables for using Nano-X as a passive library<br>
|
Prepare the fd_set and maxfd variables for using Nano-X as a passive library<br>
|
GrServiceSelect
|
GrServiceSelect
|
|
|
Callback the passed GetNextEvent routine when Nano-X has events requiring processing<br>
|
Callback the passed GetNextEvent routine when Nano-X has events requiring processing<br>
|
GrMainLoop
|
GrMainLoop
|
|
|
A convenience routine for a typical Nano-X application main loop</p>
|
A convenience routine for a typical Nano-X application main loop</p>
|
</body>
|
</body>
|
</html>
|
</html>
|
|
|