Subject: PSARC FastTrack [03/31/2005]: Update libXmu to X11R6.8 version

I am sponsoring this fasttrack for the X11 & Solaris x86 video driver teams.
It times out on March 31, 2005, and does not contain any references to
stability levels beginning with "E" which may cause undue distress to ARC
member's mailboxes.

Template Version: @(#)sac_nextcase 1.55 08/11/04 SMI
This information is Copyright 2005 Sun Microsystems, Inc.  All Rights Reserved.
1. Introduction
    1.1. Project/Component Working Name:
	 Update libXmu to X11R6.8 version
    1.2. Name of Document Author/Supplier:
	 Author:  Alan Coopersmith
    1.3  Date of This Document:
	24 March, 2005
4. Technical Description

This project updates libXmu to the version included in the X.Org X11R6.8 
release, adding a number of new functions, and making one addition to the
file search path used by a pair of functions, but making no incompatible 
changes.  As such, it requests micro/patch binding.

Changes:

Details of the added functions are listed at the end of this document.   
All new functions come directly from the X.Org open source release unchanged.

The existing functions being changed are XmuLocateBitmapFile() and 
XmuLocatePixmapFile().   They take a string "name" naming a bitmap or 
pixmap file and locate it at the first location found in this list:
     1.  name if it begins with / or ./
     2.  each prefix in bitmapFilePath global X Resource/name
     3.  <ProjectRoot>/include/X11/bitmaps/name
     4.  name if didn't begin with / or .

<ProjectRoot> on Solaris has traditionally been /usr/openwin.   PSARC 2004/187
started the process of moving X on Solaris to /usr/X11.   This case takes
another step along that path by inserting /usr/X11/include/X11/bitmaps/name
between 3 and 4 in the above list, resulting in:
     1.  name if it begins with / or ./
     2.  each prefix in bitmapFilePath global X Resource/name
     3.  /usr/openwin/include/X11/bitmaps/name
     4.  /usr/X11/include/X11/bitmaps/name
     5.  name if didn't begin with / or .

Stability:

The Xmu source from X.Org has always contained this statement:

  This library contains miscellaneous utilities and is not part of the Xlib
  standard.  It contains routines which only use public interfaces so that it
  may be layered on top of any proprietary implementation of Xlib or Xt.

  It is intended to support clients in the MIT distribution; vendors
  may choose not to distribute this library if they wish.  Therefore,
  applications developers who depend on this library should be prepared to
  treat it as part of their software base when porting.

However, Sun has shipped it in every release of Solaris, and added public
functions to it which we document for applications to call, such as
XSolarisGetVisualGamma() and XSolarisCheckColormapEquivalence().   It has
previously been classified as Standard, so this case follows the existing
precedence.

(I can't actually find any previous ARC cases for this library, which was
 introduced into X11R4.   The earliest ARC reference I can find is in the 
 X11R5 client libraries one-pager, 19911203_stuart.wells which does not seem 
 to have become an ARC case.   The patch database shows it was shipped at least
 as far back as OpenWindows 3.0 for SunOS 4.1.1.  However, several other 
 cases imported this library as Standard, thus it is assumed to be classified 
 at that level.)

Imported interfaces:

libXmu.so.4				Standard	MIT/X Consortium/
<X11/Xmu/CharSet.h>			Standard	 The Open Group/
<X11/Xmu/Convertors.h>			Standard	 X.Org source releases
<X11/Xmu/SysUtil.h>			Standard
<X11/Xmu/Xmu.h>				Standard
Existing bitmap file search path	Standard ?
/usr/openwin hierarchy			Obsolete	PSARC 2004/187
/usr/X11 hierarchy			Stable		PSARC 2004/187

Exported interfaces:

New Xmu functions defined below		Standard	X.Org X11R6.8 source
Bitmap file search path entries:
 /usr/openwin/include/X11/bitmaps/	Obsolete
 /usr/X11/include/X11/bitmaps/		Stable

------------------------------------------------------------------------------

Details of newly added functions:
=================================

Defined in <X11/Xmu/CharSet.h>:

 void XmuNCopyISOLatin1Lowered(char *dst_return, const char *src, int size);
 void XmuNCopyISOLatin1Uppered(char *dst_return, const char *src, int size);

 These are size-limited counterparts to the existing XmuCopyISOLatin1Lowered
 and XmuCopyISOLatin1Uppered, to simplify buffer-overflow prevention in 
 callers. The only difference between those functions and these is the
 addition of a size parameter, which operates like the similar parameter to 
 strlcpy(3c) - the function will copy (and case-convert as appropriate) no 
 more than size - 1 characters and will ensure that the string copied to the
 dst buffer is null-terminated.
 
Defined in <X11/Xmu/Convertors.h>:
 
 Boolean XmuCvtBackingStoreToString
 (Display *dpy, XrmValue *args, Cardinal *num_args,
  XrmValuePtr fromVal, XrmValuePtr toVal, XtPointer *converter_data);
 
 Boolean XmuCvtGravityToString
 (Display *dpy, XrmValue *args, Cardinal *num_args,
  XrmValuePtr fromVal, XrmValuePtr toVal, XtPointer *converter_data);
 
 Boolean XmuCvtJustifyToString
 (Display *dpy, XrmValue *args, Cardinal *num_args,
  XrmValuePtr fromVal, XrmValuePtr toVal, XtPointer *converter_data);
 
 Boolean XmuCvtLongToString
 (Display *dpy, XrmValue *args, Cardinal *num_args,
  XrmValuePtr fromVal, XrmValuePtr toVal, XtPointer *converter_data);
 
 Boolean XmuCvtOrientationToString
 (Display *dpy, XrmValue *args, Cardinal *num_args,
  XrmValuePtr fromVal, XrmValuePtr toVal, XtPointer *converter_data);
 
 Boolean XmuCvtShapeStyleToString
 (Display *dpy, XrmValue *args, Cardinal *num_args,
  XrmValuePtr fromVal, XrmValuePtr toVal, XtPointer *converter_data);
 
 Boolean XmuCvtWidgetToString
 (Display *dpy, XrmValue *args, Cardinal *num_args,
  XrmValuePtr fromVal, XrmValuePtr toVal, XtPointer *converter_data);
 
 These new functions are the complements to the existing XmuCvtStringTo*
 functions, for converting data back in the other direction.   They are
 standard Xt conversion functions, following the conventions and argument
 defintions shown in the XtConvert(3Xt) manual page.
 
Defined in <X11/Xmu/SysUtil.h>:

 int XmuSnprintf(char *str, int size, const char *fmt, ...);

 A platform independent function providing the snprintf(3c) interface for
 easier portability to platforms without a native snprintf.   On Solaris
 and other platforms with snprintf in libc, it is simply a wrapper around
 vsnprintf(3c).

Defined in <X11/Xmu/Xmu.h>:

 A new set of routines for managing clipping information in client software.
 An "area" is defined as a set of "scanlines", which are horizontal rows in
 the area.   A "scanline" contains a set of "segments" which are contigous
 values in the scanline considered to be part of the clipping region.

 typedef struct _XmuSegment {
   int x1, x2;
   struct _XmuSegment *next;
 } XmuSegment;
 
 typedef struct _XmuScanline {   
   int y;
   XmuSegment *segment;
   struct _XmuScanline *next;
 } XmuScanline;
                               
 typedef struct _XmuArea {
   XmuScanline *scanline;     
 } XmuArea;
 
 XmuArea *XmuNewArea(int x1, int y1, int x2, int y2);

       	Creates a new rectangular clipping area with the given bounding points.

 #define XmuCreateArea()		XmuNewArea(0, 0, 0, 0)

	Creates an empty area. 

 #define XmuDestroyArea(a)

	Frees all scanlines in the area and then frees the area itself.

 #define FreeArea(a)

	Frees all scanlines in the area and but does not free the area itself,
	instead leaving it empty.

 XmuArea *XmuAreaDup(XmuArea *area);

	Creates a new clipping area that is a duplicate of the argument.

 XmuArea *XmuAreaCopy(XmuArea *dst, XmuArea *src);

	Makes dst a duplicate of src.

 XmuArea *XmuAreaNot(XmuArea *area, int x1, int y1, int x2, int y2);

	Modifies area to contain the region inside the specified rectangle
	but not contained in the existing region of area.

 XmuArea *XmuAreaOrXor(XmuArea *dst, XmuArea *src, Bool or);
 #define XmuAreaOr(dst, src)	XmuAreaOrXor((dst), (src), True)
 #define XmuAreaXor(dst, src)	XmuAreaOrXor((dst), (src), False)

	Executes Or (Union) or Xor (Reverse intesection) of the areas.
	(If the "or" argument is true, performs Or, else Xor.)

 XmuArea *XmuAreaAnd(XmuArea *dst, XmuArea *src);

	Executes And (intersection) of the areas


 #define XmuValidSegment(s)

	Verifies if a segment contains any points.

 Bool XmuValidScanline(XmuScanline* scanline);

	Verifies if a scanline contains any valid segments.

 Bool XmuValidArea(XmuArea *area);

	Verifies if the area contains any valid scanlines.

 #define XmuSegmentEqu(s1, s2)	((s1)->x1 == (s2)->x1 && (s1)->x2 == (s2)->x2)

	Checks if segments s1 and s2 are equal.

 Bool XmuScanlineEqu(XmuScanline *s1, XmuScanline *s2);

	Checks if scanlines s1 and s2 are equal

 XmuSegment *XmuNewSegment(int x1, int x2);

	Creates a new segments with the coordinates x1 and x2

 #define XmuDestroySegment(s)	XtFree((char *)(s))

	Frees the segment.

 void XmuDestroySegmentList(XmuSegment *segment);

	Frees the memory used by the list headed by segment

 XmuScanline *XmuNewScanline(int y, int x1, int x2);

	Creates a new scanline.  If x1 < x2, sets the scanline to include
	the segment between those two points.

 #define XmuDestroyScanline(s)

	Frees a scanline and all of its segments.

 void XmuDestroyScanlineList(XmuScanline *scanline);

	Frees memory associated with a list of scanlines.

 XmuScanline *XmuScanlineCopy(XmuScanline *dst, XmuScanline *src);

	Makes dst contain the same data as src

 Bool XmuAppendSegment(XmuSegment *segment, XmuSegment *append);

	Adds a copy of the append list at the end of the segment list

 XmuScanline *XmuOptimizeScanline(XmuScanline *scanline);

	Some functions, when transforming Segments of Scanlines, left these
 	with unnecessary data (that may cause error in these same functions).
        This function corrects these incorrect segments.

 XmuScanline *XmuScanlineNot(XmuScanline *scanline, int minx, int maxx);

	Inverts the segments included in the scanline.

 XmuScanline *XmuScanlineOr(XmuScanline *dst, XmuScanline *src);

	Sets dst to include segments set in either dst or src.

 XmuScanline *XmuScanlineAnd(XmuScanline *dst, XmuScanline *src);

	Sets dst to include segments set in both dst and src.

 XmuScanline *XmuScanlineXor(XmuScanline *dst, XmuScanline *src);

	Sets dst to include segments set in dst or src, but not both.

 XmuArea *XmuOptimizeArea(XmuArea *area);

	Optimizes an area. This function is called when finishing a
	operation between areas, since they can end with redundant data,
	and the algorithms for area combination wants a area with
	correct data (but can leave unnecessary data in the area, to avoid
	too much paranoia tests).

6. Resources and Schedule
    6.4. Steering Committee requested information
   	6.4.1. Consolidation C-team Name:
		X
    6.5. ARC review type: FastTrack