





                    Sample X/V11 Server
                    Notes for Release 2
	


0.  Read the porting layer definition (x11/doc/Server/ddx.doc.tbl.ms)
    and strategies for porting document (x11/doc/Server/strat.doc.ms)


1.  WHAT'S NOT IMPLEMENTED

o    Motion buffers.  No DDX in the sample implementation supports
     motion history.

2.  WHAT ARE KNOWN PROBLEMS


o    There are performance problems with  text.   Two  areas
     that  we  plan  to look at are the over head in DIX and
     making fixed width font output a special case.


o    MFB code: framebuffers with width > screen width aren't
     handled correctly.  We think the only interface change
     is to mfbScreenInit().


o    There is a problem accessing the cursor font as a 16 bit
     font.  This isn't a problem now, since there are only
     162 glyphs.


o    We haven't tested restricting the size of packets 
     (maxRequestSize in the connection setup information)
     with Xlib.


o    The server needs to be  robust with respect to  failing
     to  allocate   memory.    This   will  require  various
     interface changes.  We expect to make progress on  this
     for the next release.


o    We have made an  effort to get  dix to lint  reasonably
     cleanly.  We  will  be  working  on  other parts of the
     server for the next release.


3.  NOTES ON PORTING


3.1.  Naming  Conventions

     Most  variable names  follow  a  loose  form  of  'Hun-
garian',  used at Xerox and Microsoft.  A name's prefix gen-
erally indicates a type, e.g.  p = pointer, ch =  character,
n  =  number of, pt = point, i = index, and so on.  ppt, for
example, is a pointer to a point, and ich is an index  of  a
character,  and  chFirst  and  chSecond are both characters.
Where the type has not seemed quite as important names  like
theWholeName,  anotherThing,  and valuableProperty are used.
There has been a real efforet to clearly distinguish between
things  and  pointers to things.  Macros are ALL_UPPER_CASE,
unless they are expected to  be  turned  into  in-line  pro-
cedures, or replaced  by less  flexible code.   Functions in
many subdirectories are prefixed  with that directory  name;
e.g. mfbCopyArea, and miCopyArea.


3.2.  Output

     The  output  model  is  heavily   influenced   by   the
protocol's  explicit use of state blocks.  We see three pos-
sible kinds of hardware:

o    No hardware state (e.g. dumb frame buffers)


o    One hardware state block (e.g. vsII/GPX)


o    Multiple hardware state blocks



     For the first case, ValidateGC only needs to swap  pro-
cedure  vectors  in and out, and  compute some accelerators.
For the second case, it  may  want  to  load  some  hardware
registers (although certain mi routines will call ValidateGC
for a different GC before using this one; this is a problem,
and  suggestions are welcome for fixing it.)  The third case
will update some hardware state block somewhere.  Note  that
the  second  case can be made to look like the third case if
there is a device driver that caches several GCs.


     For the second and third cases,   some  work  might  be
done  in  ChangeGC  rather  than  ValidateGC if the graphics
engine has a CPU in it capable of  doing  the  work  itself;
less  intelligent hardware should probably batch the changes
and do the work at validation time.

     The mfb directory contains  a  mostly  complete  sample
implementation;  the  goal  is  to make it runnable, with no
changes except for a compilation switch, on any  1-bit  deep
frame buffer.  (see server/ddx/mfb/maskbits.h)

     The cfb directory contains  a  mostly  complete  sample
implementation;  the  goal  is  to make it runnable, with no
changes except for a compilation switch, on many N-bit  deep
frame buffers.  (see server/ddx/cfb/cfbmskbits.h)

     The calculation of graphics exposures is tedious.   the
mfb  sample  code calls miHandleExposures(), which takes the
same parameter list as CopyArea(); miHandleExposures  clears
any  exposed areas, and sends exposure events to the client,
if the client has requested them.   miHandleExposures()  can
be  used  by  any implementation of CopyArea(), but requires
that  the  region  package  provided  with  the  server   be
installed in the screen's procedure vector.

     There is a utility routine  NotClippedByChildren(pWin),
which  returns  the  window's clip region if drawing through
children is wanted; this happens  when  gc.subWindowMode  ==
IncludeInferiors.



3.3.  Which output routines should be replaced?

     We strongly recommend optimizing, in order,

o    CopyArea (or in the case of mfb,  the  helper  function
     mfbDoBitblt(), which is called from numerous places),

o    ImageText with fixed-width characters (used for  termi-
     nal emulators),

o    lines with linewidth == 0,

o    filled rectangles,

o    PolyText

     Doing most or all of the work testing for fill  styles,
alu  values,  and  so  on, in ValidateGC() seems to be a big
win; doing this shortens the drawing path by  several  tests
and  often  a  procedure call or two.  Procedure vectors are
one of the more pervasive features of the server,  and  they
are almost all loadable at runtime.


3.4.  Input

     It is important for  time-stamp  sequencing   that  the
mouse  and keyboard be merged into one stream at the device-
driver level.  The incoming events must be timestamped.

     Note  that  input  is  weighted  very  heavily  in  the
dispatch  loop  and  that  ProcessInputEvents() should be an
inexpensive operation.   Input  is  processed  between  each
client  output request.  See SetInputCheck() in DDX document
(section 2.2).


3.5.  General Notes:


3.5.1.  Stack Usage:

             The output  routines,  even  with  the  messier
machine  independent  ones,  do  not nest very far.  miVali-
dateTree, however, is recursive, and we make  heavy  use  of
the  ALLOCATE_LOCAL macro, which gives us temporary storage;
under Unix, this allocates  space  on  the  stack,  whch  is
cheaper  than  allocating  temporary  buffers  on  the heap.
There may be problems on machines with  small  stacks  (e.g.
the Intel 286.)


3.5.2.  Word Size

             The sample assumes that 32 bit  operations  are
the most efficient.  This is mostly evident in the mfb code.

             The  sample  dix  code  and  headers  have been
cleaned up  considerable  with  respect  to assumptions that
ints are 32 bits, but there is still a long way to go,  both
in dix and in the ddx and os layers.  This is not a priority
for us, although we will do what we can.
