xorg-server-1.4/hw/xfree86/xf4bpp/NOTES

   1 This code originally hails from IBM.  It was ported to an early XFree86 by
   2 Gertjan Akkerman, whose BUGS file I append here.
   3
   4 In turn, this is a port of Gertjan's work to the new server design.  Among the
   5 changes are:
   6
   7 - The removal of almost all unreferenced code.
   8 - The removal of this code's own copy of mfb (xf1bpp is used instead).
   9 - The removal of banking support (mibank is used instead).
  10 - External symbols were made static where this was sufficient.
  11 - The remaining external names were renamed to xf4bpp*.
  12 - Several minor cleanups too many to mention here.
  13
  14 To understate the matter, this code is >UGLY<.  This seems inherent in IBM's
  15 corporate culture.  Be that as it may, it *does* survive X11R4's xtest
  16 (whatever that means these days...).  For now, this is sufficient for 4bpp
  17 support in the new design, but at some point, I'll have to sit down and
  18 rewrite this from scratch.  A more technical justification for a rewrite is
  19 that the pixmap format is 8bpp, instead of 4bpp, which is causing me to
  20 pepper the rest of the server with unclean accomodations.
  21
  22 Marc.
  23
  24 ===============================================================================
  25 Section 1: From IBM's X11R4 contribution towards XFree86.
  26
  27 This section describes what I did to obtain a 16 colour vga server.
  28
  29 I started with the SYSV, ppc, vga and common directories from IBM's X11R4
  30 contribution. Those directories have the following function:
  31 1. SYSV implements the mouse and keyboard.
  32 2. ppc is a generic layer implementing ddx in terms of drawing operations
  33    through rectangles. (With spans as a boundary case: height = 1.)
  34 3. vga implements a layer of operations drawing through rectangles.
  35 4. common implements ddx initialization and quitting, and screen saving.
  36
  37 I eliminated SYSV and common since the functionality provided therein is
  38 already provided in XFree86. Since XFree86 is actively being ported to
  39 new operating systems, while X11R4 is out of date, I preferred the XFree86
  40 code here above the SYSV and common code.
  41 Whatever functionality was still needed from common (default colormap
  42 initialization -- not much code) was moved into ppc.
  43
  44 Since XFree86 uses the mi-provided software cursor code, IBM's software
  45 cursor code was deleted from ppc and vga. This is a pity, since it is
  46 expected that it is more efficient than mi's code, but the XFree86 mouse and
  47 keyboard code directly call mi, and I do not want to maintain the XFree86
  48 mouse and keyboard code.
  49
  50 Since we cannot support a monolithic multi-screen server using all of the
  51 x11r4 contributed code yet, all multi screen code was deleted. This includes
  52 one header file containing a nasty copyright statement.
  53
  54 Since glyph handling has changed between X11R4 and X11R5, the code handling
  55 glyphs was replaced by appropriate calls to mi.
  56 I hope it can be modified and put back one day.
  57
  58 Provisionally, some code was added (viz. file vga/offscreen.c) to intercept
  59 calls to the rectangle drawing code when we are switched out of the VT.
  60 I hope this can be replaced by some window tree invalidation and GC validation
  61 scheme.
  62
  63
  64 Section 2: BUGS
  65
  66 This section describes fixed and still unfixed bugs in this code.
  67 All bugs not labeled otherwise also occur in IBM's X11R4 code, and may be of
  68 interest to anybody using that code.
  69
  70 1. (Fixed.)
  71 I found (and provisionally fixed) a bug in the IBM bitblit code:
  72 In file ddx/ibm/vga/vgaImages.c a function vgaReadColorImage is defined.
  73 When this function is used to read less than 8 pixels starting on a byte
  74 boundary it will always read precisely 8 pixels.
  75 Thus, when space is allocated for 4 or less pixels, it will write beyond
  76 the allocated space.
  77 Since the code is rather convoluted, this may not be apparent at first sight,
  78 but going through the code with an example shows the error.
  79
  80 2. (Fixed.)
  81 In ppcPixmapFS.c, function ppcStipplePixmapFS there was a bug
  82 regarding the stipple origin: The horizontal origin is added while
  83 the vertical one is subtracted. The horizontal origin should be subtracted
  84 instead of added here.
  85 This bug gets visible when backing-store is enabled and one uses twm:
  86 the submenu icons get truncated on their left hand side.
  87 (In case you wonder why this bug appears: under those circumstances
  88 twm prepares its menus by drawing into an unmapped window.
  89 The miCopyPlane function uses the ppcStipplePixmap (and many others)
  90 to get the plane copied.)
  91 I also fixed this bug in the other routines (ppcOpStipplePixmapFS,
  92 ppcTilePixmapFS) in this file, although I had no visible clues for this.
  93 I hope this is appropriate.
  94
  95 3. (Fixed.)
  96 I find it suspect that ppcSetSpans gives different output when one
  97 claims that an actually sorted list of spans is unsorted.
  98 The unsorted code is wrong, and should be made to look more like the sorted
  99 code. I.e., use ( xStart - ppt->x ) instead of ( xStart - pbox->x1 )
 100
 101 4. (Fixed.)
 102 There used to be another bug that became visible when using twm and backing
 103 store: popping up a submenu, and moving the cursor upwards til it leaves the
 104 submenu, the submenu would disappears, as it should.
 105 But the submenu icon would not get restored, while it should be.
 106 10b. By replacing the clip-computing code in ppcValidateGC by that in
 107 cfbValidateGC, I *finally* fixed the disappearing twm menu icon problem.
 108
 109 5. Added mfbRegisterCopyplaneProc call. [Its omission was an error on my
 110    part.]
 111    Fixing a server core dump in XTest.
 112
 113 6. Fixed not-very-high tile bug in function ppcTileRect, file emulTile.c
 114    (I.e., if the tile was higher than the area to be tiled, far too much
 115    was drawn, causing server core dumps in XTest.)
 116    Actually, "savey" ought to be used to determine the height of the tiles in
 117    the top line to be tiled, instead of "pTile->drawable.height".
 118 7. A use of height where width was intended was fixed in ppcTileRect:
 119    "savehcount = w / pTile->drawable.height;" should use "... .width" and
 120    "savehcount = ( x + w - htarget ) / pTile->drawable.height;" too.
 121
 122 8. Deleted overly clever code in ppcCReduce.c
 123    (All code that tried to pre-compute how alu's could be replaced by
 124     other alu's with inverted colors, etc. was deleted. I think it is
 125    at least wrong for FillSolid.)
 126
 127 9. Looked at suspicious code in ppcSetSp.c
 128    "tmpx = *pdst;" was never updated during the loop. We took it out of the
 129    initialization position of the for and moved it into the loop.
 130
 131 10. Add xSrc := GC->patOrg.x + pDrawable.x and ySrc := ... in ppcPixmapFS.c,
 132    functions ppcStipplePixmapFS, ppcOpStipplePixmapFS, and ppcTilePixmapFS.
 133    This because stipple and tile origins are taken relative to the drawable.
 134    Also use a "modulo" function that gets the cases of a negative stipple
 135    or tile offset right. (When the stipple origin is to the right of or
 136    below the origin of the drawable.)
 137
 138 11. File vgaSolid.c, function vgaFillSolid:
 139    Inverting is XORing with all ones. Not with the color we want to AND/OR
 140    later. So we'll have to set the color to VGA_ALLPLANES
 141    whenever we want to invert existing data, and reset it before the
 142    AND/OR is done.
 143    Also we replaced an outb( 0x3CF, tmp2 ) by the SetVideoGraphicsData( tmp2 )
 144    it is representing. (Just a cosmetic replacement.)
 145
 146 12. File vgaImages, function vgaDrawColorImage.
 147    Moved a line "invert_existing_data = TRUE;" two lines down, past a case
 148    label. Now it is also part of the code executed for GXorReverse, as it
 149    should be.
 150
 151 13. The pixmap FillSpans routines (file ppcPixmapFS.c) got somewhat better
 152    after importing some code from ddx/ibm/vga. (A getbits function that does
 153    wrapping.)
 154    They were wrong for the FillStippled and FillOpaqueStippled modes.
 155    I don't understand the old code. How could it handle stipples of a size not
 156    an exact multiple of 32? (or 8, for that matter.)
 157
 158 14. In function vgaBitBlt file vgaBitBlt.c, in the shortcuts for
 159     GXSet, GXClear and GXInvert, the source (x0,y0) is accidentally operated
 160     upon by vgaFillSolid, instead of the destination (x1,y1).
 161
 162 15. Notice that in DoMonoSingle and DoMonoMany in file vgaStipple.c, the left
 163    edge of the square to be stippled is treated wrong.
 164    Correct would be to get the bits with getbits using offset xshift, and
 165    to shift them right (x & 07) places.
 166    [One might wish to use the variable tmp1 at this place, since it had been
 167     set to (x & 07) at this place; but that is already re-used at this point.]
 168    Also note that NeedValX is set wrong: The implicit assumption was that
 169    stipples are more than 8 wide.
 170    This only fixes the problem when miPushPixel is used instead of ppcPushPixel.
 171    I think I should look some more into this.
 172
 173 16. I took out some code of the CopyArea function, in which a no-op function
 174    was called while a real one was needed. My fix does not completely work,
 175    although it improved the behaviour of GetImage somewhat.
 176
 177 17.  After finding three kinds of errors in this single function,
 178    -- the new kinds being the right side not being always written due to
 179    an incorrect if scope, and the lower end not always being written due
 180    to variables being updated at the wrong place --
 181    (requiring modifications to be made at at least 10 places,
 182    I decided to REWRITE the body of the ppcTileRect function from scratch.
 183    This version simply computes all relevant margins in advance, and does
 184    not try to reuse temporary variables. I leave that to the compiler.
 185    (This was a maintenance and robustness nightmare anyway.)
 186
 187 MORE NOTES:
 188    It is funny that there are two files in mi that require compilation
 189    with the proper #defines ( -DXF86VGA16  in my case ):
 190    Besides the obvious mibitblt.c, there is also mipushpxl.c.
 191
 192
 193
 194 $XFree86: xc/programs/Xserver/hw/xfree86/xf4bpp/NOTES,v 1.1.2.2 1998/06/27 15:15:45 dawes Exp $