nano-X/nano-X-docs.pdf Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: original_mini-x.txt =================================================================== --- original_mini-x.txt (revision 1765) +++ original_mini-x.txt (nonexistent) @@ -1,1103 +0,0 @@ - MINI-X TUTORIAL - David I. Bell - 19 May 91 - -This is a simple tutorial on using the mini-X graphics system. Much of this -is a lot easier to understand if you are familiar to X. I am not going to -try to explain every concept in detail here, nor how to put it all together -to make really fancy programs. Instead, I am only going to tell you just -enough to let you make some simple graphics programs which work. Experience -with simple test programs will enable you to build much fancier graphics -programs much easier than trying to decipher what I could tell you. - -I am assuming that you basically know what a screen, pixels, colors, -keyboards, mice, buttons, and windows are. However, you probably don't -know exactly what the properties of windows in this system are. Also, you -might not know two other concepts which are important here, which are -graphics contexts and events. So these things will be explained in this -tutorial. - - -WINDOWS - -Windows are rectangular areas which can be drawn into. Windows have a -position, specified by the x and y coordinates of their upper left corners, -and also a size, specified by their width and height. Windows are arranged -in a tree structure, with the parent windows controlling the child windows. -The top of the tree is known as the root window. The root window is always -present, and represents the total screen area. - -Each child window is clipped by its parent window. This means that a window -can be very large, but the only part of the window that can ever be seen is -the part which shows through its parent window. This applies recursively, -so that all of the parents of a window limit its visibility. The position -of a window is specified relative to its parent, and not absolutely. This -means that for example, when a window is moved, then all of its children will -move with it. The position of a window can be negative. - -Windows which have the same parent can clip each other. That is, there is a -defined order among the children of a window as to which is more important. -If two sibling windows overlap, then the more important window will be visible -in preference to the less important window. The precedence of visibility -of siblings can be dynamically adjusted. Clipping can also occur on a window -by earlier siblings of any of the window's parents. - -Windows can be mapped or unmapped. Unmapped windows are not visible, and -cause no events. They can be thought of as "in storage" or offscreen. -When a window is mapped, then it can become visible on the screen. Children -of an unmapped window are implicitly also unmapped. So a window is not -visible until it and all of its parents are mapped. A newly created window -starts off unmapped. - -Windows have a background color. A newly mapped window is filled with its -background color. Clearing the window later, or having obscured portions -of the window become visible again, will fill the region with the background. -The client program can then draw into the window to make it look correct. - -Windows may have a border. A border is a set of rectangles adjacent to the -four sides of the window which is drawn in a specified color, with a -specified width. This makes pretty lines around the window, for example. -The border cannot be drawn in by the program. Borders are optional, so -that a window with a border width of zero has no border at all. Borders -are "around" the window, so that they do not affect the coordinates of the -window. Whether or not a window has borders, its position determines the -location of the upper left corner which can be drawn into. - -Windows can have a cursor associated with them. The graphics server tracks -the location of the mouse, and maintains the position of a graphics cursor -on the screen. This cursor can automatically change its shape and colors as -it moves between different windows. The use of different cursors for different -windows can be used to provide a powerful clue to the user as to what will -happen if a mouse button is pressed in a window. Newly created windows -inherit the same cursor as their parent. - -There are two types of windows, input-output and input-only windows. -Input-output windows are normal windows which are visible and can be drawn -into. Input-only windows are invisible, have no border, and cannot be -drawn into. Their purpose is to catch events, and to enable the cursor -to be changed in different regions of a visible window. The only children -of input-only windows are also input-only windows. - -Windows are identified by integers called window ids. The root window has -a constant window id value of GR_ROOT_WINDOW_ID. The root window does not -need creating, and cannot be unmapped, moved, resized, or destroyed. -However, it can be drawn into and events can be delivered to it. New windows -can be created from existing windows. Their window ids are not constants, -but once created the window id remains until the window is destroyed. Window -ids are not reused as windows are created and destroyed. - - -GRAPHICS CONTEXTS - -When drawing objects such as lines, there are many parameters that can be -specified for the function call that affect the operation. Besides the -minimum information needed for the function such as the endpoint coordinates, -there are extra parameters that are less important and less variable. -Examples of these extra parameters are color, width (thin or thick), style -(dashed, dotted), and drawing operation (setting, XORing). Instead of -requiring the specifying of each of these extra parameters for every function -call, graphics contexts are used. Graphics contexts are just a collection -of specific combinations of these extra parameters. The many possible -extra parameters to each function are replaced by just one extra parameter, -which is the graphics context. - -For example, instead of a function call like: - drawline(window, x1, y1, x2, y2, color, width, style, operation); - -you have instead - drawline(window, gc, x1, y1, x2, y2), - -where the graphics context contains within itself the parameters color, width, -style, and operation. - -Graphics contexts are stored in the graphics server, and are identified by -unique numbers in a way similar to window ids. Your program must allocate -graphic contexts, which then can be used in drawing functions. A newly -allocated graphics context is supplied with default parameters, such as a -foreground color of white, drawing operation of setting, and width of 0. -You can modify the parameters associated with the graphics context one by -one, by for example, setting the foreground color to black. - -A single graphics context could be used for every drawing operation by -constantly setting the parameters associated with it to the values needed -for each drawing call. But this is inefficient. The reason that multiple -graphics contexts can be allocated is so that you can minimize the setting of -their parameters. By presetting the parameters of several graphics contexts -to commonly used values in your program, you can avoid changing them later. -For example, you can call one graphics context white_gc, and another graphics -context black_gc, and then use the correct graphics context in the drawing -functions to draw in either black or white. - -The parameters contained within a graphics context are currently the -following: - -Drawing mode. -Specifies the operation performed when drawing each pixel. One of: - GR_MODE_SET draw pixels as given (default) - GR_MODE_XOR draw pixels using XOR - GR_MODE_OR draw pixels using OR - GR_MODE_AND draw pixels using AND - -Text font. -A small integer identifying the font for drawing text. The first few are -built-in to the device driver, others must be loaded by the graphics server. -The default font is 0. - -Foreground color. -The color that is used to draw almost all objects with, such as lines, -points, ellipses, text, bitmaps, and filled areas. Default is white. - -Background color. -The color used for some functions in addition to the foreground color. -For bitmaps and text, this is the color used for the zero bits. The -default background color is black. The drawing of this color can be -disabled by the next parameter. - -UseBackground flag. -This is a boolean value which indicates whether or not the background -color is actually to be drawn for bitmaps, text, and the GrArea8 function. -The default is GR_TRUE. - - -EVENTS - -Events are the way in which the graphics system notifies your program -of asychronous changes in the state of the screen, mouse, or keyboard. -Whenever the state changes, your program is notified of this change and -can act on it. The word "event" is used both for the actual change -that took place, and also for the data that is returned to your program -which describes the change. - -Events are generated for various different types of changes that may be useful -for your program to know. Events directly related to the hardware are the -keyboard and mouse events. Keyboard events are generated for each key which -is pressed (and released, if possible). The event contains the character -which caused the event. Mouse events are generated when a button on the -mouse is pressed or released, or when the mouse position moves. The event -contains the buttons which are pressed, and the current position of the mouse. -Other events are more subtle, and are based on non-physical changes, such -as having the mouse move into or out of specific windows. - -Events are generally tied to individual windows. Your program can enable -or disable which kinds of events it wants for each window. Part of the data -associated with an event is the window associated with the event. For -example, if a key is pressed on the keyboard, the event for that key will -indicate which window that key is for. You program can then act differently -for different windows. Events which you have not indicated an interest in -are simply discarded. - -The keyboard and mouse events can propagate upwards through the window tree -and be delivered to some parent window. This occurs if the window does -not select for the event, but one of the parent windows does. Part of the -information returned about these events is the window that accepted the event, -and also the original window which caused the event. Therefore, your program -can determine which child window an event was for without having to select -for the event for each child. Events other than keyboard and mouse events -never propagate. - -The window that keyboard events are delivered to depends on the current -mouse position or on the "input focus". The input focus is a way of -specifying that keyboard events are to be delivered to a particular window, -no matter where the mouse is currently pointing. Your program can change -the input focus as desired. If the input focus is set to the root window, -then the keyboard events will be delivered to the window which contains -the mouse pointer (or one of its parents). - -Events are returned to your program as a structure containing the information -about the event. This information is the event type, the window id which -the event is associated with, and other event-specific data. Events are -stored in a queue, and are delivered to your program one by one as requested. -The order of the events is preserved. Your program can either simply ask -for the next available event (waiting for one if none are yet available), -or it can check to see if an event is available without waiting. The -delivering of events only occurs when you request an event. So even though -events themselves are asychronous, the reading of them is synchronous. -There are no "interrupts" for events, you must explicitly ask for them. - -The important thing about programming with events is that your program -should be written to run "upside-down". That is, you do not have a main -routine which checks that the mouse has been moved, or the keyboard has -been typed on, or which window the mouse is in. Instead, your main routine -just waits for an event, and then dispatches on its type and which window -it is for. Generally, you must keep some state information to remember -what is happening in your program. For example, if the user wants to click -the button in a window to indicate where some text should be inserted, then -your program cannot simply detect the mouse click, and then wait for the -text to be typed. Instead, when the mouse is clicked, it should just -remember the position of the mouse and set a flag to indicate that text -typing is allowed, When the keyboard event arrives, this saved information -then enables you to draw the text at the correct location. Your program -basically becomes one large state machine. - -One obscure event is the exposure event. This is sent to your program when -a window requires redrawing. Due to lack of memory space, the graphics server -does not attempt to save the data from the parts of windows which are -covered by other windows. Therefore, when the obscured parts of the window -are uncovered, your program must be told to redraw those parts. The exposure -event contains a rectangular area which requires drawing (which may in fact -be larger than the area which was actually uncovered). Your program can -either just redraw that area, or if more convenient, redraw the whole window. -The area to be redrawn has already been cleared to the window's background -color. When a window is mapped, an exposure event is sent for the window. -Therefore, you should not explicitly draw into a window when it is first -created and mapped, but should instead just wait for the exposure event, and -then draw it. In this way, the code to draw the window only resides in one -place in your program, and you prevent redundant drawing of the window. -If you are drawing the complete window on all exposure events, then it -might be useful to use GrPeekEvent to examine the next event too. If it -is also an exposure event for the same window, then you can read it by using -GrGetNextEvent, and thereby prevent redundant redrawing. Of course, to -be able to redraw the window, you may need to save extra data in order to -regenerate the drawing commands. (Pixmaps are one way of doing this in -the future, but they are not currently implemented.) - -The following is a description of the various types of events which are -available, and (in parenthesis) the typedef name for the structure that -returns the event. Each event has a type field, which can be used to -distinguish between the various events. For details on the other data -within the structures, refer to graphics.h. The typedef GR_EVENT is a -union which contains all of the possible event structures. - - -GR_EVENT_TYPE_NONE (GR_EVENT) - This indicates that no event has occurred. - -GR_EVENT_TYPE_EXPOSURE (GR_EVENT_EXPOSURE) - This is generated when a window needs redrawing because it is either - newly mapped, or has been uncovered by another window. This returns - the window id, and the x, y, width, and height of the area within - the window which needs redrawing. - -GR_EVENT_TYPE_BUTTON_DOWN (GR_EVENT_BUTTON) - This is generated when a button is pressed down on the mouse. - This returns the window id which generated the event, the window id - which actually contains the mouse, the current position of the mouse, - the buttons which are currently down on the mouse, the buttons - which were just pressed down, and the current modifier flags. - -GR_EVENT_TYPE_BUTTON_UP (GR_EVENT_BUTTON) - This is generated when a button is released on the mouse. This - returns data similarly to button down. - -GR_EVENT_TYPE_MOUSE_ENTER (GR_EVENT_GENERAL) - This is generated when the mouse enters a window. This returns the - window id which generated the event. - -GR_EVENT_TYPE_MOUSE_EXIT (GR_EVENT_GENERAL) - This is generated when the mouse leaves a window. This returns - the window id which generated the event. - -GR_EVENT_TYPE_MOUSE_MOTION (GR_EVENT_MOUSE) - Mouse motion is generated for every motion of the mouse, and is - used to track the entire history of the mouse. Mouse motion - generates many events and causes lots of overhead. This returns - data similarly to mouse enter. - -GR_EVENT_TYPE_MOUSE_POSITION (GR_EVENT_MOUSE) - Mouse position ignores the history of the motion, and only reports the - latest position of the mouse by only queuing the latest such event for - any single client (good for rubber-banding). This returns data - similarly to mouse enter. - -GR_EVENT_TYPE_KEY_DOWN (GR_EVENT_KEYSTROKE) - This indicates that a key has been pressed on the keyboard. - This returns the window id which generated the event, the window id - which actually contains the pointer (if the pointer is outside of - the event window, this will be the event window), the current position - of the mouse, the current buttons on the mouse which are down, the - current modifier flags, and the character which was typed. - -GR_EVENT_TYPE_KEY_UP (GR_EVENT_KEYSTROKE) - This indicates that a key has been released on the keyboard. This - event is not necessarily available, and should not be depended on. - This returns data similarly to key down. - -GR_EVENT_TYPE_FOCUS_IN (GR_EVENT_GENERAL) - This indicates that the input focus has just changed to this window. - This returns the window id which got focus. - -GR_EVENT_TYPE_FOCUS_OUT (GR_EVENT_GENERAL) - This indicates that the input focus has just left this window. - This returns the window id which lost focus. - - -To select for events, you use GrSelectEvents, and specify the window which -wants to receive the events, and also specify a mask indicating the events -you wish to receive. The mask is the logical OR of individual bit values -representing the event types. The mask names are the same as the event -names, except that the "_TYPE_" string is replaced by "_MASK_". For -example, the mask associated with the event GR_EVENT_TYPE_FOCUS_IN is -GR_EVENT_MASK_FOCUS_IN. - -If you select for both button down and button up events, then the mouse -will be implicitly "grabbed" when any button is pressed down in that window. -This means that the mouse position and button down and up events will be -delivered only to that window, and the cursor shape won't change, even if -the mouse leaves that window. The implicit grabbing ends after the last -button is released. While this grabbing occurs, the input focus is also -not changed as the mouse is moved. - - -MODIFIER AND MOUSE BUTTONS - -Modifiers are the status of special keyboard shift-like keys. The state -of these keys can be read as up or down, and don't generate any characters -by themselves. These keys are for things like SHIFT, CTRL, and ALT. -They are returned as bit values OR'd together in various events. Not all -of these modifiers may be implemented. The GrGetScreenInfo function returns -the modifiers that are implemented. The following modifiers are defined: - - GR_MODIFIER_SHIFT shift key is down - GR_MODIFIER_CTRL ctrl key is down - GR_MODIFIER_META meta (or ALT) key is down - GR_MODIFIER_ANY any of the modifiers is down - - -The mouse button state are returned as bit values OR'd together in various -events. Not all of these buttons may be implemented. The GrGetScreenInfo -function returns the buttons that are implemented. The following mouse -buttons are defined: - - GR_BUTTON_1 button 1 is down (left) - GR_BUTTON_2 button 2 is down (middle) - GR_BUTTON_3 button 3 is down (right) - GR_BUTTON_ANY any of the buttons is down - - -BITMAPS - -Bitmaps are defined as an array of GR_BITMAP values, which are unsigned shorts. -Each word is 16 bits, which specify foreground and background values, with 1 -being foreground and 0 being background. Higher order bits in the word -represent pixels to the left of the lower order bits. Bitmaps have a width -and a height, measured in pixels. The width does not need to be a multiple -of 16. In this case, remaining bits in the last word of a row are unused, -so that each row starts with a new bitmap word. The GR_BITMAP_SIZE macro can -be used to allocate the proper number of bitmap words for a bitmap, as in: - - GR_BITMAP_SIZE(width, height). - -The symbol GR_MAX_BITMAP_SIZE is the number of bitmap words required for -the maximum sized cursor. - - -ERROR CODES - -Calls to the graphics libraries may produce errors. Most errors that -occur are due to specifying a window or graphics context which does not -exist, or attempting an operation which is illegal. Many things are allowed -even if pointless, such as drawing outside of the window boundaries, or -while a window is not mapped. The things which return errors are those -which definitely indicate a program bug, attempts to exceed the system -limits, or a fatal device error. - -In order to be as efficient as possible, error codes are not returned by -individual function calls. Instead, if a function fails, an error event -is generated which will eventually be noticed by the program at a possibly -much later time. This allows many drawing requests to be sent at one time -without having to worry about the status of each one. - -Error events are detected when the program checks for events, such as -by calling GrGetNextEvent. At this point, if an error had occurred, a -special error handler routine is called to notice the error. If the program -had not set up its own error handler, a default one is called which will -disconnect from the server, print out an indication of the error, and exit -the program. - -The following is a list of the possible errors: - -GR_ERROR_BAD_WINDOW_ID the specified window id is unknown -GR_ERROR_BAD_GC_ID the specified graphics context id is unknown -GR_ERROR_BAD_CURSOR_SIZE the specified cursor is too large -GR_ERROR_MALLOC_FAILED no more memory is available in the server -GR_ERROR_BAD_WINDOW_SIZE the specified window size is illegal -GR_ERROR_KEYBOARD_ERROR an error occurred reading from the keyboard -GR_ERROR_MOUSE_ERROR an error occurred reading from the mouse -GR_ERROR_INPUT_ONLY_WINDOW drawing was attempted in an input-only window -GR_ERROR_ILLEGAL_ON_ROOT_WINDOW an illegal operation was attempted on the root -GR_ERROR_TOO_MUCH_CLIPPING complexity of windows exceeded clipping limits -GR_ERROR_SCREEN_ERROR an error occurred talking to the screen driver -GR_ERROR_UNMAPPED_FOCUS_WINDOW attempted to set focus to an unmapped window -GR_ERROR_BAD_DRAWING_MODE illegal drawing mode specified for a GC - - -SCREEN PROPERTIES - -You do not have to hard code the size of the screen or the number of colors -available in your program. Instead, you can find this information out -dynamically after the connection is made to the graphics server, by using -the GrGetScreenInfo call. This returns the above information, and in addition -returns the color values for black and white, the aspect ratio of pixels, -the number of built-in fonts available, and the modifiers and buttons which -are available. The aspect ratio is useful for drawing objects which need -to be scaled correctly, such as circles. The aspect ratio is the quotient -of xdpcm and ydpcm, which are integer values. - - -typedef struct { - GR_SIZE rows; /* number of rows on screen */ - GR_SIZE cols; /* number of columns on screen */ - GR_SIZE xdpcm; /* dots/centimeter in x direction */ - GR_SIZE ydpcm; /* dots/centimeter in y direction */ - GR_COLOR maxcolor; /* maximum legal color value */ - GR_COLOR black; /* the color black */ - GR_COLOR white; /* the color white */ - GR_COUNT fonts; /* number of built-in fonts */ - GR_BUTTON buttons; /* buttons which are implemented */ - GR_MODIFIER modifiers; /* modifiers which are implemented */ -} GR_SCREEN_INFO; - - -INCLUDE FILE AND GRAPHICS LIBRARY - -To use the graphics server, your program must include "graphics.h". -This should be put into /usr/include, so that your program simply has -the following line at the top: - #include - -Including this file gives you all of the definitions you need to use the -graphics library. These are the typedefs, function declarations, event -structures, and various constants. - -When loading your program, you need to load the graphics server into the -program by using the -lgraph option in the cc command. For example, if -your program is called myprog, then you could build it using the following: - cc -o myprog myprog.c -lgraph - - -TYPEDEFS - -The following is a list of the typedefs in the include file, and a short -description of their purpose. Refer to their definitions in graphics.h -to find out what their actual C base type is. Most are shorts, unsigned -shorts, or longs. - -GR_COORD coordinate value (x, y locations, signed) -GR_SIZE size value (widths, heights, signed) -GR_COUNT number of items (signed) -GR_COLOR full color value (32 bit value for full generality) -GR_COLOR8 eight bit color value (8 bit value for efficient storage) -GR_BITMAP bitmap unit (single words of 16 bits for bitmaps) -GR_MODE drawing mode (setting, xoring, anding, oring) -GR_CHAR text character (normal chars) -GR_ID resource ids (window, graphics context, pixmap) -GR_DRAW_ID drawable id (window, pixmap) -GR_WINDOW_ID window id (identifies individual window) -GR_PIXMAP_ID pixmap id (identifies individual pixmaps, not yet used) -GR_GC_ID graphics context id (identifies indiviual graphics contexts) -GR_FONT font number (identifies individual fonts, first few built-in) -GR_BOOL boolean value (GR_TRUE or GR_FALSE) -GR_FUNC function codes (not for clients to use) -GR_ERROR error value (reasons for graphics calls to fail) -GR_EVENT_TYPE event types (identifies the type of event) -GR_BUTTON button flags (which mouse buttons are depressed) -GR_MODIFIER modifier flags (CTRL, SHIFT, etc) -GR_EVENT_MASK event masks (mask values corresponding to event types) -GR_FUNC_NAME function name (for error reporting) -GR_ERROR_FUNC error function (for defining error handlers) - - -The following typedefs may be useful to your program. None of the library -functions (currently) accept any of these structures as arguments, except -for the GrPoly and GrFillPoly routines, which use GR_POINT. - - -typedef struct { - GR_COORD x; /* x coordinate */ - GR_COORD y; /* y coordinate */ -} GR_POINT; - -typedef struct { - GR_COORD x1; /* x coordinate of first point */ - GR_COORD y1; /* y coordinate of first point */ - GR_COORD x2; /* x coordinate of second point */ - GR_COORD y2; /* y coordinate of second point */ -} GR_LINE; - -typedef struct { - GR_COORD x; /* x coordinate of center */ - GR_COORD y; /* y coordinate of center */ - GR_SIZE rx; /* radius in x direction */ - GR_SIZE ry; /* radius in y direction */ -} GR_ELLIPSE; - -typedef struct { - GR_COORD x; /* x coordinate of top left corner */ - GR_COORD y; /* y coordinate of top left corner */ - GR_SIZE width; /* width of rectangle */ - GR_SIZE height; /* height of rectangle */ -} GR_RECT; - - -LIMITS - -The coordinate system is limited to integers in the range GR_COORD_MIN -to GR_COORD_MAX. This is -32768 to 32767, and fits in a short. - -The maximum size of a cursor definition is GR_MAX_CURSOR_SIZE, which is -16 pixels by 16 pixels. - -The complexity of overlapping windows is limited to GR_MAX_CLIPRECTS regions, -which is 200. Each window which overlaps another requires another 1 to 4 -regions depending on its position and size. - - -GRAPHICS CALLS - - -int -GrOpen() -Open a connection to the graphics server. This must be the first graphics -function used by your program. Currently, this sets the screen into -graphics mode. Returns zero if successful, -1 on failure. - - -void -GrClose() -Close the connection to the graphics server, first flushing any graphics -calls that have been buffered. Currently, this sets the screen back into -text mode. This (currently) should be called before your program exits, -otherwise the screen will be left in graphics mode. If this occurs, you -can run the 'tm' program to reset the terminal to text mode. - - -GR_ERROR_FUNC -GrSetErrorHandler(func) - GR_ERROR_FUNC func; /* function to handle errors */ -Set an error handling routine, which will be called on any errors from -the server (when events are asked for by the client). If zero is given, -then a default routine will be used which will describe the error and exit. -Returns the previous error handler (0 if none). When an error occurs, -the error handling function is called with the following parameters: -GR_ERROR, GR_FUNC_NAME, and GR_ID. These are the error code, the name -of the function which failed, and a resource id (0 if not meaningful). -The error routine can return if desired, but without corrective action -new errors will probably occur soon. - - -void -GrGetScreenInfo(sip) - GR_SCREEN_INFO *sip; /* location to return info into */ -Return useful information about the screen. This information returned -has been documented above. - - -void -GrGetFontInfo(font, fip) - GR_FONT font; /* font number */ - GR_FONT_INFO *fip; /* address of font info */ -Return useful information about the specified font number. This information -is the font number, the height of the font, the maximum width of any -character in the font, the height of the baseline, a flag indicating whether -or not the font is fixed-width, and a table of the individual widths of each -character in the font. If the font is unknown, the returned font number is -set to zero and the remainder of the information is undefined. Refer to -graphics.h for a definition of the fields of GR_FONT_INFO. - - -void -GrGetGCInfo(gc, gcip) - GR_GC_ID gc; /* graphics context */ - GR_GC_INFO *gcip; /* address of graphics context info */ -Return useful information about the specified graphics context. This -information is the graphics context id, the current font, the foreground -and background colors, and so on. If the graphics context is unknown, -the returned id is 0, and the other information is undefined. Refer to -graphics.h for a definition of the fields of GR_GC_INFO. - - -void -GrGetGCTextSize(gc, cp, len, retwidth, retheight, retbase) - GR_GC_ID gc; /* graphics context containing font */ - GR_CHAR *cp; /* address of text string */ - GR_SIZE len; /* length of text string */ - GR_SIZE *retwidth; /* returned width of string */ - GR_SIZE *retheight; /* returned height of string */ - GR_SIZE *retbase; /* returned height of baseline */ -Return the size of a text string for the font in a graphics context. -This is the width of the string, the height of the string, and the height -above the bottom of the font of the baseline for the font. The returned -sizes are in pixels. - - -void -GrGetNextEvent(ep) - GR_EVENT *ep; /* address where event is returned */ -Return the next event from the event queue, waiting for it if necessary. -If a graphics error had occurred, the error handler will be called at this -point. This routine first flushes any buffered graphics commands. The -GR_EVENT is a union of all the possible events. The type field of the union -indicates which of the possible events took place, and then the correct -element of the union can be used to access that particular event type's data. - - -void -GrCheckNextEvent(ep) - GR_EVENT *ep; /* address where event is returned */ -Return the next event from the event queue if one is ready. -If one is not ready, then the event type GR_EVENT_TYPE_NONE is returned. -Therefore, this routine never blocks. This routine first flushes any -buffered graphics commands. - - -void -GrPeekEvent(ep) - GR_EVENT *ep; /* address where event is returned */ -Return the next event from the event queue if one is ready, without removing -it from the queue. If one is not ready, then the type GR_EVENT_TYPE_NONE -is returned. This routine never blocks. This routine first flushes any -buffered graphics commands. - - -void -GrSelectEvents(wid, eventmask) - GR_WINDOW_ID wid; /* window id */ - GR_EVENT_MASK eventmask; /* mask of events wanted */ -Select events for a window for this client. The events are a bitmask -specifying the events desired for this window. This totally replaces -any previously selected event mask for the window. - - -GR_WINDOW_ID -GrNewWindow(parent, x, y, width, height, bordersize, background, bordercolor) - GR_WINDOW_ID parent; /* parent id */ - GR_COORD x; /* x position relative to parent */ - GR_COORD y; /* y position relative to parent */ - GR_SIZE width; /* width */ - GR_SIZE height; /* height */ - GR_SIZE bordersize; /* size of border */ - GR_COLOR background; /* background color */ - GR_COLOR bordercolor; /* border color */ -Allocate a new input-output window which is a child of the specified window. -A new top-level window is made by specifying a parent of GR_ROOT_WINDOW_ID. -The x and y position is the upper left corner of the window, relative to -the parent's upper left corner. These corners are only for the drawable -area of the windows, so that the border does not affect the position. An -input-output window cannot be made as a child of an input-only window. The -new window starts off unmapped, and must be mapped before it can be seen. -The new window inherits the cursor of the parent window, and initially is -set to select no events. This routine returns the window id of the window -which can be used in other calls. - - -GR_WINDOW_ID -GrNewInputWindow(parent, x, y, width, height) - GR_WINDOW_ID parent; /* parent id */ - GR_COORD x; /* x position relative to parent */ - GR_COORD y; /* y position relative to parent */ - GR_SIZE width; /* width */ - GR_SIZE height; /* height */ -Allocate a new input-only window which is a child of the specified window. -An input-only window is invisible, and cannot be drawn into. It's only -purposes are that it can select events, and can have it's own cursor. The -new window starts off unmapped, and must be mapped before it is effective. -The new window inherits the cursor of the parent window, and initially is -set to select no events. This routine returns the window id of the window -which can be used in other calls. - - -void -GrDestroyWindow(wid) - GR_WINDOW_ID wid; /* window to destroy */ -This unmaps and then destroys the specified window, and all of its children. -The root window cannot be destroyed. After destroying a window, you must be -careful about handling events which refer to the dead window, but which have -not been read yet. - - -void -GrGetWindowInfo(wid, wip) - GR_WINDOW_ID wid; /* window id to find out about */ - GR_WINDOW_INFO *wip; /* location to return info into */ -Return useful information about the specified window. Refer to the -graphics.h include file for the definition of GR_WINDOW_INFO to see -what data is returned. If the window id is not valid, an error is NOT -generated. Instead, the wid value in the returned structure is set to -zero, and the other fields are not defined. - - -GR_GC_ID -GrNewGC() -Allocate a new graphics context with default parameters. These defaults are: -background of black, foreground of white, font as font 0, and drawing mode -as setting. This routine returns the id for the graphics context which can -be used in other calls. - - -GR_GC_ID -GrCopyGC(gc) - GR_GC_ID gc; /* graphics context to copy */ -Allocate a new graphics context which is a copy of another one. The new -graphics context has the same parameter values as the old one, but is then -independent. This routine returns the id for the graphics context which -can be used in other calls. - - -void -GrDestroyGC(gc) - GR_GC_ID gc; /* graphics context to destroy */ -Destroy an existing graphics context. - - -void -GrMapWindow(wid) - GR_WINDOW_ID wid; /* window to be mapped */ -Map the window to make it (and possibly its children) visible on the screen. -This paints the border and background of the window, and creates an -exposure event to tell the client to draw into it. - - -void -GrUnmapWindow(wid) - GR_WINDOW_ID wid; /* window to be unmapped */ -Unmap the window to make it and its children invisible on the screen. - - -void -GrRaiseWindow(wid) - GR_WINDOW_ID wid; /* window to be raised */ -Raise the window to the highest level among its siblings. This means that -this window will be visible in preference to those siblings. Siblings are -windows which have the same parent as this window. - - -void -GrLowerWindow(wid) - GR_WINDOW_ID wid; /* window to be lowered */ -Lower the window to the lowest level among its siblings. This means that -this window will be covered by any siblings which overlap it. - - -void -GrMoveWindow(wid, x, y) - GR_WINDOW_ID wid; /* window to be lowered */ - GR_COORD x; /* new relative x position */ - GR_COORD y; /* new relative y position */ -Move the window to the specified position relative to its parent. - - -void -GrResizeWindow(wid, width, height) - GR_WINDOW_ID wid; /* window to be lowered */ - GR_SIZE width; /* new width of window */ - GR_SIZE height; /* new height of window */ -Resize the window to be the specified size. Resizing of a window can -generate exposure events. - - -void -GrClearWindow(wid, exposeflag) - GR_WINDOW_ID wid; /* window id */ - GR_BOOL exposeflag; /* nonzero to cause an exposure */ -Clear the specified window by setting it to its background color. -If the exposeflag is nonzero, then this also creates an exposure -event for the window. - - -void -GrSetFocus(wid) - GR_WINDOW_ID wid; /* window id */ -Set the focus to a particular window. This makes keyboard events only -visible to that window or children of it, depending on the pointer location. -Setting the focus window to the root window makes the input focus track -the pointer (which is the default). - - -void -GrSetBorderColor(wid, color) - GR_WINDOW_ID wid; /* window id */ - GR_COLOR color; /* color for border */ -Set the border of a window to the specified color. - - -void -GrSetCursor(wid, width, height, hotx, hoty, foreground, background, - fgbitmap, bgbitmap) - - GR_WINDOW_ID wid; /* window id to set cursor for */ - GR_SIZE width; /* width of cursor */ - GR_SIZE height; /* height of cursor */ - GR_COORD hotx; /* relative x position of hot spot */ - GR_COORD hoty; /* relative y position of hot spot */ - GR_COLOR foreground; /* foreground color of cursor */ - GR_COLOR background; /* background color of cursor */ - GR_BITMAP *fgbitmap; /* foreground bitmap */ - GR_BITMAP *bgbitmap; /* background bitmap */ -Specify a new cursor for a window. This cursor will only be used within -that window, and by default for its new children. The cursor is defined -by giving its width and height, its foreground and background colors, its -foreground and background bitmaps, and its "hot spot" position. If a pixel -is specified for both the foreground and background bitmaps, then the -foreground has precedence. The hot spot is an offset from the upper left -corner of the bitmap, and is the location in the cursor which is important. - - -void -GrMoveCursor(x, y) - GR_COORD x; /* new x position of cursor */ - GR_COORD y; /* new y position of cursor */ -Move the cursor to the specified absolute screen coordinates. -The coordinates are that of the defined hot spot of the cursor. -The cursor's appearance is changed to that defined for the window -in which the cursor is moved to. - - -void -GrFlush() -Flush the graphics buffer so that all previous requests will be executed. -This is only needed if you do not check events quickly and want to see the -results on the screen soon, since checking for events does an automatic flush. - - -void -GrSetGCForeground(gc, foreground) - GR_GC_ID gc; /* graphics context id */ - GR_COLOR foreground; /* foreground color */ -Set the foreground color in a graphics context. The default is white. - - -void -GrSetGCBackground(gc, background) - GR_GC_ID gc; /* graphics context id */ - GR_COLOR background; /* background color */ -Set the background color in a graphics context. The default is black. - - -void -GrSetGCUseBackground(gc, flag) - GR_GC_ID gc; /* graphics context id */ - GR_BOOL flag; /* TRUE if background is drawn */ -Set whether or not the background color is drawn in bitmaps and text. -This affects GrBitmap, GrArea8, and GrText. The default is GR_TRUE. - - -void -GrSetGCMode(gc, mode) - GR_GC_ID gc; /* graphics context id */ - GR_MODE mode; /* drawing mode */ -Set the drawing mode in a graphics context. The drawing mode is one of -GR_MODE_SET, GR_MODE_XOR, GR_MODE_AND, or GR_MODE_OR. The default is -GR_MODE_SET. - - -void -GrSetGCFont(gc, font) - GR_GC_ID gc; /* graphics context id */ - GR_FONT font; /* text font */ -Set the font used for text drawing in a graphics context. -The font is a number identifying one of several fonts. -Font number 0 is always available, and is the default font. - - -void -GrLine(id, gc, x1, y1, x2, y2) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x1; - GR_COORD y1; - GR_COORD x2; - GR_COORD y2; -Draw a line in the specified drawable using the specified graphics context. - - -void -GrRect(id, gc, x, y, width, height) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x; - GR_COORD y; - GR_SIZE width; - GR_SIZE height; -Draw the boundary of a rectangle in the specified drawable using the -specified graphics context. - - -void -GrFillRect(id, gc, x, y, width, height) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x; - GR_COORD y; - GR_SIZE width; - GR_SIZE height; -Fill a rectangle in the specified drawable using the specified graphics -context. The boundary of this rectangle is identical to that drawn by -the GrRect function. - - -void -GrEllipse(id, gc, x, y, rx, ry) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x; - GR_COORD y; - GR_SIZE rx; - GR_SIZE ry; -Draw the boundary of an ellipse in the specified drawable with -the specified graphics context. - - -void -GrFillEllipse(id, gc, x, y, rx, ry) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x; - GR_COORD y; - GR_SIZE rx; - GR_SIZE ry; -Fill an ellipse in the specified drawable using the specified -graphics context. - - -void -GrBitmap(id, gc, x, y, width, height, bitmaptable) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x; - GR_COORD y; - GR_SIZE width; - GR_SIZE height; - GR_BITMAP *bitmaptable; -Draw a rectangular area in the specified drawable using the specified -graphics context, as determined by the specified bit map. This differs -from rectangle drawing in that the rectangle is drawn using the foreground -color and possibly the background color as determined by the bit map. -Bits which are 1 are the foreground, and bits which are 0 are the background. -Each row of bits is aligned to the next bitmap word boundary (so there can -be padding at the end of each row). The background bit values are only -written if the usebackground flag is set in the GC. - - -void -GrArea8(id, gc, x, y, width, height, colortable) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x; - GR_COORD y; - GR_SIZE width; - GR_SIZE height; - GR_COLOR8 *colortable; -Draw a rectangular area in the specified drawable using the specified -graphics context. This differs from rectangle drawing in that the -color values for each pixel in the rectangle are specified. The color -values are estricted to 8 bit values. The color table is indexed row by -row from left to right. Table values whose color matches the background -color are only written if the usebackground flag is set in the GC. - - -void -GrReadArea8(id, x, y, width, height, colortable) - GR_DRAW_ID id; - GR_COORD x; - GR_COORD y; - GR_SIZE width; - GR_SIZE height; - GR_COLOR8 *colortable; -Read the color values from the specified rectangular area of the specified -drawable into a supplied buffer. If the drawable is a window which is -obscured by other windows, then the returned values will include the values -from the covering windows. Regions outside of the screen boundaries, or -from unmapped windows will return black. - - -void -GrPoint(id, gc, x, y) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x; - GR_COORD y; -Draw a point in the specified drawable using the specified graphics context. - - -void -GrPoly(id, gc, count, pointtable) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COUNT count; - GR_POINT *pointtable; -Draw a polygon in the specified drawable using the specified graphics -context. The polygon is only complete if the first point is repeated at -the end. Note: currently if the polygon crosses itself, and the drawing -mode is set to XOR, then the individual line segments will affect each -other. The endpoints of the lines are correct, however. - - -void -GrFillPoly(id, gc, count, pointtable) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COUNT count; - GR_POINT *pointtable; -Draw a filled polygon in the specified drawable using the specified -graphics context. The last point may be a duplicate of the first point, -but this is not required. Note: currently only convex polygons are -filled properly. - - -void -GrText(id, gc, x, y, str, count) - GR_DRAW_ID id; - GR_GC_ID gc; - GR_COORD x; - GR_COORD y; - GR_CHAR *str; - GR_COUNT count; -Draw a text string at the specified location in the specified drawable -using the specified graphics context. The background of the characters -are only drawn if the usebackground flag in the GC is set. - - -EXAMPLE PROGRAM - -The following simple program opens the graphics, creates a window, prints -some text in it, waits for the mouse to be clicked in the window, then exits. - - -#include -#include - -#define MARGIN 50 /* margin around window */ - - -main() -{ - GR_WINDOW_ID wid; /* window id */ - GR_GC_ID gc; /* graphics context id */ - GR_EVENT event; /* current event */ - GR_SCREEN_INFO si; /* screen information */ - - if (GrOpen() < 0) { - fprintf(stderr, "Cannot open graphics\n"); - exit(1); - } - - GrGetScreenInfo(&si); - - wid = GrNewWindow(GR_ROOT_WINDOW_ID, MARGIN, MARGIN, - si.cols - MARGIN * 2, si.rows - MARGIN * 2, - 1, si.black, si.white); - - GrSelectEvents(wid, GR_EVENT_MASK_BUTTON_DOWN | GR_EVENT_MASK_EXPOSURE); - GrMapWindow(wid); - gc = GrNewGC(); - - while (1) { - GrGetNextEvent(&event); - switch (event.type) { - case GR_EVENT_TYPE_BUTTON_DOWN: - if (event.button.wid != wid) - break; - GrClose(); - exit(0); - - case GR_EVENT_TYPE_EXPOSURE: - if (event.exposure.wid == wid) - GrText(wid, gc, 50, 50, "EXIT", 4); - break; - } - } -} - - -For a more complete demonstration program, see the file "demo.c" in the -/usr/src/graphics/clients directory. Index: microwindows_architecture.html =================================================================== --- microwindows_architecture.html (revision 1765) +++ microwindows_architecture.html (nonexistent) @@ -1,1085 +0,0 @@ - - - - - - - -MicroWindows Architecture - - - - -

Microwindows Architecture

- -

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 -whether you're confused by my explanations. This document is for educational and -porting purposes, so please read on.

- -

1. Architecture
-    1.1        Layered Design
-    1.2        Device Drivers
-        1.2.1     Screen Driver
-        1.2.2     Mouse Driver
-        1.2.3     Keyboard Driver
-    1.3        MicroGUI - Device -Independent Graphics Engine
-    1.4        Applications Programmer -Interfaces
-        1.4.1    Microwindows API
-        1.4.2    Nano-X API

- -

2. Device-Independent Engine Features
-    2.1        Graphics Engine Features -and Implementation
-        2.1.1    Regions
-        2.1.2    Clipping
-        2.1.3    Line Drawing
-        2.1.4    Rectangles, Circles, -Ellipses
-        2.1.5    Polygons
-        2.1.6    Area Fills
-        2.1.7    Fonts
-        2.1.8    Text Drawing
-        2.1.9    Color model and -palettes
-        2.1.10 Image Drawing
-        2.1.11 Blitting

- -

3. Microwindows API
-    3.1        Message-passing -architecture
-    3.2        Window creation and -destruction
-    3.3        Window showing, hiding -and moving
-    3.4        Window painting
-        3.4.1    Client and screen -coordinates
-        3.4.2    Device contexts
-        3.4.3    Graphics drawing API
-    3.5        Utility functions
-        3.5.1    Setting window focus
-        3.5.2    Mouse capture
-        3.5.3    Rectangle and Region -management

- -

4. Nano-X API
-    4.1        Client/Server model
-    4.2        Events
-    4.3        Window creation and -destruction
-    4.4        Window showing, hiding -and moving
-    4.5        Drawing to a window
-        4.5.1    Graphics contexts
-        4.5.2    Graphics drawing API
-    4.6        Utility functions

- -

1. Architecture

- -

1.1 Layered Design

- -

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, -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, -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 -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. -These APIs provide close compatibility with the Win32 and X Window systems, allowing -programs to be ported from other systems easily.

- -

1.2 Device Drivers

- -

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 -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 -setup allows varying hardware devices to be added to the Microwindows system without -affecting the way the entire system works.

- -

1.2.1 Screen Driver

- -

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 -(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 -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 -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, -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 -framebuffer only. All the graphics mode initialization and deinitialization is -handled by the Linux kernel. Getting this set up can be a real pain.

- -

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 -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. -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 -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 -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 -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 -the system the x,y size of the screen, along with the color model supported.

- -

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 -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.

- -

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 -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 -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 -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. -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 -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 -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 -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, -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 -files fblin8.c and mempl4.c for examples of supporting both types of display hardware.

- -

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 -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 -write a bitblit routine from the start.

- -

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 -pointers are valid. Thus, even if not implementing bitblit, a do-nothing bit-blit -procedure must be provided.

- -

1.2.2 Mouse Driver

- -

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, -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 -function is to decode the mouse data and return either relative or absolute data for the -mouse position and buttons.

- -

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 -surface, and can be used like a mouse.

- -

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 -Microwindows is running on doesn't support select() or doesn't pass mouse data through a -file descriptor, a Poll() entry point is provided.

- -

1.2.3 Keyboard Driver

- -

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. -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 -doesn't decode multi-character function key codes. This functionality will need to be -added soon, by reading termcap files or the like.

- -

1.3 MicroGUI - Device Independent Graphics -Engine

- -

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

- -

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 -conversion is handled within this layer. The following files comprise the core -modules of Microwindows:

- -

devdraw.c Core graphics -routines for line, circle, polygon draw and fill, text and bitmap drawing, color -conversion

- -

devclip.c Core -clipping routines. (devclip2.c is the new y-x-banding algorithm, devclip1.c an older -method)

- -

devrgn.c -New dynamically allocated routines for intersect/union/subtract/xor region creation.

- -

devmouse.c Core routines for keeping -the mouse pointer updated or clipped from the screen.

- -

devkbd.c Core -keyboard handling routines.

- -

devpalX.c Linked in -static palettes for 1, 2, 4 and 8bpp palletized systems.

- -

Section 2 following discusses the MicroGUI graphics engine routines in detail.

- -

1.4 Applications Programmer Interfaces

- -

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

- -

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 -an event occurs, if it's a system event like keyboard or mouse activity, then this -information is passed to the user program converted to an expose event, paint message, -etc. 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 -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 -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 -display contexts and passes that information, including clipping information, to the core -engine routines.

- -

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

- -

1.4.1 Microwindows API

- -

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 -well as automatic window title bar drawing and dragging windows for movement. The -Microwindows API is message-based, and allows programs to be written without regard to the -eventual window management policies implemented by the system. The Microwindows API -is not currently client/server, and will be discussed in more detail in section 4.

- -

1.4.2 Nano-X API

- -

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 -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 -for automatic window dressings, title bars, or user window moves. There are several -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 -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 -could be considerable, in the case that, say Gdk was ported.)

- -

2. Device-Independent Engine Features

- -

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 -an API by understanding how the engine works.

- -

2.1 Graphics Engine -Features and Implementation

- -

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 -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 -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 -specified in device coordinates, that is, offsets from the upper left corner of the -screen.

- -

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 -PIXELVAL values. In the case of 32bpp truecolor displays, no conversion is -required. The color model will be discussed in detail below.

- -

2.1.1 Regions

- -

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 -pixels require more complex data structures. In Microwindows, regions are described -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 -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 -the region. The array wasn't sorted in any particular order, but was always -guaranteed to contain non-overlapping rectangles. Another global variable, -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 -functions, described below.

- -

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, -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 -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 -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 -rectangles and regions with regions using Intersection, Union, Subtraction, and Exclusive -Or. This model allows regions to be implemented apart from the clipping routines, -unlike the first version. Following are the new region routines:

- -

    -GdAllocRegion                    -- Create a region
-    -GdDestroyRegion                -- Destroy a region
-    -GdCopyRegion                    -- Copy a region
-    GdUnionRectWithRegion     - Union a rectangle with -a region
-    -GdIntersectRegion               -- Create a region from the intersection of two regions
-    -GdSubtractRegion                -- Create a region from the difference of two regions
-    -GdUnionRegion                    -- Create a region from the union of two regions
-    -GdXorRegion                       -- Create a region from the XOR of two regions
-

- -

2.1.2 Clipping

- -

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 -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 -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 -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 -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 -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 -within the region, CLIP_INVISIBLE, if the area is completely not in the region, which -means that no drawing should be performed, or CLIP_PARTIAL, if a part but not the whole -area is within the region. A typical graphics primitive will call the screen driver -with unmodified passed inputs if CLIP_VISIBLE is returned, or return if CLIP_INIVISIBLE is -returned. 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 -slows down the operation considerably.

- -

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

- -

2.1.3 Line Drawing

- -

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 -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. -GdFixCursor restores the cursor if previously visible.

- -

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 -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 -whether or not to draw the last point. The Microwindows API doesn't draw the last -point, but the Nano-X API does.

- -

Most drawing functions, including line drawing draw using the "current" -foreground color, specified using GdSetForeground. In addition a drawing mode, -currently either MODE_SET or MODE_XOR can be specified using GdSetMode.

- -

2.1.4 Rectangles, -Circles, Ellipses

- -

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, -rectangles and ellipses are drawn using the current foreground color and mode.

- -

2.1.5 Polygons

- -

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, -drawing mode, and clip region is used during output.

- -

2.1.6 Area Fills

- -

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

- -

2.1.7 Fonts

- -

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 -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 -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 -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 -drawing, as well as to draw the character as a monochrome bitmap.

- -

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 -conversion programs allow conversion of fonts from different formats to the driver -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 -Microwindows format. Convrom converts PC ROM bios fonts.

- -

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 -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.

- -

2.1.8 Text Drawing

- -

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 -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 -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.

- -

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 -case the background is drawn using the current background color set via -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.

- -

2.1.9 Color model and -palettes

- -

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 -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 -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, -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 -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 -values using two routines, GdFindColor and GdFindNearestColor, described below.

- -

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 -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 -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 -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 -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.

- -

The GdSetPalette function determines whether there are any free entries in the system -palette (discussed shortly) and if so, adds entries to the system palette, and calls the -screen driver SetPalette entry point to set the hardware palette. There is a single -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 -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 -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 -different images and force the system palette to be rewritten.

- -

2.1.10 Image Drawing

- -

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 -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 -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 -TRUE.

- -

Color bitmaps are specified using a 1, 4 or 8bpp image palette, and an array of indices -into this palette, all stuffed into an IMAGEHDR structure, and drawn via -GdDrawImage. First, the system creates a conversion palette by calling -GdMakePaletteConversionTable, which converts the images' palette entries into system -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 -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 -converted to hardware truecolor pixel values, and output directly.

- -

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 -routine could be used for faster image drawing.

- -

2.1.11 Blitting

- -

Blitting functionality is required in the screen driver for offscreen drawing -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 -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 -implement this by allocating a new SCREENDRIVER structure, copying an existing -SCREENDRIVER structure into it, replacing the address field with a malloc()'d value, and -setting the PSF_MEMORY bit, which indicates to the display driver that this is now an -offscreen surface. 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 -display, the GdBlit routine is called. Currently, only SRCCOPY operations are -performed, but future plans will add blitting opcodes.

- -

3. Microwindows API

- -

3.1 Message-passing -architecture

- -

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 -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 -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 -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 -application sends the message to the associated window's handling procedure using -DispatchMessage. When a window class is created, it's associated message handling -procedure is specified, so the system knows where to send the message.

- -

The message-passing architecture allows the core API to manage many system functions by -sending messages on all sorts of events, like window creation, painting needed, moving, -etc. By default, the associated window handling function gets a "first -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 -way when dragged, etc, unless specifically overridden by the user. Major window -management policies can be redefined by merely re-implementing DefWindowProc, rather than -making changes throughout the system.

- -

The following functions deal with messages directly:

- -

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

- -

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

- -

3.2 Window creation and -destruction

- -

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 -procedure" for handling messages destined for this window. Applications -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 -communicating with the windows remains exactly the same. The following functions -deal with window registration, creation, and destruction:

- -

    -RegisterClass                -Define a new window class name and associated window procedure
-    -UnRegisterClass            Undefine -a window class
-    CreateWindowEx         Create -an instance of a window of a certain class
-    -DestroyWindow            Destroy a -window instance

- -

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 -DestroyWindow.

- -

When a window is registered, extra bytes can be allocated to the window structure when -created. The GetWindowLong, GetWindowWord, SetWindowLong and SetWindowWord -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.

- -

3.3 Window showing, -hiding and moving

- -

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. -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.

- -

3.4 Window painting

- -

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 -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 -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 -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 -waiting, the UpdateWindow function can be called. The InvalidateRect function -specifies a rectangle to add to the update region, causing a subsequent WM_PAINT.

- -

The window title is automatically painted and is set with the SetWindowText function, -and retrieved with the GetWindowText function.

- -

3.4.1 Client and screen -coordinates

- -

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 -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 -coordinate system is called "client coordinates." As will be explained -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 -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 -reserved by the system for the application's drawing. The GetClientRect and -GetWindowRect functions return client or screen coordinates for the passed window. -ClientToScreen and ScreenToClient can be called to translate between window coordinate -systems.

- -

3.4.2 Device contexts

- -

An applications programmer must obtain a "device context" before calling any -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 -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 -to be specified for every graphics operation. The device context selects the -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.

- -

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, -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 -the DC.

- -

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 -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 -clipping region so that user output will only occur where previously invalidated.

- -

3.4.3 Graphics drawing -API

- -

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.

- -

    -SetTextColor                    -Set the foreground text color in a DC
-    -SetBkColor                      -Set the background color in a DC
-    -GetSysColor                    -Get the system color defined for the current look and feel scheme
-    -SetBkMode                     -Set the use background flag in a DC
-    -SetROP2                         -Set the drawing mode (XOR, SET, etc) for drawing
-    -SetPixel                            -Draw a pixel in the current fg color
-    -MoveToEx                       -Prepare to draw a line
-    -LineTo                              -Draw a line from the last location to this one in the current fg color
-    -Rectangle                          -Draw a rectangle in the current pen color
-    -FillRect                             -Fill a rectangle with the current brush color
-    -TextOut                            -Draw text in the current fg/bg color
-    -ExtTextOut                       -Draw text in the current fg/bg color
-    -DrawText                         -Draw text or compute text height and width sizes
-    -DrawDIB                          -Draw a color bitmap
-    -SelectObject                    -Select a pen, brush or font to use in a DC
-    -GetStockObject               -Get a predefined standard pen, brush or font
-    -CreatePen                        -Create a pen of a certain color
-    -CreateSolidBrush             -Create a brush of a certain color
-    CreateCompatibleBitmap Create an offscreen area to draw onto
-    -DeleteObject                    -Delete a pen, brush or bitmap
-    CreateCompatibleDC        Create an -offscreen DC
-    -DeleteDC                         -Delete an offscreen DC
-    -BitBlit                                -Copy from one bitmap in a DC to another
-    GetSystemPaletteEntries    Get the currently in-use -system palette entries
-

- -

3.5 Utility functions

- -

A number of routines are provided for various purposes, described below. In -addition, Microwindows currently exports some helper routines, named WndXXX, that are -useful but subject to change. These are detailed following:

- -

    -WndSetDesktopWallpaper                -Set the desktop background image
-    -WndSetCursor                                  -Set the cursor for a window
-    -WndRaiseWindow                             -Raise a window's z-order
-    -WndLowerWindow                           -Lower a window's z-order
-    -WndGetTopWindow                         -Return the topmost window's handle
-    -WndRegisterFdInput                          -Register to send a message when file descriptor has read data available
-    -WndUnregisterFdInput                       -Unregister file descriptor for read data messages

- -

-GetTickCount -Return # milliseconds elapsed since startup
- -Sleep -Delay processing for specified milliseconds

- -

3.5.1 Setting window -focus

- -

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 -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 -is the window that is currently highlighted. The GetDesktopWindow routine returns -the window handle of the desktop window.

- -

3.5.2 Mouse capture

- -

Normally, Microwindows sends WM_MOUSEMOVE messages to the window the mouse is currently -moving over. If desired, the 7applications programmer can "capture" the -mouse and receive all mouse move messages by calling SetCapture. ReleaseCapture -returns the processing to normal. In addition, the GetCapture function will return -the window with capture, if any.

- -

3.5.3 Rectangle and -Region management

- -

There are a number of functions that are used for rectangles and regions. -Following is the group:

- -

    -SetRect                        -Define a rectangle structure
-    -SetRectEmpty              -Define an empty rectangle
-    -CopyRect                    -Copy a rectangle
-    -IsRectEmpty                -Return TRUE if empty rectangle
-    -InflateRect                    -Enlarge a rectangle
-    -OffsetRect                    -Move a rectangle
-    -PtInRect                      -Determine if a point is in a rectangle
-

- -

A large number of region management routines are defined and declared in the winrgn.c -file.

- -

4. Nano-X API

- -

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 -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 -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, -instead modeled after the X protocol which was designed for speed on systems where the -client and server machines were different.

- -

4.1 Client/Server model

- -

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 -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 -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 -the client routines parameters to the server function.

- -

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 -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 -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 -directly with the functions in nanox/srvfunc.c, and the nanox/client.c and nanox/srvnet.c -files are not required.

- -

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 -when running the client/server model, and return an error status if the server can't be -found or isn't currently running.

- -

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 -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 -from the queue.

- -

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 -application. Some rewriting is needed to fire up the server when an application -requires it, I believe.

- -

4.2 Events

- -

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 -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 -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 -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, -there is no automatic dispatching. Of course, widget sets serve to provide -object-orientation, but this is in addition to the Nano-X API.

- -

Following are the event types that Nano-X programs can recieve:

- -

GR_EVENT_TYPE_NONE, ERROR, EXPOSURE, BUTTON_DOWN, BUTTON_UP, -MOUSE_ENTER, MOUSE_EXIT, MOUSE_MOTION, MOUSE_POSITION, KEY_UP, KEY_DOWN, FOCUS_IN, -FOCUS_OUT, FDINPUT

- -

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, -and not combined and possibly delayed for better paint throughput as in the Microwindows -API.

- -

4.3 Window creation and destruction

- -

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 -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 -ID that can be used in later calls to get a graphics context or perform window -manipulation.

- -

4.4 Window showing, -hiding and moving

- -

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 -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 -change the position of a window, and GrResizeWindow is used to resize a window.

- -

4.5 Drawing to a window

- -

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 -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 -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 -graphics API call.

- -

4.5.1 Graphics contexts

- -

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 -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 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' -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 -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 -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 -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 -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, -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 -window clipping information and must be released before processing the next message.

- -

4.5.2 Graphics drawing -API

- -

Following are the graphics drawing functions available with Nano-X. Like -Microwindows API, these all match up eventually to the graphics engine GdXXX routines.

- -

    -GrGetGCTextSize                    -Return text width and height information
-    -GrClearWindow                       -Clear a window to it's background color
-    -GrSetGCForeground                -Set the foreground color in a graphics context
-    -GrSetGCBackground               -Set the background color in a graphics context
-    GrSetGCUseBackground         -Set the "use background color" in a graphics context
-    -GrSetGCMode                        -Set the drawing mode
-    -GrSetGCFont                           -Set the font
-    -GrPoint                                     -Draw a point in the passed gc's foreground color
-    -GrLine                                      -Draw a line in the passed gc's foreground color
-    -GrRect                                     -Draw a rectangle in passed gc's foreground color
-    -GrFillRect                                 -Fill a rectangle with the passed gc's foreground color
-    -GrEllipse                                   -Draw a circle or ellipse with the passed gc's foreground color
-    -GrFillEllipse                               -Fill a circle or ellipse with the passed gc's foreground color
-    -GrPoly                                       -Draw a polygon using the passed gc's foreground color
-    -GrFillPoly                                  -Fill a polygon using the passed gc's foreground color
-    -GrText                                       -Draw a text string using the foreground and possibly background colors
-    -GrBitmap                                  -Draw an image using a passed monocrhome bitmap, use fb/bg colors
-    -GrArea                                     -Draw a rectangular area using the passed device-dependent pixels
-    -GrReadArea                             -Read the pixel values from the screen and return them
-    GrGetSystemPaletteEntries        Get -the currently in-use system palette entries
-    GrFindColor                             -Translate an RGB color value to a PIXELVAL pixel value
-

- -

4.6 Utility functions

- -

Various functions serve as utility functions to manipulate windows and provide other -information. These include the following:

- -

    -GrSetBorderColor                    -Set the border color of a window. Not suitable for 3d look and feel.
-    -GrSetCursor                             -Set the cursor bitmap for the window.
-    -GrMoveCursor                         -Move the cursor to absolute screen coordinates.
-    -GrSetFocus                              -Set the keyboard input focus window.
-    -GrRedrawScreen                      -Redraw the entire screen.
-    -GrGetScreenInfo                       -Return information about the size of the physical display.
-    -GrGetWindowInfo                    -Return information about the passed window.
-    -GrGetGCInfo                            -Return information about the passed graphics context.
-    -GrGetFontInfo                          -Return information about the passed font number.
-    -GrRegisterInput                        -Register a file descriptor to return an event when read data available
-    GrPrepareSelect -                       -Prepare the fd_set and maxfd variables for using Nano-X as a passive library
-    GrServiceSelect -                        -Callback the passed GetNextEvent routine when Nano-X has events requiring processing
-    GrMainLoop -                             -A convenience routine for a typical Nano-X application main loop

- - Index: faq.html =================================================================== --- faq.html (revision 1765) +++ faq.html (nonexistent) @@ -1,171 +0,0 @@ - - - - - - - - - - - - -

Microwindows Frequently Asked -Questions

- -

1999/12/04 Microwindows FAQ - greg@censoft.com

- -

What is Microwindows?

- -

Microwindows is an Open Source project that brings some of the features of modern -graphical windowing systems to the programming community not wanting or requiring the -large disk and ram requirements of higher-end windowing systems like Microsoft Windows or -the X Window System. Microwindows does not require any operating system or other -graphics system support, as it writes directly to the display hardware, although it runs -well on Linux framebuffer systems. Microwindows is designed to be portable, and can -run in a wide variety of hardware and software environments. One the of more -interesting targets is the emerging market of portable handheld and pocket PC's running -Linux, also known as LinuxCE.

- -

What does Microwindows run on?

- -

Microwindows currently runs on 32-bit Linux systems with kernel framebuffer support, or -through the popular SVGAlib library. In addition, it has been ported to 16-bit Linux -ELKS, and real-mode MSDOS. Microwindows screen drivers for 1, 2, 4, 8, 16 and 32 -bits-per-pixel have been written, as well as a VGA 16 color 4 planes driver. -Microwindows has been ported to a number of Handheld and Pocket PC's, as well. The -Microwindows graphics engine is capable of running on any system that supports readpixel, -writepixel, drawhorzline and drawvertline, and setpalette. Blitting support is -optional, but if implemented allows enhanced functionality. All bitmap, font, cursor -and color support is implemented on top of these routines. Support for 8, 15, 16 and -32 bit truecolor systems as well as 1, 2, 4 and 8bpp palletized systems is implemented.
-
-Recently, an X11 driver was completed that allows Microwindows applications to be run on -top of the X Window desktop. This driver emulates all of Microwindows' truecolor and -palette modes so that an application can be previewed using the target system's display -characteristics directly on the desktop display, regardless of the desktop display -characteristics.

- -

What CPU's are supported?

- -

Microwindows is extremely portable, and completely written in C, although some routines -have been recoded in assembly for speed. It has been ported to the Intel 16 and 32 -bit cpu's, as well as MIPS R4000 (NEC Vr41xx) and ARM chips found on popular handheld and -pocket PC's.

- -

How big is Microwindows?

- -

On 16 bit systems, the entire system, including screen, mouse and keyboard drivers runs -in less than 64k. On 32-bit systems, support includes proportional fonts and -applications are typically less than 100k.

- -

What is Microwindows' architecture and what API's are supported?

- -

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, -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, -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 -applications programmer. These APIs may or may not provide desktop and/or window -look and feel. Currently, Microwindows supports the Win32 and Nano-X APIs. -These APIs provide close compatibility with the Win32 and X Window systems, allowing -programs to be ported from other systems easily.

- -

What's the difference between Microwindows and NanoGUI?

- -

Microwindows' origin is with NanoGUI. NanoGUI was created by Alex Holden by -taking David Bell's mini-X server and Alan Cox's modifications and adding client/server -networking. Greg Haerr then took interest in the NanoGUI project and began making -extensive enhancements and modifications to NanoGUI. Around version 0.5, Greg Haerr -added support for multiple API's, and began distributing Microwindows. In -Microwindows 0.84, all previous NanoGUI changes were incorporated and since then -Microwindows has been the combined NanoGUI/Microwindows distribution.

- -

What is Nano-X?

- -

Nano-X is the X-like API that Microwindows supports. It is based on David Bell's -mini-X server API, and includes X-like primitives for low-level window and graphics -operations. Window management is not included, and the window look and feel must be -created through a widget set or directly by the applications programmer. Currently, -there are a number of people working on widget sets for Nano-X. There is some -discussion about converting the Nano-X API to be X Window System compatible.

- -

What is the Microwindows API?

- -

Microwindows supports an API based on the Win32 graphics device interface -module, and implements a large portion of it. The function calls try to be 100% -compatible, so that code compiled for other operating systems can usually be -compiled with no source code changes. In addition, a portion of the Win32 -USER module is implemented, which contains routines for window dragging, title -bars, message passing, and generating required window messages. -Because of this, window manager support is built into the system, and a single -API for applications programs can be used that doesn't change based on the -widget set being used.
-
-Since the WinCE API is mostly a subset of the Win32 API for graphics-related -functions, the Microwindows API is also WinCE compatible, and can be used to -implement WinCE graphics functions on platforms Microwindows is running on.

- -

What are Microwindows' graphics features?

- -

Microwindows features full RGB color support, color mapping, optimized palette bitmap -drawing, truecolor and palletized displays, and a 3d look-and-feel. Overlapped and child -windows are supported, with complete window and client area clipping. Proportional and -fixed fonts are supported, along with utilities for converting fonts or bitmap files. -Optimized painting algorithms are used to allow maximum response while the user is moving -windows on the screen. Offscreen drawing and bit-blit routines are implemented for -flicker-free drawing and animation. Polygon draws, fills and arbitrary region clipping are -also supported.

- -

What license is Microwindows under?

- -

The project is licensed under the MPL. Alternatively, the software can be -licensed under the GPL, if desired. This means that the standard Microwindows -distribution can be used for commercial purposes, and supports the needs of developers -working under non-disclosure or writing proprietary device drivers. Modifications to -source code supplied in the standard distribution must stay open source. Or the -entire project can be converted to GPL, with files added by a developer considered GPL -only.

- -

Where is the most current source?

- -

The FTP site ftp://microwindows.censoft.com/pub/microwindows -is the primary distribution point for all releases. The home web site is at http://microwindows.censoft.com. I can be -reached at greg@censoft.com. I am working on -getting the development tree moved to CVS, stay tuned.

- -

Are there screenshots and/or demos available?

- -

There are demos for Linux, ELKS and MSDOS, as well as screenshots, available at:

- -

-
ftp://microwindows.censoft.com/pub/microwindows/ScreenShots
-
ftp://microwindows.censoft.com/pub/microwindows/LinuxExamples - ftp://microwindows.censoft.com/pub/microwindows/ElksExamples - ftp://microwindows.censoft.com/pub/microwindows/DosExamples
-

- -

Is there a mailing list?

- -

The mailing list is nanogui@linuxhacker.org

- -

To subscribe, send an empty email to:

- -

nanogui-subscribe@linuxhacker.org

- -

To unsubscribe, send an empty email to:

- -

nanogui-unsubscribe@linuxhacker.org

- -

What can I do to help?

- -

We need help in all sorts of areas. There are currently projects to port base -level widget sets and custom controls to Microwindows. Fast screen drivers and -blitting routines are also on the list. There are lots of folks interested in -getting the system to run on one of the many new Handheld or Pocket PC's. Please -join the list and join the fun.

- -

- - Index: index.html =================================================================== --- index.html (revision 1765) +++ index.html (nonexistent) @@ -1,201 +0,0 @@ - - - -Greg Haerr's Microwindows and NanoGUI Page - - - - - - - - - - - - - - - - - -

Microwindows and NanoGUI Projects

-

Downloads
- Microwindows
- Screen Shots -
- Linux Binaries -
- ELKS Binaries -
- MSDOS Binaries -

-

Docs
- FAQ
- Architecture

-

Links
- NanoGUI
- Linux CE
- ELKS
- Brad's Linux MIPS Pages
- RTEMS Port

Welcome

-

Microwindows is an Open Source project aimed at bringing the features of modern - graphical windowing environments to smaller devices and platforms. Microwindows - allows applications to be built and tested on the Linux desktop, as well as cross-compiled - for the target device. Microwindows' genesis was with the NanoGUI project, and has - now been combined into a single distribution. The Win32 API implementation is known - as Microwindows, and the Xlib-like API implementation is known as Nano-X. Please read the FAQ for more information. An extensive Architecture document is also available. - To get involved, please join the NanoGUI - mailing list.

-

News

-

Version 0.87pre2 release

-

December 14, 1999
- The second prerelease for version 0.87 has just been released, and is - available for download at:
- ftp://microwindows.censoft.com/pub/microwindows/microwindows-0.87pre2.tar.gz - This release is primarily intended for inspection and testing of the - changes before the directory tree reorganization, planned next.
- The major enhancements include:

-

Portrait mode driver for framebuffer systems. This is a big - win for handhelds and palmtops, many of which require portrait mode - for normal operation. All graphics output, including mouse - movement, hotspots, and text output, are rotated and displayed in - portrait mode. In addition, your Microwindows applications can - be viewed in portrait mode on the desktop. Try moving the mouse - without holding your head sideways!
The RTEMS operating system port source has been integrated with the - main tree.
Fixes to allow Microwindows to be run on big-endian machines are now - included.
Various bug fixes including the Microwindows terminal emulator pty - fix for X11, and Nano-X GrMovewindow fixes for child windows. - There are still some issues relating to Nano-X clipping during window - movement.

-

RTEMS Port

-

December 3, 1999
- There's been alot of interest and development with Microwindows lately. Rosimildo - daSilva has ported Microwindows 0.86 to the RTEMS operating system, available at http://members.xoom.com/rosimildo/rtems_gui.htm. - RTEMS is a POSIX-threads compliant real time - multitasking operating system which runs on Intel, Motorola, Hitachi, Mips, and many other - CPUs.

-

Version 0.87pre1 release

-

December 2, 1999
- I have prepared an interim release of Microwindows and Nano-X enhancements, which - completes many things folks have asked for, version 0.87pre1. This is available for - download at ftp://microwindows.censoft.com/pub/microwindows/microwindows-0.87pre1.tar.gz -
- The major enhancements include:

Support for running under X11. Microwindows and Nano-X can now run as a user-defined - (default 640x480) window under X Windows. The graphics output and look and feel are - identical to framebuffer, but will run on any X display server.

-

Compile-time options allow configuration to emulate any of the Microwindows truecolor or - palette modes, in any pixel depth, including grayscale. This allows a Microwindows or - Nano-X application to be emulated exactly, regardless of the host's or target's - framebuffer characteristics. Thanks to Tony Rogvall for the X11 driver.
-
The client/server network code has been completely rewritten for speed!!! - I studied the - X11 Xlib implementation and came up with a similar implementation. By queuing all client - data until an event or reply is required, Nano-X now runs at extremely high speed. - For benchmarking, use the world demo, which plots several thousand - points. This demo now runs extremely quickly. Unlike - the Xlib implementation, Nano-X still runs synchronously per client, meaning that once a - client request packet is sent, the server waits until the whole packet has arrived until - servicing another client. This keeps the server code immensely simpler, while still - running very quickly. I urge interested folks to check out the implementation, in - mwin/src/nanox/nxproto.{ch}, and mwin/src/nanox/client.c.
-
Routines were added to allow Nano-X to be used as a "passive library", meaning - that an application with it's own main loop can now call into Nano-X occasionally - (after a - select returns a file descriptor that Nano-X is interested in), and it will all work. This - was done for Morten. See mwin/src/nanox/client.c, functions GrPrepareSelect(), - GrServiceSelect(), GrMainLoop().
-
Routines were added to get the system palette, and translate an RGB color to a PIXELVAL - palette index. This was for Richard and the Opera browser. See mwin/src/nanox/srvfunc.c, - functions GrGetSystemPalette, GrFindColor().
-
A null mouse driver was added for systems without a mouse, by setting NOMOUSE=1 in - Makefile.
-
- This is released as 0.87pre1 because I still haven't finished the directory tree - reorganization, and adding Martin's cool X11 graphics makefile configuration tool. The - client/server code rewrite took alot more time than expected. I am also working on getting - all source on CVS.

-

NanoGUI combined with Microwindows

-

November 13, 1999
- Alex Holden, the originator of the NanoGUI project, officially handed over his role to - Greg Haerr, so that the NanoGUI and Microwindows projects can officially be available as a - single distribution. Alex continues to host the Microwindows/NanoGUI mailing list. - Although the releases have been maintained for some time by Greg Haerr, the - official distribution site is now moved here. A big thanks goes to Alex for thinking - up the NanoGUI idea and hosting the initial web site.

-

Opera Web Browser ported to Microwindows

-

November 11, 1999
- The Opera Web Browser, a browser known for it's small - footprint and operation on different operating systems, including Windows, BeOS, Linux, - Solaris, MacOS and OS/2, has announced they have completed initial work porting Opera to - Microwindows. This is a crticial milestone for Microwindows, since it shows that - larger, graphics intensive applications can run on top of the Microwindows graphics - engine. The Opera port uses the Nano-X api and features jpeg and gif image support, - as well as transparent image drawing. The codefile size is 670k. The current - Microwindows footprint is less than 100k with no compiled-in images.

-

Version 0.86 release

-

October 28, 1999
- Thanks to Brad LaRonde for helping me get this web page out. I have posted an update - v0.86 to Microwindows/Nano-X at:

-

-
ftp://microwindows.censoft.com/pub/microwindows/microwindows-0.86.tar.gz -
-

-

This version completes a major effort, that of implementing off-screen drawing, as well - as screen-to-screen blitting. The screen driver interface had to change to accommodate - this, and I had to rewrite all the screen drivers. In addition, the blitting routines were - written for 1, 2, 4, 8, 16 and 32bpp linear framebuffer devices, as well as the 16 color 4 - planes vga (this was a royal pain...) The blitting uses a clipping region traversal - algorithm so that blitting is always high speed, even when the destination window is - partly obscured.

-

This release also auto-detects most Linux framebuffer implementations, and should have - a compiled in driver for it.

-

The standard Microwindows demo is now a graphical terminal emulator, mterm. (No, it - doesn't run vi yet, and it doesn't repaint it's screen contents, but it will ;-) This demo - requires screen-to-screen blitting for scrolling. The 3d graphics demo now uses offscreen - blitting to enhance (read no flicker) the display. Check it out.

-

There is also some experimental full-blown region handling code included, which uses - X11's y-x banding region algorithms. (This stuff is truly for those with extra time and - brains). It is currently not compiled in, but can be included by replacing devclip.c with - devclip2.c. In the next release, arbitrary multi-rectangle clipping regions will be - available. I also plan on implementing separate clip regions from update regions for - windows, with the system computing the update region as a subset of the clip region. - Anyway, this sophisticated region handling is required for smart window painting as well - as higher end graphics primitives. Eventually, this will also allow separate source and - destination clipping for bitblit operations. Only destination clipping is working now.

-

The next release will have a reorganized directory structure, allowing separate - development of Nano-X, widgets, core engine, and Microwindows. I plan on moving the whole - thing to a CVS soon. BTW, Microwindows now supports three processor families, according to - reports emailed me. We've got i386, 8086, MIPS Vr41xx, and ARM families running ;-)

-

Following is a summary of the ChangeLog:
- Version 0.86 - 28th October 1999 - greg@censoft.com

merged framebuffer, elks and msdos vga 16 color 4 planes drivers
wrote vga bitbit routines (a herculean effort)
optimized bitblit by traversing window clip region
added experimental multi-rectangle dynamically allocated regions
wrote scrolling terminal emulator demo for microwindows
added WM_FDINPUT msg, WndRegisterFdInput call for terminal emulator
changed SCREENINFO struct, removed black/white, added bpp, planes
added offscreen (memory DC) drawing to microwindows
added BitBlt, CreateCompatibleBitmap, CreateCompatibleDC, DeleteDC
retired BOGL library, must use new interface for blitting
converted framebuffer, svgalib, elks and msdos screen drivers (we need blit routines for - herc and svgalib still)
major screen driver interface change, old drivers not compatible

-

Page maintained by Greg Haerr <greg@censoft.com>

- -

Browse

Tools

Subversion Repositories or1k

Compare Revisions

Rev 1765 → Rev 673