| KERNEL MODULE |
| ============= |
| |
| ... |
| |
| GDI MODULE |
| ========== |
| |
| 1. X Windows System interface |
| ----------------------------- |
| |
| The X libraries used to implement X clients (such as Wine) do not work |
| properly if multiple threads access the same display concurrently. It is |
| possible to compile the X libraries to perform their own synchronization |
| (initiated by calling XInitThreads()). However, Wine does not use this |
| approach. Instead Wine performs its own synchronization py putting a |
| wrapper around every X call that is used. This wrapper protects library |
| access with a critical section, and also arranges things so that X |
| libraries compiled without -D_REENTRANT (eg. with global errno variable) |
| will work with Wine. |
| |
| To make this scheme work, all calls to X must use the proper wrapper |
| functions (or do their own synchronization that is compatible with the |
| wrappers). The wrapper for a function X...() is calles TSX...() (for |
| "Thread Safe X ..."). So for example, instead of calling XOpenDisplay() |
| in the code, TSXOpenDisplay() must be used. Likewise, X include files |
| that contain function prototypes are wrapped, so that eg. "ts_xutil.h" |
| must be included rather than <X11/Xutil.h>. It is important that this |
| scheme is used everywhere to avoid the introduction of nondeterministic |
| and hard-to-find errors in Wine. |
| |
| The code for the thread safe X wrappers is contained in the tsx11/ |
| directory and in include/ts*.h. To use a new (ie. not previously used) X |
| function in Wine, a new wrapper must be created. The wrappers are |
| generated (semi-)automatically from the X11R6 includes using the |
| tools/make_X11wrappers perl script. In simple cases it should be enough |
| to add the name of the new function to the list in tsx11/X11_calls; if |
| this does not work the wrapper must be added manually to the |
| make_X11wrappers script. See comments in tsx11/X11_calls and |
| tools/make_X11wrappers for further details. |
| |
| |
| USER MODULE |
| =========== |
| |
| USER implements windowing and messaging subsystems. It also |
| contains code for common controls and for other miscellaneous |
| stuff (rectangles, clipboard, WNet, etc). Wine USER code is |
| located in windows/, controls/, and misc/ directories. |
| |
| 1. Windowing subsystem |
| ---------------------- |
| |
| windows/win.c |
| windows/winpos.c |
| |
| Windows are arranged into parent/child hierarchy with one |
| common ancestor for all windows (desktop window). Each window |
| structure contains a pointer to the immediate ancestor (parent |
| window if WS_CHILD style bit is set), a pointer to the sibling |
| (returned by GetWindow(..., GW_NEXT)), a pointer to the owner |
| window (set only for popup window if it was created with valid |
| hwndParent parameter), and a pointer to the first child |
| window (GetWindow(.., GW_CHILD)). All popup and non-child windows |
| are therefore placed in the first level of this hierarchy and their |
| ancestor link (wnd->parent) points to the desktop window. |
| |
| Desktop window - root window |
| | \ `-. |
| | \ `-. |
| popup -> wnd1 -> wnd2 - top level windows |
| | \ `-. `-. |
| | \ `-. `-. |
| child1 child2 -> child3 child4 - child windows |
| |
| Horizontal arrows denote sibling relationship, vertical lines |
| - ancestor/child. To summarize, all windows with the same immediate |
| ancestor are sibling windows, all windows which do not have desktop |
| as their immediate ancestor are child windows. Popup windows behave |
| as topmost top-level windows unless they are owned. In this case the |
| only requirement is that they must precede their owners in the top-level |
| sibling list (they are not topmost). Child windows are confined to the |
| client area of their parent windows (client area is where window gets |
| to do its own drawing, non-client area consists of caption, menu, borders, |
| intrinsic scrollbars, and minimize/maximize/close/help buttons). |
| |
| Another fairly important concept is "z-order". It is derived from |
| the ancestor/child hierarchy and is used to determine "above/below" |
| relationship. For instance, in the example above, z-order is |
| child1->popup->child2->child3->wnd1->child4->wnd2->desktop. Current |
| active window ("foreground window" in Win32) is moved to the front |
| of z-order unless its top-level ancestor owns popup windows. |
| |
| All these issues are dealt with (or supposed to be) in windows/winpos.c |
| with SetWindowPos() being the primary interface to the window manager. |
| |
| Wine specifics: in default and managed mode each top-level window |
| gets its own X counterpart with desktop window being basically a |
| fake stub. In desktop mode, however, only desktop window has an X |
| window associated with it. Also, SetWindowPos() should eventually be |
| implemented via Begin/End/DeferWindowPos() calls and not the other way |
| around. |
| |
| 1.1 Visible region, clipping region and update region |
| |
| windows/dce.c |
| windows/winpos.c |
| windows/painting.c |
| |
| ________________________ |
| |_________ | A and B are child windows of C |
| | A |______ | |
| | | | | |
| |---------' | | |
| | | B | | |
| | | | | |
| | `------------' | |
| | C | |
| `------------------------' |
| |
| Visible region determines which part of the window is not obscured |
| by other windows. If a window has the WS_CLIPCHILDREN style then all |
| areas below its children are considered invisible. Similarily, if |
| the WS_CLIPSIBLINGS bit is in effect then all areas obscured by its |
| siblings are invisible. Child windows are always clipped by the |
| boundaries of their parent windows. |
| |
| B has a WS_CLIPSIBLINGS style: |
| . ______ |
| : | | |
| | ,-----' | |
| | | B | - visible region of B |
| | | | |
| : `------------' |
| |
| When the program requests a display context (DC) for a window it |
| can specify an optional clipping region that further restricts the |
| area where the graphics output can appear. This area is calculated |
| as an intersection of the visible region and a clipping region. |
| |
| Program asked for a DC with a clipping region: |
| ______ |
| ,--|--. | . ,--. |
| ,--+--' | | : _: | |
| | | B | | => | | | - DC region where the painting will |
| | | | | | | | be visible |
| `--|-----|---' : `----' |
| `-----' |
| |
| When the window manager detects that some part of the window |
| became visible it adds this area to the update region of this |
| window and then generates WM_ERASEBKGND and WM_PAINT messages. |
| In addition, WM_NCPAINT message is sent when the uncovered area |
| intersects a nonclient part of the window. Application must reply |
| to the WM_PAINT message by calling BeginPaint()/EndPaint() pair of |
| functions. BeginPaint() returns a DC that uses accumulated update |
| region as a clipping region. This operation cleans up invalidated |
| area and the window will not receive another WM_PAINT until the |
| window manager creates a new update region. |
| |
| A was moved to the left: |
| ________________________ ... / C update region |
| |______ | : .___ / |
| | A |_________ | => | ...|___|.. |
| | | | | | : | | |
| |------' | | | : '---' |
| | | B | | | : \ |
| | | | | : \ |
| | `------------' | B update region |
| | C | |
| `------------------------' |
| |
| |
| Windows maintains a display context cache consisting of entries that |
| include DC itself, window to which it belongs, and an optional clipping |
| region (visible region is stored in the DC itself). When an API call |
| changes the state of the window tree, window manager has to go through |
| the DC cache to recalculate visible regions for entries whose windows |
| were involved in the operation. DC entries (DCE) can be either private |
| to the window, or private to the window class, or shared between all |
| windows (Windows 3.1 limits the number of shared DCEs to 5). |
| |
| 1.2 |
| |
| 2. Messaging subsystem |
| ---------------------- |
| |
| windows/queue.c |
| windows/message.c |
| |
| Each Windows task/thread has its own message queue - this is where |
| it gets messages from. Messages can be generated on the fly |
| (WM_PAINT, WM_NCPAINT, WM_TIMER), they can be created by the system |
| (hardware messages), they can be posted by other tasks/threads |
| (PostMessage), or they can be sent by other tasks/threads (SendMessage). |
| |
| Message priority: |
| |
| First the system looks for sent messages, then for posted messages, |
| then for hardware messages, then it checks if the queue has the |
| "dirty window" bit set, and, finally, it checks for expired |
| timers. See windows/message.c. |
| |
| From all these different types of messages, only posted messages go |
| directly into the private message queue. System messages (even in |
| Win95) are first collected in the system message queue and then |
| they either sit there until Get/PeekMessage gets to process them |
| or, as in Win95, if system queue is getting clobbered, a special |
| thread ("raw input thread") assigns them to the private |
| queues. Sent messages are queued separately and the sender sleeps |
| until it gets a reply. Special messages are generated on the fly |
| depending on the window/queue state. If the window update region is |
| not empty, the system sets the QS_PAINT bit in the owning queue and |
| eventually this window receives a WM_PAINT message (WM_NCPAINT too |
| if the update region intersects with the non-client area). A timer |
| event is raised when one of the queue timers expire. Depending on |
| the timer parameters DispatchMessage either calls the callback |
| function or the window procedure. If there are no messages pending |
| the task/thread sleeps until messages appear. |
| |
| There are several tricky moments (open for discussion) - |
| |
| a) System message order has to be honored and messages should be |
| processed within correct task/thread context. Therefore when |
| Get/PeekMessage encounters unassigned system message and this |
| message appears not to be for the current task/thread it should |
| either skip it (or get rid of it by moving it into the private |
| message queue of the target task/thread - Win95, AFAIK) and |
| look further or roll back and then yield until this message |
| gets processed when system switches to the correct context |
| (Win16). In the first case we lose correct message ordering, in |
| the second case we have the infamous synchronous system message |
| queue. Here is a post to one of the OS/2 newsgroup I found to |
| be relevant: |
| |
| " Here's the problem in a nutshell, and there is no good solution. |
| Every possible solution creates a different problem. |
| |
| With a windowing system, events can go to many different windows. |
| Most are sent by applications or by the OS when things relating to |
| that window happen (like repainting, timers, etc.) |
| |
| Mouse input events go to the window you click on (unless some window |
| captures the mouse). |
| |
| So far, no problem. Whenever an event happens, you put a message on |
| the target window's message queue. Every process has a message |
| queue. If the process queue fills up, the messages back up onto the |
| system queue. |
| |
| This is the first cause of apps hanging the GUI. If an app doesn't |
| handle messages and they back up into the system queue, other apps |
| can't get any more messages. The reason is that the next message in |
| line can't go anywhere, and the system won't skip over it. |
| |
| This can be fixed by making apps have bigger private message queues. |
| The SIQ fix does this. PMQSIZE does this for systems without the SIQ |
| fix. Applications can also request large queues on their own. |
| |
| Another source of the problem, however, happens when you include |
| keyboard events. When you press a key, there's no easy way to know |
| what window the keystroke message should be delivered to. |
| |
| Most windowing systems use a concept known as "focus". The window |
| with focus gets all incoming keyboard messages. Focus can be changed |
| from window to window by apps or by users clicking on winodws. |
| |
| This is the second source of the problem. Suppose window A has focus. |
| You click on window B and start typing before the window gets focus. |
| Where should the keystrokes go? On the one hand, they should go to A |
| until the focus actually changes to B. On the other hand, you |
| probably want the keystrokes to go to B, since you clicked there |
| first. |
| |
| OS/2's solution is that when a focus-changing event happens (like |
| clicking on a window), OS/2 holds all messages in the system queue |
| until the focus change actually happens. This way, subsequent |
| keystrokes go to the window you clicked on, even if it takes a while |
| for that window to get focus. |
| |
| The downside is that if the window takes a real long time to get focus |
| (maybe it's not handling events, or maybe the window losing focus |
| isn't handling events), everything backs up in the system queue and |
| the system appears hung. |
| |
| There are a few solutions to this problem. |
| |
| One is to make focus policy asynchronous. That is, focus changing has |
| absolutely nothing to do with the keyboard. If you click on a window |
| and start typing before the focus actually changes, the keystrokes go |
| to the first window until focus changes, then they go to the second. |
| This is what X-windows does. |
| |
| Another is what NT does. When focus changes, keyboard events are held |
| in the system message queue, but other events are allowed through. |
| This is "asynchronous" because the messages in the system queue are |
| delivered to the application queues in a different order from that |
| with which they were posted. If a bad app won't handle the "lose |
| focus" message, it's of no consequence - the app receiving focus will |
| get its "gain focus" message, and the keystrokes will go to it. |
| |
| The NT solution also takes care of the application queue filling up |
| problem. Since the system delivers messages asynchronously, messages |
| waiting in the system queue will just sit there and the rest of the |
| messages will be delivered to their apps. |
| |
| The OS/2 SIQ solution is this: When a focus-changing event happens, |
| in addition to blocking further messages from the application queues, |
| a timer is started. When the timer goes off, if the focus change has |
| not yet happened, the bad app has its focus taken away and all |
| messages targetted at that window are skipped. When the bad app |
| finally handles the focus change message, OS/2 will detect this and |
| stop skipping its messages. |
| |
| |
| As for the pros and cons: |
| |
| The X-windows solution is probably the easiest. The problem is that |
| users generally don't like having to wait for the focus to change |
| before they start typing. On many occasions, you can type and the |
| characters end up in the wrong window because something (usually heavy |
| system load) is preventing the focus change from happening in a timely |
| manner. |
| |
| The NT solution seems pretty nice, but making the system message queue |
| asynchronous can cause similar problems to the X-windows problem. |
| Since messages can be delivered out of order, programs must not assume |
| that two messages posted in a particular order will be delivered in |
| that same order. This can break legacy apps, but since Win32 always |
| had an asynchronous queue, it is fair to simply tell app designers |
| "don't do that". It's harder to tell app designers something like |
| that on OS/2 - they'll complain "you changed the rules and our apps |
| are breaking." |
| |
| The OS/2 solution's problem is that nothing happens until you try to |
| change window focus, and then wait for the timeout. Until then, the |
| bad app is not detected and nothing is done." (by David Charlap) |
| |
| |
| b) Intertask/interthread SendMessage. The system has to inform the |
| target queue about the forthcoming message, then it has to carry |
| out the context switch and wait until the result is available. |
| Win16 stores necessary parameters in the queue structure and then |
| calls DirectedYield() function. However, in Win32 there could be |
| several messages pending sent by preemptively executing threads, |
| and in this case SendMessage has to build some sort of message |
| queue for sent messages. Another issue is what to do with messages |
| sent to the sender when it is blocked inside its own SendMessage. |
| |
| |