.\"U7
.\"UT "Graphics Resource Functions" 5
.NH 1
Graphics Resource Functions
.LP
Once you have initialized the X system,
you can use the Xlib graphics resource functions to:
.IP \(bu 5
Manipulate the color map
.IP \(bu 5
Manipulate pixmaps
.IP \(bu 5
Manipulate graphics context/state
.IP \(bu 5
Set graphics context components
.LP
There are a number of resources used when performing graphics
operations in X.
Most information about performing graphics (for example, foreground
color, background color, line style, and so on) are stored in
resources called graphics contexts.
.IN "Definitions" "Graphics Context"
Most graphics operations (see chapter 6) take a graphics
context or "GC" as an argument.
While possible to share between applications, it
is expected that applications will use their own
GCs when performing operations, and such
use is discouraged, as the library may cache GC state.
.LP
Windows in X on a color display always have an associated colormap, which
provides a level of indirection between pixel values and color displayed
on the screen.
Much hardware built today have a single color map, so the primitives
are written to encourage sharing of color map entries between applications.
Since colormaps are associated with windows, X will support displays
with multiple colormaps, and indeed different types of colormaps.
If there is not sufficient colormap resources in the display,
then some windows may not be displayed in their true colors.
A window manager can set which window(s) are displayed
in their true colors if more than one colormap is required for
the color resources the applications are using.
.LP
Off screen memory, or pixmaps, are often used to define often
used images for later use in graphics operations.
Pixmaps are also used to define tiles, or
patterns, for use as window backgrounds, borders, or cursors.
A single bit plane pixmap is sometimes referred to as a bitmap.
There may not be an unlimited amount of off screen memory,
so it should be regarded as a "precious" resource.
Graphics operations can be performed to either windows or
pixmaps, also called "drawables" in the discussion below and
in the next chapter.
.NH 2
Manipulating the Color Map
.LP
Xlib provides functions with which you can manipulate a color map.
This section discusses how to:
.IP \(bu 5
Create, copy, and destroy the color map
.IP \(bu 5
Allocate and deallocate colors
.NH 3
Creating, Copying, and Destroying Color Maps
.LP
Xlib provides functions with which you can create, copy, free,
or set a color map.
.XS
Color Map Manipulation
.XE
.LP
The following functions manipulate the representation of color on the
screen.
For each possible value a pixel may take on a display
(for example, if a display is 4 bits deep, pixel values 0 through 15 are
defined), there is a color cell in the color map.
A color map is the collection of the color cells.
A color cell consists of a triple of red, green and blue.
As each pixel is read out of display memory, its value
is taken and looked up in the color map.
The values of the cell determine what color is displayed on the screen.
On a multiplane  display with a black and white monitor (grayscale, but
not color), these values may or may not be combined to determine the
brightness on the screen.
.LP
Screens always have a color map.
Programs will typically allocate cells out of a common map;
it is highly discouraged to write applications which monopolize 
color resources.
On a screen that either cannot load the color map or cannot have a fully
independent color map, 
only certain kinds of allocations may work.
One (or more on certain hardware) color maps may be resident at one time.
The
.PN XInstallColormap 
function (see Chapter 7) is used to install a color map.
The 
.PN DefaultVisual 
macro
returns the default visual type for the specified screen.
Color maps are local to a particular screen.
The 
.PN DefaultColormap 
macro
returns the type of color map.
.IN "Definitions" "Colormap"
.IN "Macros" "Colormap"
Possible types are represented by these constants: 
.PN StaticGray , 
.PN GrayScale , 
.PN StaticColor ,
.PN PseudoColor , 
.PN TrueColor , 
or 
.PN DirectColor .
.LP
These types are more fully discussed in the section on visual
types in Chapter 3.
.NT
The introduction of color changes the view a programmer should
take when dealing with a bitmap display.
For example, when printing text, you
write in a `color' (pixel value) rather than setting or clearing bits.
Hardware will impose limits (number of significant
bits, for example) on these values.
Typically, one allocates particular pixel values or sets of
values.
If read only, the pixel values may be shared among multiple applications.
If read/write, they are exclusively owned by the program,
and the color cell associated with the pixel value may be changed at will.
.NE
.LP
.\" *** JIM: WE MAY WANT A CHAPTER OR AN APPENDIX WHERE WE CAN
.\"          PLACE ALL OF THE STRUCTURES. ***
The functions in this section operate on a 
.PN XColor
structure:
.IN "Data Structures" "Color"
.DS 0
.\" Adjusted structure so that elements fit neatly on
.\" the 7 by 9 page.
.TA .5i 2.5i
.ta .5i 2.5i

typedef struct {
	unsigned long pixel;	/* pixel value */
	unsigned short red, green, blue;	/* rgb values */
	char flags;	/* do_red, do_green, do_blue */	
	char pad;
} XColor;
.DE
.IN "XColor"
.IN "Data Structures" "XColor"
.LP
The red, green and blue values are scaled between 0 and 65535. 
That is,
`on full' in a color is a value of 65535 independent of the number
of bit planes of the display.
.IN "Color"
Half brightness in a color would be a value of 32767, and off of 0.
This representation gives uniform results for color values across
displays with different number of bit planes.
.LP
.sp
To create a color map for the screen on which the window resides 
and to return the Colormap ID, use 
.PN XCreateColormap .
.IN "XCreateColormap"
.IN "Protocol request" "XCreateColormap"
The definition for this function is:
.IN "Definitions" "XCreateColormap"
.FD 0
.so ./Xsrc/XCreateCmap.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w.a
This is the window on whose screen you want to create a color map.
.\" *** JIM: SAME NAME USED FOR XWindow. HOWEVER DIFFERENT DESCRIPTIONS. CALL visual1.a FILE FOR NOW. ***
.so ./Xsrc/visual1.a
.so ./Xsrc/alloc.a
.LP
If you pass the constant
.PN AllocNone 
to the alloc argument, 
the color map has no allocated entries.
This allows your client programs to allocate the entries in 
the color map.
If you pass the constant
.PN AllocAll , 
the entire color map is allocated
writable.
However, you cannot free these entries with
.PN XFreeColors ,
and no relationships between the
entries is defined. 
.LP
With
.PN XCreateColormap ,
it is legal to specify a visual with a class represented by the constants
.PN StaticGray 
or 
.PN TrueColor .
The entries then have defined but unspecified (by the protocol) values.
For a visual of class represented by the constants
.PN StaticGray 
or 
.PN TrueColor ,
alloc must be specified as 
.PN AllocNone 
(else a 
.PN BadMatch 
error).
.LP
The client must understand whether the colormap is 
.PN StaticGray , 
.PN GrayScale , 
.PN StaticColor , 
.PN PseudoColor , 
.PN TrueColor , 
or 
.PN DirectColor 
to know how to store into
entries.
.LP
.sp
To copy a color map to the same screen specified by cmap and to 
return a new Colormap ID, use 
.PN XCopyColormapAndFree .
.IN "XCopyColormapAndFree"
.PN XCopyColormapAndFree
is used to obtain a new color map when allocating out of a previous
colormap has failed due to resource exhaustion (that is, too many cells
or planes were in use in the original color map).
.IN "Protocol request" "XCopyColormapAndFree"
The definition for this function is:
.IN "Definitions" "XCopyColormapAndFree"
.FD 0
.so ./Xsrc/XCopyCmapFr.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.LP
.PN XCopyColormapAndFree
moves all of the client's existing allocations
from the specified color map to the new colormap
and frees those entries in cmap.
Values in other entries in the new color map are undefined.
.LP
.sp
To delete the association between the resource ID and the color map, 
use 
.PN XFreeColormap .
.IN "XFreeColormap"
.IN "Protocol request" "XFreeColormap"
The definition for this function is:
.IN "Definitions" "XFreeColormap"
.FD 0
.so ./Xsrc/XFreeCmap.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
This is the color map associated with the resource ID you want to delete.
.LP
The
.PN XFreeColormap
function deletes the association between the window resource ID and the color map.
However, this function has no effect on a default color map for a screen.
Specifically,
.PN XFreeColormap
performs the following processing:
.IP \(bu 5
If cmap is an installed map for a screen
.IP
Uninstalls the color map and installs another color map in its place.
See
.PN XUninstallColormap .
.IP \(bu 5
If cmap is defined as the color map for a window (by
.PN XCreateWindow
or
.PN XChangeWindowAttributes)
.IP
Changes the color map associated with the window to the constant
.PN None ,
generates a
.PN ColormapNotify
event,
and frees the color map. 
.IP \(bu 5
If the screen's default colormap is not installed 
.IP
Uses the default colormap.
.LP
.sp
To set the color map for a specified window, use
.PN XSetWindowColormap .
.IN "XSetWindowColormap"
.IN "Protocol request" "XSetWindowColormap"
The definition for this function is:
.IN "Definitions" "XSetWindowColormap"
.FD 0
.so ./Xsrc/XChCmap.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/w.a
This is the window to which you want to set the color map.
.so ./Xsrc/cmap.a
.NH 3
Obtain Hardware Colors
.LP
Xlib provides functions with which you can allocate or deallocate colors.
There are two ways of allocating color cells: explicitly as read only
entries by pixel value 
.PN (XAllocColor) 
or read/write,
where you can allocate N colors and planes simultaneously.
.IN "XAllocColor"
.IN "Read/Write Colormap Cells"
The read write cells you allocate do not have defined colors until
set with 
.PN XStoreColors .
.IN "XStoreColors"
.LP
.sp
To obtain the closest color provided by the hardware, use 
.PN XAllocColor .
.IN "XAllocColor"
.IN "Color Allocation"
.IN "Protocol request" "XAllocColor"
The definition for this function is:
.IN "Definitions" "XAllocColor"
.FD 0
.so ./Xsrc/XGetHardClr.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/def.a
.LP
.PN XAllocColor
returns the pixel value indicating the closest color supported by the hardware.
The corresponding color map cell is read-only.
It also returns the red, green, and blue values actually used.
.LP
.PN XAllocColor
allocates a read-only color map entry corresponding to the closest
red, green, and blue values supported by the hardware.
The corresponding color map cell is read-only.
In addition,
.PN XAllocColor
returns 0 if there were some problem (typically lack of resources),
or non-zero if it succeeded.
.IN "Colormap"
.IN "Color Allocation"
.IN "Allocation" "Color Map"
.IN "Read-only Colormap Cells"
Read-only color map cells are shared among clients.
When the last client deallocates a shared cell, it is deallocated.
.\" *** JIM: WHAT IS THE FOLLOWING FOR?
.EQ
delim %%
.EN
.LP
.sp
To obtain the color definition structure for a specified color and the closest 
color supported by the hardware, use 
.PN XAllocNamedColor .
.IN "XAllocNamedColor"
.IN "Color" "Naming"
.PN XAllocNamedColor
determines the correct color (shade) for the given display.
.IN "Protocol request" "XAllocNamedColor"
The definition for this function is:
.IN "Definitions" "XAllocNamedColor"
.FD 0
.so ./Xsrc/XGetColor.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/colorname.a
.so ./Xsrc/hard_def.a
.so ./Xsrc/exact_def.a
.LP 
.PN XAllocNamedColor
returns 0 when it encounters an error or a non-zero when it succeeds.
Both the `exact' data base definition, and 
the `closest' color supported by the hardware are returned.
.LP
.sp
To look up the name of a color,
use
.PN XLookupColor .
.IN "XLookupColor"
.IN "Protocol request" "XLookupColor"
The definition of this function is:
.IN "Definitions" "XLookupColor"
.FD 0
.so ./Xsrc/XLkUpColor.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/spec.a
.so ./Xsrc/def.a
.so ./Xsrc/exact_def.a
.LP
.PN XLookupColor
looks up the string name of a color with respect to the screen
associated with the specified cmap and
returns both the exact the color values and
the closest values provided by the hardware.
The name should use the ASCII encoding, and upper/lower case does not matter.
In addition,
.PN XLookupColor
returns nonzero if the spec existed in the RGB data base
or 0 if it did not exist.
.LP
To determine the color,
.PN XLookupColor
uses a data base on the X server.
.IN "Color" "Data Base"
On UNIX, this data base is
.PN /usr/lib/rgb .
To read the colors provided by the data base on a UNIX-based system,
see 
.PN /usr/lib/rgb.txt .
.IN "File" "/usr/lib/rgb.txt"
The name and contents of this file are operating system specific.
.LP
.sp
To set the colors of the specified pixel values to the closest available hardware colors,
use
.PN XStoreColors .
.IN "XStoreColors"
.IN "Color" "Setting Cells"
.IN "Protocol request" "XStoreColors"
The definition for this function is:
.IN "Definitions" "XStoreColors"
.FD 0
.so ./Xsrc/XStoreColors.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/defs.a
.so ./Xsrc/ncolors.a
.LP
.PN XStoreColors
performs the following processing:
.IP \(bu 5
Changes the color map entries of the pixel values.
.IP
You specified these values in the
pixel members of the
.PN XColor
structures.
These pixel values must be read/write cells and valid indexes into cmap.
.IP \(bu 5
Changes the red, green, and/or blue color components.
.IP
You specify which color components to be changed by passing the constants
.PN DoRed ,
.PN DoGreen ,
and/or
.PN DoBlue
to the flags members of the
.PN XColor
structures.
If the color map is an installed map for its screen, the changes are visible immediately.
.IP \(bu 5
Changes the specified pixels if they are allocated writeable in cmap by any client,
even if the pixel generates an error.
.LP
.sp
To set the color of the specified pixel value to the closest
available hardware color, use 
.PN XStoreColor .
.IN "XStoreColor"
.IN "Protocol request" "XStoreColor"
The definition for this function is:
.IN "Definitions" "XStoreColor"
.FD 0
.so ./Xsrc/XStoreColor.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/def.a
.LP
.PN XStoreColor
performs the following processing:
.IP \(bu 5
Changes the color map entry of the pixel value. 
.IP
You specified this value in the
pixel member of the
.PN XColor
structure.
This pixel value must be a read/write cell and a valid index into cmap.
.IP \(bu 5
Changes the red, green, and/or blue color components.
.IP
You specify which color components to be changed by passing the constants
.PN DoRed ,
.PN DoGreen ,
and/or
.PN DoBlue
to the flags member of the
.PN XColor
structure.
If the color map is an installed map for its screen, the changes are visible immediately.
.IP \(bu 5
Changes the specified pixel if it is allocated writeable in cmap by any client,
even if the pixel generates an error.
.LP
.sp
To allocate color cells, use 
.PN XAllocColorCells .
.IN "XAllocColorCells"
.IN "Color Allocation"
.IN "Protocol request" "XAllocColorCells"
The definition for this function is:
.IN "Definitions" "XAllocColorCells"
.FD 0
.so ./Xsrc/XAllocCells.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/contig.a
.so ./Xsrc/plane_masks.a
.so ./Xsrc/nplanes.a
.so ./Xsrc/pixels.a
.so ./Xsrc/ncolors1.a
.LP
The number of colors must be positive, the number of planes
non-negative.  If ncolors and nplanes are requested, 
then ncolors pixels
and nplane plane masks are returned.
No mask will have any bits in common with
any other mask, or with any of the pixels.
By ORing together masks and
pixels, ncolors* %2 sup nplanes% distinct pixels can be produced;
all of these are
allocated writable by the request.
For 
.PN GrayScale 
or 
.PN PseudoColor , 
each
mask will have exactly one bit, and for 
.PN DirectColor 
each will have
exactly three bits.
If contiguous is 
.PN True , 
then if all masks are ORed
together, a single contiguous set of bits will be formed for 
.PN GrayScale
or 
.PN PseudoColor , 
and three contiguous sets of bits (one within each
pixel subfield) for 
.PN DirectColor .
The RGB values of the allocated
entries are undefined.
.LP
.sp
To allocate color planes, use 
.PN XAllocColorPlanes .
.IN "XAllocColorPlanes" 
.IN "Color Allocation"
.IN "Protocol request" "XAllocColorPlanes"
The definition for this function is:
.IN "Definitions" "XAllocColorPlanes"
.FD 0
.so ./Xsrc/XAllocPlanes.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/contig.a
.so ./Xsrc/pixels.a
.PN XAllocColorPlanes
returns the pixel values in this array.
.so ./Xsrc/ncolors1.a
.so ./Xsrc/nredgrbl.a
.so ./Xsrc/rgbmask.a
.LP
Ncolors must be positive, nreds, ngreens, and nblues
non-negative.  
If C colors, R reds, G greens, and B blues are
requested, then C pixels are returned, and the masks have R, G, and B
bits set respectively.
If contiguous is 
.PN True , 
then each mask will have
a contiguous set of bits.
No mask will have any bits in common with
any other mask, or with any of the pixels.
For 
.PN DirectColor , 
each mask
will lie within the corresponding pixel subfield.
By ORing together
subsets of masks with pixels, C*(2^(R+G+B)) distinct pixels can be
produced. 
All of these are allocated by the request.
However, in the
colormap there are only C*(2^R) independent red entries, C*(2^G)
independent green entries, and C*(2^B) independent blue entries.  
This is true even for 
.PN PseudoColor .
When the colormap entry for a pixel
value is changed using 
.PN XStoreColors 
or 
.PN XStoreNamedColor ,
the pixel is decomposed according to the masks and the corresponding independent
entries are updated.
.LP
.sp
To allocate a color cell by name, use
.PN XStoreNamedColor.
.IN "XStoreNamedColor"
.IN "Protocol request" "XStoreNamedColor"
The definition for this function is:
.IN "Definitions" "XStoreNamedColor"
.FD 0
.so ./Xsrc/XStoreNColor.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/color.a
.so ./Xsrc/pixel.a
.so ./Xsrc/flags.a
.LP 
.PN XStoreNamedColor
looks up the named color with respect to the screen associated with
cmap, then stores the result in cmap.
Upper/lower case in name does not matter.
Pixel determines the entry in the color map.
Which of the red, green and blue indicies are set is determined by
the flags argument, by a bitwise OR of the bits from the constant set
.PN DoRed , 
.PN DoGreen , 
and 
.PN DoBlue .
.LP
.sp
To free color map cells, use 
.PN XFreeColors .
.IN "XFreeColors"
.IN "Protocol request" "XFreeColors"
The definition for this function is:
.IN "Definitions" "XFreeColors"
.FD 0
.so ./Xsrc/XFreeColors.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/pixels.a
These pixel values map to the cells in the specified color map.
.so ./Xsrc/npixels.a
.so ./Xsrc/planes.a
.LP
.PN XFreeColors
frees the cells represented by pixels whose values are in the array.
If any planes are specified, they also are freed.
.LP
.sp
To obtain the color values for the specified pixel value, 
use 
.PN XQueryColor .
.IN "XQueryColor"
.IN "Protocol request" "XQueryColor"
The definition for this function is:
.IN "Definitions" "XQueryColor"
.FD 0
.so ./Xsrc/XQueryColor.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.IP \fIdef\fP 1i
Specifies a pointer to the color definition structure.
.LP
.PN XQueryColor
performs the following processing:
.IP \(bu 5
Returns the red, green, and blue color values stored in cmap for
the pixel value you passed to the pixel member of the
.PN XColor
structure.
.IP \(bu 5
Sets the flags member in the 
.PN XColor
structure to all three colors.
.IP \(bu 5
Returns zero if it encountered some problem, or non-zero if
it succeeded.
.LP
.sp
To obtain color values for each specified pixel value, 
use 
.PN XQueryColors .
.IN "XQueryColors"
.IN "Color" "Getting Values"
.IN "Protocol request" "XQueryColors"
The definition for this function is:
.IN "Definitions" "XQueryColors"
.FD 0
.so ./Xsrc/XQueryColors.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/cmap.a
.so ./Xsrc/defs.a
.so ./Xsrc/ncolors.a
.LP
.PN XQueryColors
performs the following processing:
.IP \(bu 5
Returns the red, green, and blue color values stored in cmap for
the pixel value(s) you passed to the pixel member(s) of the
.PN XColor
structure(s).
.IP \(bu 5
Sets the flags member(s) in the 
.PN XColor
structure(s) to all three colors.
.IP \(bu 5
Returns zero if it encountered some problem, or non-zero if
it succeeded.
.NH 2
Manipulating Pixmaps
.LP
Xlib provides functions with which you can create or free a pixmap.
A few  programs may want to manipulate pixels that they later display on
the screen.
This section describes calls which will move pixels from the program to
the window system, or from the window system to the program.
Care must be taken to adhere to the data representation described at the
beginning of this document to keep programs portable between machine
architectures.
.LP
.sp
To create a pixmap of a specified size, use 
.PN XCreatePixmap .
.IN "XCreatePixmap"
.IN "Protocol request" "XCreatePixmap"
The definition for this function is:
.IN "Definitions" "XCreatePixmap"
.FD 0
.so ./Xsrc/XCrePmap.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
.so ./Xsrc/widtheight.a
These dimensions define the width and height of the pixmap.
The values you pass must be non-zero.
.so ./Xsrc/depth1.a
.LP 
Width and height must be non-zero.
Depth must be one of the depths supported by the root of the
specified drawable.
The initial contents of the pixmap are undefined.
.LP
Pixmaps are off screen resources which are used for a number of
operations.
A bitmap is a single bit Pixmap.
These include defining cursors,
temporarily saving some part of the screen for later,
as tiling patterns, and as the source for certain raster operations.
.LP
If this routine returns 0,
there was insufficient space for the pixmap.
.LP
.sp
To free all storage associated with a specified pixmap, 
use 
.PN XFreePixmap .
.IN "XFreePixmap"
.IN "Protocol request" "XFreePixmap"
The definition for this function is:
.IN "Definitions" "XFreePixmap"
.FD 0
.so ./Xsrc/XFreePixmap.f
.FN	
.so ./Xsrc/display.a
.so ./Xsrc/pixmap.a
.LP 
The Pixmap should never be referenced again.
.NH 2
Manipulating Graphics Context/State
.LP
Xlib implements a write-back cache for all elements of a GC that are not
resource IDs to allow it to implement the transparent coalescing changes to
GCs.
GCs are neither expected nor encouraged to be shared between client 
applications, so this write-back caching should present no problems.
Applications cannot share GCs without external synchronization.
Therefore,
sharing GCs between applications is highly discouraged. 
.LP
Xlib provides functions with which you can create, copy, change, or free
the graphics context.
.XS
Graphic Operations
.XE
.LP
.IN "Definitions" "Display Functions"
.IN "Definitions" "Source"
.IN "Definitions" "Destination"
You use display functions when you update  a section of the screen (the
`destination') with bits from somewhere else (the
`source').  
Many procedures below take one of these display functions as an argument.
The function defines how the new destination bits are to be
computed from the source bits and the old destination bits.
.PN GXcopy
is typically the most useful as it will work on a color display,
but special applications may use other functions,
particularly in concert with particular planes of a color display.
.IN "File" "<X11/X.h>
The 16 such functions, defined in 
.PN <X11/X.h> ,
are:
.\"Table 5-1 lists these 16 functions along with the associated hexadecimald code
.\" and operation.
.\".CP T 1
.\"Display Functions
.TS H
tab(@);
l c c
l c l.
_
.sp 6p
.TB
Function Name@Hex Code@Operation
.sp 6p
_
.sp 6p
.TH
.R
GXclear@0x0@0
GXand@0x1@src AND dst
GXandReverse@0x2@src AND NOT dst
GXcopy@0x3@src
GXandInverted@0x4@(NOT src) AND dst
GXnoop@0x5@dst
GXxor@0x6@src XOR dst
GXor@0x7@src OR dst
GXnor@0x8@(NOT src) AND NOT dst
GXequiv@0x9@(NOT src) XOR dst
GXinvert@0xa@NOT dst
GXorReverse@0xb@src OR NOT dst
GXcopyInverted@0xc@NOT src
GXorInverted@0xd@(NOT src) OR dst
GXnand@0xe@(NOT src) OR NOT dst
GXset@0xf@1
.sp 6p
_
.TE
.LP
Many of the color functions below take either pixel values or
planes as an argument.
.IN "Pixel Values"
The planes is of type long which specifies which planes of the
display are to be modified, one bit per plane.
.IN "Definitions" "Plane Masks"
A monochrome display has only one plane and
will be the least significant bit of the word.
As planes are added to the display hardware, they will occupy more
significant bits in the plane mask.
.LP
.IN "Macro" "AllPlanes"
A macro constant 
.PN AllPlanes 
can be used to refer to all planes of a display simultaneously (``~0'').
.LP
.IN "Definitions" "Graphics Context"
.IN "Graphics Context"
Most operations use an object called a "GC", which is short for
"Graphics Context".  
The contents of the GC object are private to the library.
.LP
Several procedures take structures of type "GCValues". The following lists
each entry by its defined value, not by its position in the XGCValue 
structure:
.DS 0
.TA .5i 3i
.ta .5i 3i

/* GC components: masks used in CreateGC, CopyGC, ChangeGC */

#define GCFunction	(1L<<0)
#define GCPlaneMask	(1L<<1)
#define GCForeground	(1L<<2)
#define GCBackground	(1L<<3)
#define GCLineWidth	(1L<<4)
#define GCLineStyle	(1L<<5)
#define GCCapStyle	(1L<<6)
#define GCJoinStyle	(1L<<7)
#define GCFillStyle	(1L<<8)
#define GCFillRule	(1L<<9)
#define GCTile	(1L<<10)
#define GCStipple	(1L<<11)
#define GCTileStipXOrigin	(1L<<12)
#define GCTileStipYOrigin	(1L<<13)
#define GCFont	(1L<<14)
#define GCSubwindowMode	(1L<<15)
#define GCGraphicsExposures	(1L<<16)
#define GCClipXOrigin	(1L<<17)
#define GCClipYOrigin	(1L<<18)
#define GCClipMask	(1L<<19)
#define GCDashOffset	(1L<<20)
#define GCDashList	(1L<<21)
#define GCArcMode	(1L<<22)

.DE
.DS 0
.\" Adjusted structure so that elements fit neatly on
.\" the 7 by 9 page.
.TA .5i 3i
.ta .5i 3i
/*
 * Data structure for setting graphics context.
 */

typedef struct {
	int function;	/* logical operation */
	unsigned long plane_mask;	/* plane mask */
	unsigned long foreground;	/* foreground pixel */
	unsigned long background;	/* background pixel */
	int line_width;	/* line width */
	int line_style;	/* LineSolid, LineOnOffDash, LineDoubleDash */
	int cap_style;	/* CapNotLast, CapButt, CapRound, CapProjecting */
	int join_style;	/* JoinMiter, JoinRound, JoinBevel */
	int fill_style;	/* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
	int fill_rule;	/* EvenOddRule, WindingRule */
	int arc_mode;	/* ArcChord, ArcPieSlice */
	Pixmap tile;	/* tile pixmap for tiling operations */
	Pixmap stipple;	/* stipple 1 plane pixmap for stippling */
	int ts_x_origin;	/* offset for tile or stipple operations */
	int ts_y_origin;
	Font font;	/* default text font for text operations */
	int subwindow_mode;	/* ClipByChildren, IncludeInferiors */
	Bool graphics_exposures;	/* boolean, should exposures be generated */
	int clip_x_origin;	/* origin for clipping */
	int clip_y_origin;
	Pixmap clip_mask;	/* bitmap clipping; other calls for rects */
	int dash_offset;	/* patterned/dashed line information */
	char dashes;
} XGCValues;
.DE
.IN "XGCValues"
.IN "Data Structures" "XGCValues"
.LP
.sp
To create a new graphics context for the specified drawable, use 
.PN XCreateGC .
.IN "XCreateGC"
.IN "Initializing Graphics Contexts"
.IN "Protocol request" "XCreateGC".
The definition for this function is:
.IN "Definitions" "XCreateGC".
.FD 0
.so ./Xsrc/XCreateGC.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
.so ./Xsrc/valuemask1.a
This argument indicates which values are to be set using information in the values
structure.
.so ./Xsrc/values1.a
.LP 
The specified components of the new graphics context in valuemask
are set to the values passed in the components argument.
.\" *** JIM: WHERE IS THE COMPONENTS ARGUMENT? ***
The other values default to the following values:
.br
.\"Table 5-2 lists the default component values.
.\".CP T 2
.\"Default Component Values
.TS H
tab(@);
c l
l l.
_
.sp 6p
.TB
Component@Value
.sp 6p
_
.sp 6p
.TH
.R
function:@GXcopy
plane_mask:@all ones
foreground:@0
background:@1
line_width:@0
line_style:@LineSolid
cap_style:@CapButt
join_style:@JoinMiter
fill_style:@FillSolid
fill_rule:@EvenOddRule
arc_mode:@ArcPieSlice
tile:@pixmap of unspecified size filled with foreground pixel
stipple:@pixmap of unspecified size filled with ones
ts_x_origin:@0
ts_y_origin:@0
font:@<implementation dependent>
subwindow_mode:@ClipByChildren
graphics_exposures:@True
clip_x_origin:@0
clip_y_origin:@0
clip_mask:@None
dash_offset:@0
dash_list:@4 (i.e., the list [4, 4])
.sp 6p
_
.TE
.LP
In graphics operations, given a source and destination pixel, the
result is computed bitwise on corresponding bits of the pixels.  That
is, a boolean operation is performed in each bit plane.  
The plane_mask
restricts the operation to a subset of planes.  That is, the result is
computed by the following:
.LP
.DS 
.R
((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
.DE
Range checking is not performed on the values for foreground,
background, or plane_mask;
they are simply truncated to the appropriate
number of bits.
.LP
The line_width is measured in pixels and either can be greater than or equal to
one (``wide'' line) or can be the special value zero (``thin'' line).
.LP
Wide lines are drawn centered on the path described by the graphics request.
Unless otherwise specified by the join or cap style,
the bounding box of a wide line with endpoints [x1, y1], [x2, y2], and
width w is a rectangle with vertices at the following real coordinates:
.LP
.DS
.TA .5i 2.5i
.ta .5i 2.5i
[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
.DE
The sn argument is the sine of the angle of the line and cs is the cosine of
the angle of the line.
A pixel is part of the line and, hence, is drawn,
if the center of the pixel is fully inside the bounding box
(which is viewed as having infinitely thin edges).
If the center of the pixel is exactly on the bounding box,
it is part of the line if and only if the interior is immediately to its right
(x increasing direction).
Pixels with centers on a horizontal edge are a special case and are part of
the line if and only if the interior is immediately below 
(y increasing direction).
.NT
This description is a mathematical model that describes the pixels 
that are drawn for a wide line and, as such, does not imply that trigonometry
is required to implement such a model.
For lines greater than one pixel in width,
real or fixed point arithmetic is recommended for computing the corners 
of the line endpoints.
.NE
.LP
Thin lines (zero line_width) are ``one pixel wide'' lines drawn using an
unspecified, device dependent algorithm.
There are only two constraints on this algorithm. 
.IP 1. 5
If a line is drawn unclipped from [x1,y1] to [x2,y2] and
if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
then a point [x,y] is touched by drawing the first line 
if and only if the point [x+dx,y+dy] is touched by drawing the second line.
.IP 2. 5
The effective set of points comprising a line cannot be affected by clipping.
That is, a point is touched in a clipped line if and only if the point 
lies inside the clipping region and the point would be touched
by the line when drawn unclipped.
.LP
A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels 
as a wide line drawn from [x2,y2] to [x1,y1], not counting cap and join styles.
Implementors are encouraged to make this property true for thin lines, but it
is not required.
A line_width of zero differs from a line_width of one in which pixels are
drawn.
.LP
In general, drawing a thin line will be faster than drawing a
wide line of width one.
However, because of their different drawing algorithms,
thin lines may not mix well, aesthetically speaking, with wide lines.
If it is desirable to obtain precise and uniform results across all displays,
a client should always use a line_width of one,
rather than a line_width of zero.
.LP
The line-style defines which sections of a line are drawn:
.IP LineSolid: 1.5i
The full path of the line is drawn.
.IP LineDoubleDash: 1.5i
The full path of the line is drawn, 
but the even dashes are filled differently 
than the odd dashes (see fill-style), with
.PN CapButt
style used where even and odd dashes meet.
.IP  LineOnOffDash: 1.5i
Only the even dashes are drawn,
and cap-style applies to 
each individual segment (except
.PN CapNotLast 
is treated as 
.PN CapButt 
for internal caps).
.LP
The cap_style defines how the endpoints of a path are drawn:
.IP CapNotLast: 1.5i
Equivalent to 
.PN CapButt , 
except that for a line-width
of zero or one the final endpoint is not drawn.
.IP CapButt: 1.5i
Square at the endpoint with no projection beyond.
.IP CapRound: 1.5i
A circular arc with the diameter equal to the line_width,
centered on the endpoint (equivalent to 
.PN CapButt 
for line-width zero or one).
.IP CapProjecting: 1.5i
Square at the end, but the path continues beyond the endpoint 
for a distance equal to half the line_width 
(equivalent to 
.PN CapButt 
for line-width zero or one).
.LP
The join_style defines how corners are drawn for wide lines:
.IP JoinMiter: 1.5i
The outer edges of the two lines extend to meet at an angle.
.IP JoinRound: 1.5i
A circular arc with diameter equal to the line_width, centered on the joinpoint.
.IP JoinBevel: 1.5i
.PN CapButt 
endpoint styles, and then the triangular "notch" filled.
.LP
The tile/stipple and clip origins are interpreted relative to the
origin of whatever destination drawable is specified in a graphics
request.
.LP
The tile pixmap must have the same root and depth as the graphics context
(else a 
.PN BadMatch 
error).
The stipple pixmap must have depth one and must have the same root as the
graphics context (else a 
.PN BadMatch 
error).  
For stipple operations, the stipple pattern is tiled in a
single plane and acts as an additional clip mask to be ANDed with the
clip_mask.  
Any size pixmap can be used for tiling or stippling,
although some sizes may be faster to use than others.
.LP
The fill_style defines the contents of the source for line, text, and
fill requests.  
For all text and fill requests (for example,
.PN XDrawText , 
.PN XDrawText16 ,
.PN XFillRectangle , 
.PN XFillPolygon , 
and
.PN XFillArc )
for line requests (for example,
.PN XLine ,
.PN XSegments , 
.PN XRectangle,  
.PN XArc )
with line_style 
.PN LineSolid , 
and for the
even dashes for line requests with line_style 
.PN LineOnOffDash 
or 
.PN LineDoubleDash:
.IP FillSolid: 1.5i
Foreground.
.IP FillTiled: 1.5i
Tile.
.IP FillOpaqueStippled: 1.5i
A tile with the same width and height as stipple,
but with background everywhere stipple has a zero
and with foreground everywhere stipple has a one.
.IP FillStippled: 1.5i
Foreground masked by stipple.
.LP
For the odd dashes for line requests with line_style 
.PN DoubleDash:
.IP FillSolid: 1.5i
Background.
.IP FillTiled: 1.5i
Tile.
.IP FillOpaqueStippled: 1.5i
Same as for even dashes.
.IP FillStippled: 1.5i
Background masked by stipple.
.LP
If the pixmap is used simultaneously in a graphics request both as
a destination and as a tile or stipple,
the results are not defined.
.LP
The dash_list value allowed here is actually a simplified form of the
more general patterns that can be set with 
.PN XSetDashes .  
Specifying a
value of N here is equivalent to specifying the two element list [N, N] in 
.PN XSetDashes . 
The value must be non-zero.  
The meaning of dash_offset
and dashlist are explained for the 
.PN XSetDashes 
function.
.LP
The clip_mask restricts writes to the destination drawable.  
Only pixels where the clip-mask has a one bit are drawn.  
It affects all graphics requests.
The clip_mask does not clip sources.  The
clip_mask origin is interpreted relative to the origin of whatever
destination drawable is specified in a graphics request.
If a pixmap is specified as the clip_mask,
it must have depth one and have the same root as the graphics context
(else a 
.PN BadMatch 
error).
The clip_mask can also be set with the
.PN XSetClipRectangles 
request.
.LP
For 
.PN ClipByChildren , 
both source and destination windows are
additionally clipped by all viewable children.  
For 
.PN IncludeInferiors ,
neither source nor destination window is clipped by inferiors. 
This will result in drawing through subwindow boundaries.
The use of 
.PN IncludeInferiors 
on a window of one depth with mapped
inferiors of differing depth is not illegal, but the semantics is
undefined by the core protocol.
.LP
The fill_rule defines what pixels are inside (that is, are drawn) for
paths given in 
.PN XFillPolygon 
requests.  
.PN EvenOddRule 
means a point is inside if
an infinite ray with the point as origin crosses the path an odd number
of times.  
For 
.PN WindingRule , 
a point is inside if an infinite ray with the
point as origin crosses an unequal number of clockwise and
counterclockwise directed path segments.
For both rules, a "point" is infinitely small, 
and the path is an infinitely thin line.  
A pixel is inside if the center point of the pixel is inside,
and the center point is not on the boundary.  
If the center point is on the boundary,
the pixel is inside if and only if the polygon interior is immediately to
its right (x increasing direction).  
Pixels with centers along a horizontal edge are a special case 
and are inside if and only if the polygon interior is immediately below 
(y increasing direction).
.LP
The arc_mode controls filling in the 
.PN XFillArcs
function and can be pieslice or chord.
The graphics_exposure flag controls 
.PN GraphicsExpose 
event generation
for 
.PN XCopyArea 
and 
.PN XCopyPlane
requests (and any similar requests defined by extensions).
.LP
.sp
To copy components from a source graphics context to a destination
graphics context, use 
.PN XCopyGC .
.IN "XCopyGC"
.IN "Protocol request" "XCopyGC"
The definition for this function is:
.IN "Definitions" "XCopyGC"
.FD 0
.so ./Xsrc/XCopyGC.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/src.a
.so ./Xsrc/valuemask1.a
This argument identifies which source graphics context to copy.
.so ./Xsrc/dest.a
.LP 
The valuemask specifies which component to copy, as for
.PN XCreateGC .
.LP
.sp
To change the components in the specified graphics context, use 
.PN XChangeGC .
.IN "XChangeGC"
.IN "Protocol request" "XChangeGC"
The definition for this function is:
.IN "Definitions" "XChangeGC"
.FD 0
.so ./Xsrc/XChGC.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/valuemask1.a
These are the components you want to change.
.so ./Xsrc/values1.a
.LP
The valuemask specifies which components
are to be changed. 
The values contain the values to be set.
The values and restrictions are the same as for 
.PN XCreateGC .
Changing the clip_mask also overrides any previous 
.PN XSetClipRectangles
request on the context. 
Changing the dash_offset or dash_list
overrides any previous 
.PN XSetDashes
request on the context.
.LP
.sp
To free the specified graphics context, use 
.PN XFreeGC .
.IN "XFreeGC"
.IN "Protocol request" "XFreeGC"
The definition for this function is:
.IN "Definitions" "XFreeGC"
.FD 0
.so ./Xsrc/XFreeGC.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.NH 2
Using GC Convenience Routines
.LP
Xlib provides functions with which you can set a graphics context component.
This section discusses how to set the:
.IP \(bu 5
Foreground, background, plane mask, or function components
.IP \(bu 5
Line attributes and dashes components
.IP \(bu 5
Fill style and fill rule components
.IP \(bu 5
Fill tile and stipple components
.IP \(bu 5
Font component
.IP \(bu 5
Clip region component
.IP \(bu 5
Arc mode, subwindow mode, and graphics exposure components
.LE
.NH 3
Setting Foreground, Background, Plane Mask, or Function
.LP
To set the foreground, background, plane mask, and function components
for the specified graphics context, use 
.PN XSetState .
.IN "XSetState"
.IN "Protocol request" "XSetState"
The definition for this function is:
.IN "Definitions" "XSetState"
.FD 0
.so ./Xsrc/XSetState.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/foreground.a
.so ./Xsrc/background.a
.so ./Xsrc/function.a
.so ./Xsrc/plane_mask.a
.LP
.sp
To set a specified value in the specified graphics context, 
use 
.PN XSetFunction .
.IN "XSetFunction"
.IN "Protocol request" "XSetFunction"
The definition for this function is:
.IN "Definitions" "XSetFunction"
.FD 0
.so ./Xsrc/XSetFunc.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/function.a
.LP
.sp
To set the plane mask in the specified graphics context, 
use 
.PN XSetPlaneMask .
.IN "XSetPlaneMask"
.IN "Protocol request" "XSetPlaneMask"
The definition for this function is:
.IN "Definitions" "XSetPlaneMask"
.FD 0
.so ./Xsrc/XSetPlnMsk.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/plane_mask.a
.LP
.sp
To set the foreground in the specified graphics context, 
use 
.PN XSetForeground .
.IN "XSetForeground"
.IN "Protocol request" "XSetForeground"
The definition for this function is:
.IN "Definitions" "XSetForeground"
.FD 0
.so ./Xsrc/XSetFgrnd.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/foreground.a
.LP
.sp
To set the background in the specified graphics context, 
use 
.PN XSetBackground .
.IN "XSetBackground"
.IN "Protocol request" "XSetBackground"
The definition for this function is:
.IN "Definitions" "XSetBackground"
.FD 0
.so ./Xsrc/XSetBckgrnd.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/background.a
.NH 3
Setting Line Attributes and Dashes
.LP
To set the line drawing components in the specified graphics context, 
use 
.PN XSetLineAttributes .
.IN "XSetLineAttributes"
.IN "Protocol request" "XSetLineAttributes"
The definition for this function is:
.IN "Definitions" "XSetLineAttributes"
.FD 0
.so ./Xsrc/XSetLnStle.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/line_width.a
.so ./Xsrc/line_style.a
.so ./Xsrc/cap_style.a
.so ./Xsrc/join_style.a
.LP
.sp
To set the dash_offset and dash_list for dashed line styles
in the specified graphics context, use 
.PN XSetDashes .
.IN "XSetDashes"
.IN "Protocol request" "XSetDashes"
The definition for this function is:
.IN "Definitions" "XSetDashes"
.FD 0
.so ./Xsrc/XSetDashes.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/dashoff.a
.so ./Xsrc/dashlist.a
.so ./Xsrc/n3.a
.LP 
.PN XSetDashes 
sets the dash_offset and dash_list in gc for dashed line
styles.
The initial and alternating elements of the dash_list are the
"even" dashes, the others are the "odd" dashes.
All of the elements must be non-zero.
The dash_offset defines the phase of the pattern,
specifying how many pixels into the dash_list the pattern
should actually being in any single graphics request.
N specifies the length of the dash_list.
.NH 3
Setting the Fill Style and File Rule Components
.LP
To set the fill style in the specified graphics context, 
use 
.PN XSetFillStyle .
.IN "XSetFillStyle"
.IN "Protocol request" "XSetFillStyle"
The definition for this function is:
.IN "Definitions" "XSetFillStyle"
.FD 0
.so ./Xsrc/XSetFStyle.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/fill_style.a
.LP
.sp
To set the fill rule in the specified graphics context, 
use 
.PN XSetFillRule .
.IN "XSetFillRule"
.IN "Protocol request" "XSetFillRule"
The definition for this function is:
.IN "Definitions" "XSetFillRule"
.FD 0
.so ./Xsrc/XSetFRule.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/fill_rule.a
.NH 3
Setting the Fill Tile and Stipple Components
.LP
Some hardware can support differing size patterns for tiling or
stippling in hardware that runs much faster than arbitrary sizes.
Xlib provides functions with which you can determine the best size, 
the tile or stipple for the display
as well as set the tile or stipple shape and the tile/stipple origin.
.LP
.sp
To obtain the best (closest) size,
use
.PN XQueryBestSize .
.IN "XQueryBestSize"
.IN "Protocol request" "XQueryBestSize"
The definition of this function is:
.IN "Definitions" "XQueryBestSize"
.FD 0
.so ./Xsrc/XQBestSize.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/class_size.a
.so ./Xsrc/d.a
.so ./Xsrc/widtheight.a
.so ./Xsrc/rwidtheight.a
.LP
.PN XQueryBestSize
returns the ``best'' or ``closest'' size to the specified size.
For 
.PN CursorShape ,
this is the largest size that can be fully displayed.
For 
.PN TileShape ,
this is the size that can be tiled ``fastest''.
For 
.PN StippleShape ,
this is the size that can be stippled ``fastest''.
.LP
For 
.PN CursorShape ,
the drawable indicates the desired screen.
For 
.PN TileShape 
and 
.PN StippleShape ,
the drawable indicates the screen and possibly the window class and depth.
An 
.PN InputOnly 
window cannot be used as the drawable for 
.PN TileShape
or 
.PN StippleShape 
(else a 
.PN BadMatch 
error occurs).
.LP
.sp
To obtain the best (closest) fill tile shape,
use
.PN XQueryBestTile .
.IN "XQueryBestTile"
.IN "Protocol request" "XQueryBestTile"
The definition of this function is:
.IN "Definitions" "XQueryBestTile"
.FD 0
.so ./Xsrc/XQTileShp.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
.so ./Xsrc/widtheight.a
.so ./Xsrc/rwidtheight.a
.LP
.PN XQueryBestTile
returns the ``best'' or ``closest'' size, that is, the size that can be 
tiled ``fastest''.
The drawable indicates the screen and possibly the window class and depth.
An 
.PN InputOnly 
window cannot be used as the drawable for
.PN XQueryBestTile
(else a 
.PN BadMatch 
error occurs).
.LP
.sp
To obtain the best (closest) stipple shape,
use
.PN XQueryBestStipple .
.IN "XQueryBestStipple"
.IN "Protocol request" "XQueryBestStipple"
The definition of this function is:
.IN "Definitions" "XQueryBestStipple"
.FD 0
.so ./Xsrc/XQStipShp.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/d.a
.so ./Xsrc/widtheight.a
.so ./Xsrc/rwidtheight.a
.LP
.PN XQueryBestStipple
returns the ``best'' or ``closest'' size, that is, the size that can be
stippled ``fastest''.
The drawable indicates the screen and possibly the window class and depth.
An 
.PN InputOnly 
window cannot be used as the drawable for
.PN XQueryBestStipple
(else a 
.PN BadMatch 
error occurs).
.LP
.sp
To set the fill tile in the specified graphics context, 
use 
.PN XSetTile .
.IN "XSetTile"
.IN "Protocol request" "XSetTile"
The definition for this function is:
.IN "Definitions" "XSetTile"
.FD 0
.so ./Xsrc/XSetTile.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/tile1.a
.LP
.sp
To set the stipple in the specified graphics context, 
use 
.PN XSetStipple .
.IN "XSetStipple"
.IN "Protocol request" "XSetStipple"
The definition for this function is:
.IN "Definitions" "XSetStipple"
.FD 0
.so ./Xsrc/XSetStipple.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/stipple.a
.LP
.sp
To set the tile/stipple origin in the specified graphics context,
use
.PN XSetTSOrigin .
.IN "XSetTSOrigin"
.IN "Protocol request" "XSetTSOrigin"
The definition for this function is:
.IN "Definitions" "XSetTSOrigin"
.FD 0
.so ./Xsrc/XSetTSOrig.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/tsxy.a
.NH 3
Setting the Current Font 
.LP
To set the current font in the specified graphics context, 
use 
.PN XSetFont .
.IN "XSetFont"
.IN "Protocol request" "XSetFont"
The definition for this function is:
.IN "Definitions" "XSetFont"
.FD 0
.so ./Xsrc/XSetFont.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/font.a
.NH 3
Setting Clip Region
.LP
Xlib provides functions with which you can set the clip origin or the clip mask
as well as with which you can change the clip mask.
.LP
.sp
To set the clip origin in the specified graphics context, 
use 
.PN XSetClipOrigin .
.IN "XSetClipOrigin"
.IN "Protocol request" "XSetClipOrigin"
The definition for this function is:
.IN "Definitions" "XSetClipOrigin"
.FD 0
.so ./Xsrc/XSetClipOrig.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/clipxy.a
.LP
.sp
To set the clip_mask in the specified graphics context to the
specified pixmap, use
.PN XSetClipMask .
.IN "XSetClipMask"
The definition for this function is:
.IN "Definitions" "XSetClipMask"
.FD 0
.so ./Xsrc/XSetClpMask.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/pixmap.a
.LP
.sp
To change the clip_mask in the specified graphics context to 
the specified list of rectangles, use 
.PN XSetClipRectangles .
.IN "XSetClipRectangles"
.IN "Protocol request" "XSetClipRectangles"
The definition for this function is:
.IN "Definitions" "XSetClipRectangles"
.FD 0
.so ./Xsrc/XSetClpRects.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/clipxy.a
.so ./Xsrc/rectangles1.a
These are the rectangles you want to specify in the graphics context.
.so ./Xsrc/n2.a
.so ./Xsrc/ordering.a
.LP
The output then is clipped to remain contained within the
rectangles.
The number of rectangles are specified with the n argument.  
The clip origin is interpreted relative to the origin of
whatever destination drawable is specified in a graphics request.  
The rectangle coordinates are interpreted relative to the clip origin.  
The rectangles should be non-intersecting, or graphics results will be
undefined.
.LP
If known by the client, ordering relations on the rectangles can be
specified with the ordering argument; this may provide faster operation
by the server. 
If an incorrect ordering is specified, the graphics
results are undefined.
.PN Unsorted 
means the rectangles are in arbitrary order.
.PN YSorted 
means that the rectangles are nondecreasing in their Y
component.  
.PN YXSorted 
additionally constrains 
.PN YSorted 
order in that all
rectangles with an equal Y component are non-decreasing in their X
component.  
.PN YXBanded 
additionally constrains 
.PN YXSorted 
by requiring that
for every possible Y scan line, all rectangles that include that
scan line have an identical Y component.
.NT
The Xlib library provides a set of basic functions for performing
region arithmetic.
For information about these functions,
see Chapter 10.
.NE
.NH 3
Setting the Arc Mode, Subwindow Mode, and Graphics Exposure components
.LP
To set the arc mode in the specified graphics context, 
use 
.PN XSetArcMode .
.IN "XSetArcMode"
.IN "Protocol request" "XSetArcMode"
The definition for this function is:
.IN "Definitions" "XSetArcMode"
.FD 0
.so ./Xsrc/XSetArcMode.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/arc_mode.a
.LP
.sp
To set the subwindow mode in the specified graphics context, 
use 
.PN XSetSubwindowMode .
.IN "XSetSubwindowMode"
.IN "Protocol request" "XSetSubwindowMode"
The definition for this function is:
.IN "Definitions" "XSetSubwindowMode"
.FD 0
.so ./Xsrc/XSetSubMode.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/sub_mode.a
.LP
.sp
To set the graphics-exposures flag in the specified graphics context, 
use 
.PN XSetGraphicsExposures .
.IN "XSetGraphicsExposures"
.IN "Protocol request" "XSetGraphicsExposures"
The definition for this function is:
.IN "Definitions" "XSetGraphicsExposures"
.FD 0
.so ./Xsrc/XSetGrExp.f
.FN
.so ./Xsrc/display.a
.so ./Xsrc/gc.a
.so ./Xsrc/graph_exp.a
.bp