Move libXrender documentation from xorg-docs

Signed-off-by: Alan Coopersmith <alan.coopersmith@sun.com>

1 files changed, 600 insertions, 0 deletions

diff --git a/doc/libXrender.txt b/doc/libXrender.txt
new file mode 100644
index 0000000..79af034
--- /dev/null
+++ b/doc/libXrender.txt
@@ -0,0 +1,600 @@
+                         The Xrender Library
+			    Version 0.7
+			      2002-11-6
+			    Keith Packard
+			  keithp@xfree86.org
+
+1. Introduction
+
+The Xrender library is designed as a lightweight library interface to the
+Render extension.  This document describes how the library maps to the
+protocol without duplicating the semantics described by that document.
+
+2. Data Types
+
+2.1 Primitive Types
+
+For resources represented as CARD32 or XID on the wire, Xrender exposes them
+using an 'unsigned long' type as is the norm for 32-bit data objects in an
+Xlib compatible API.
+
+	typedef unsigned long	Glyph;
+	typedef unsigned long	GlyphSet;
+	typedef unsigned long	Picture;
+	typedef unsigned long	PictFormat;
+
+Glyphs are just CARD32 objects, while GlyphSet, Picture and PictFormat
+values are XIDs.
+
+	typedef int XFixed;
+
+Fixed point numbers buck the Xlib convention by being represented as ints.
+Machines for which 'int' is smaller than 32 bits cannot support the Xrender
+library.
+
+2.2 PictFormat descriptions.
+
+The definition of a PictFormat is exposed by two data structures:
+
+	typedef struct {
+	    short   red;
+	    short   redMask;
+	    short   green;
+	    short   greenMask;
+	    short   blue;
+	    short   blueMask;
+	    short   alpha;
+	    short   alphaMask;
+	} XRenderDirectFormat;
+
+	typedef struct {
+	    PictFormat		id;
+	    int			type;
+	    int			depth;
+	    XRenderDirectFormat	direct;
+	    Colormap		colormap;
+	} XRenderPictFormat;
+
+These serve both as a description of the available formats and as patterns
+against which available formats are matched.
+
+2.3 Picture Attributes
+
+When creating or changing Picture objects, attributes are passed much as
+they are for XCreateWindow/XChangeWindowAttributes.  A structure capable of
+holding all of the attributes has the relevant ones set and a bitmask passed
+as a separate argument which marks the valid entries.
+
+	typedef struct _XRenderPictureAttributes {
+	    Bool		repeat;
+	    Picture		alpha_map;
+	    int			alpha_x_origin;
+	    int			alpha_y_origin;
+	    int			clip_x_origin;
+	    int			clip_y_origin;
+	    Pixmap		clip_mask;
+	    Bool		graphics_exposures;
+	    int			subwindow_mode;
+	    int			poly_edge;
+	    int			poly_mode;
+	    Atom		dither;
+	    Bool		component_alpha;
+	} XRenderPictureAttributes;
+
+2.4 Colors
+
+The core protocol XColor type doesn't include an alpha component, so Xrender
+has a separate type.
+
+	typedef struct {
+	    unsigned short   red;
+	    unsigned short   green;
+	    unsigned short   blue;
+	    unsigned short   alpha;
+	} XRenderColor;
+
+2.5 Glyph Types
+
+Glyphs are stored in the server, so these definitions are passed from the
+client to the library and on to the server as glyphs are rasterized and
+transmitted over the wire.
+
+	typedef struct _XGlyphInfo {
+	    unsigned short  width;
+	    unsigned short  height;
+	    short	    x;
+	    short	    y;
+	    short	    xOff;
+	    short	    yOff;
+	} XGlyphInfo;
+
+2.6 Glyph Rendering types
+
+Glyph rendering can either take a single string of glyph indices or an array
+of one of the following structures.
+
+	typedef struct _XGlyphElt8 {
+	    GlyphSet		    glyphset;
+	    _Xconst char	    *chars;
+	    int			    nchars;
+	    int			    xOff;
+	    int			    yOff;
+	} XGlyphElt8;
+
+	typedef struct _XGlyphElt16 {
+	    GlyphSet		    glyphset;
+	    _Xconst unsigned short  *chars;
+	    int			    nchars;
+	    int			    xOff;
+	    int			    yOff;
+	} XGlyphElt16;
+
+	typedef struct _XGlyphElt32 {
+	    GlyphSet		    glyphset;
+	    _Xconst unsigned int    *chars;
+	    int			    nchars;
+	    int			    xOff;
+	    int			    yOff;
+	} XGlyphElt32;
+
+2.7 Geometric Types
+
+Geometric operations directly expose the available protocol datatypes
+
+	typedef struct _XPointFixed {
+	    XFixed  x, y;
+	} XPointFixed;
+
+	typedef struct _XLineFixed {
+	    XPointFixed	p1, p2;
+	} XLineFixed;
+
+	typedef struct _XTriangle {
+	    XPointFixed	p1, p2, p3;
+	} XTriangle;
+
+	typedef struct _XTrapezoid {
+	    XFixed  top, bottom;
+	    XLineFixed	left, right;
+	} XTrapezoid;
+
+	typedef struct _XTransform {
+	    XFixed  matrix[3][3];
+	} XTransform;
+
+2.8 Transformation Filters
+
+All of the filters are named simultaneously; Xrender provides no convenience
+functions for dealing with them.
+
+	typedef struct _XFilters {
+	    int	    nfilter;
+	    char    **filter;
+	    int	    nalias;
+	    short   *alias;
+	} XFilters;
+
+2.9 Index type PictFormat colors
+
+PictFormats of Index type advertise which colors will be used for drawing
+through this type.
+
+	typedef struct _XIndexValue {
+	    unsigned long    pixel;
+	    unsigned short   red, green, blue, alpha;
+	} XIndexValue;
+
+
+3 Application Startup Functions
+
+3.1 Initialization functions
+
+	Bool XRenderQueryExtension (Display *dpy,
+			            int     *event_basep,
+				    int     *error_basep)
+
+This function returns True if the Render extension is available on dpy.
+event_basep and error_basep will be filled in with the first event and error
+numbers used by the extension (note that Render currently uses no events).
+
+	Status XRenderQueryVersion (Display *dpy,
+				    int     *major_versionp,
+				    int     *minor_versionp)
+
+XRenderQueryVersion returns zero if the Render extension is not present or
+some error occurred while attempting to discover the current Render version
+number.  Otherwise, XRenderQueryVersion returns 1 and stores the version
+number returned by the server in *major_versionp and *minor_versionp, which
+will be less than or equal to the library version numbers RENDER_MAJOR and
+RENDER_MINOR.
+
+	Status XRenderQueryFormats (Display *dpy)
+
+XRenderQueryFormats returns 1 if it successfully fetches the available
+PictFormat information from the X server, 0 otherwise.  Applications needn't
+invoke this function directly (hmm, perhaps it should be removed from the
+external interfaces then).
+
+3.2 Subpixel Order
+
+	int XRenderQuerySubpixelOrder (Display *dpy, int screen)
+
+	Bool XRenderSetSubpixelOrder (Display *dpy, int screen, int subpixel)
+
+Applications interested in the geometry of the elements making up a single
+pixel on the screen should use XRenderQuerySubpixelOrder and not cache the
+return value.  XRenderSetSubpixelOrder is used by the XRandR library to
+update the value stored by Xrender when the subpixel order changes as a
+result of screen reconfiguration.
+
+3.3 PictFormat matching
+
+Xrender provides these APIs to help locate appropriate PictFormats; they are
+intended to work much like the Visual matching APIs in Xlib.  The
+application provides a specification including the necessary PictFormat
+characteristics and Xrender returns a matching XRenderPictFormat structure
+which describes the PictFormat.
+
+	XRenderPictFormat *
+	XRenderFindFormat (Display			*dpy,
+			   unsigned long		mask,
+			   _Xconst XRenderPictFormat	*templ,
+			   int				count)
+
+	#define PictFormatID	    (1 << 0)
+	#define PictFormatType	    (1 << 1)
+	#define PictFormatDepth	    (1 << 2)
+	#define PictFormatRed	    (1 << 3)
+	#define PictFormatRedMask   (1 << 4)
+	#define PictFormatGreen	    (1 << 5)
+	#define PictFormatGreenMask (1 << 6)
+	#define PictFormatBlue	    (1 << 7)
+	#define PictFormatBlueMask  (1 << 8)
+	#define PictFormatAlpha	    (1 << 9)
+	#define PictFormatAlphaMask (1 << 10)
+	#define PictFormatColormap  (1 << 11)
+
+XRenderFindFormat locates a PictFormat matching the characteristics provided
+in the templ.  Only elements whose associated bit in mask are compared.
+
+	XRenderPictFormat *
+	XRenderFindVisualFormat (Display *dpy, _Xconst Visual *visual)
+
+Finds the PictFormat suitable for use with the specified visual.
+
+	XRenderPictFormat *
+	XRenderFindStandardFormat (Display		*dpy,
+				   int			format)
+
+	#define PictStandardARGB32  0
+	#define PictStandardRGB24   1
+	#define PictStandardA8	    2
+	#define PictStandardA4	    3
+	#define PictStandardA1	    4
+	#define PictStandardNUM	    5
+
+As a convenience, this function locates PictFormats that coorespond to
+commonly used formats.
+
+	ARGB32		depth 32, bits 31-24 A, 23-16 R, 15-8 G, 7-0 B
+	RGB24		depth 24, bits 23-16 R, 15-8 G, 7-0 B
+	A8		depth 8, bits 7-0 A
+	A4		depth 4, bits 3-0 A
+	A1		depth 1, bits 0 A
+
+Any server supporting Render must have a PictFormat cooresponding to each of
+these standard formats.
+
+3.4 Index type PictFormat color values
+
+	XIndexValue *
+	XRenderQueryPictIndexValues(Display			*dpy,
+				    _Xconst XRenderPictFormat	*format,
+				    int				*num)
+
+If format refers to an Index type PictFormat, XRenderQueryPictIndexValues
+returns the set of pixel values and their associated colors used when
+drawing to Pictures created with that format.  Otherwise,
+XRenderQueryPictIndexValues generates a BadMatch error.
+
+3.5 Querying available filters
+
+	XFilters *
+	XRenderQueryFilters (Display *dpy, Drawable drawable);
+
+Filters are used with non-identity transformation matrices, this function
+returns a datastructure identifying the available filters on display that
+can be associated with pictures for the screen associated with drawable.
+
+Free this structure with XFree.
+
+4 Picture Functions
+
+	Picture
+	XRenderCreatePicture (Display				*dpy,
+			      Drawable				drawable,
+			      _Xconst XRenderPictFormat		*format,
+			      unsigned long			valuemask,
+			      _Xconst XRenderPictureAttributes	*attributes)
+
+	#define CPRepeat			    (1 << 0)
+	#define CPAlphaMap			    (1 << 1)
+	#define CPAlphaXOrigin			    (1 << 2)
+	#define CPAlphaYOrigin			    (1 << 3)
+	#define CPClipXOrigin			    (1 << 4)
+	#define CPClipYOrigin			    (1 << 5)
+	#define CPClipMask			    (1 << 6)
+	#define CPGraphicsExposure		    (1 << 7)
+	#define CPSubwindowMode			    (1 << 8)
+	#define CPPolyEdge			    (1 << 9)
+	#define CPPolyMode			    (1 << 10)
+	#define CPDither			    (1 << 11)
+	#define CPComponentAlpha		    (1 << 12)
+	#define CPLastBit			    11
+
+Creates a picture for drawable in the specified format.  Any values
+specified in 'attributes' and 'valuemask' are used in place of the default
+values.
+
+	void
+	XRenderChangePicture (Display				*dpy,
+			      Picture				picture,
+			      unsigned long			valuemask,
+			      _Xconst XRenderPictureAttributes  *attributes)
+
+Change values in picture to those specified by valuemask and attributes.
+
+
+	void
+	XRenderSetPictureClipRectangles (Display	    *dpy,
+					 Picture	    picture,
+					 int		    xOrigin,
+					 int		    yOrigin,
+					 _Xconst XRectangle *rects,
+					 int		    n)
+
+Sets the clip mask in picture to the union of rects offset by
+xOrigin/yOrigin.
+
+	void
+	XRenderSetPictureClipRegion (Display	    *dpy,
+				     Picture	    picture,
+				     Region	    r)
+
+Sets the clip mask in picture to r.
+
+	void
+	XRenderSetPictureTransform (Display	    *dpy,
+				    Picture	    picture,
+				    XTransform	    *transform)
+
+Sets the projective transformation matrix of picture to transform.
+
+	void
+	XRenderFreePicture (Display                   *dpy,
+			    Picture                   picture)
+
+Instructs the server to free picture.
+
+5 GlyphSet functions
+
+	GlyphSet
+	XRenderCreateGlyphSet (Display *dpy, _Xconst XRenderPictFormat *format)
+
+Creates a glyphset, every glyph in the set will use PictFormat format.
+
+	GlyphSet
+	XRenderReferenceGlyphSet (Display *dpy, GlyphSet existing)
+
+Creates a new GlyphSet ID which references an existing GlyphSet.  The
+two IDs refer to the same object so that changes using one ID will be
+visible through the other ID.  This is designed to allow multiple clients to
+share the same GlyphSet so that it doesn't get destroyed when the first
+client exits.
+
+	void
+	XRenderFreeGlyphSet (Display *dpy, GlyphSet glyphset)
+
+Frees the glyphset ID.  If no other GlyphSet IDs refer to the underlying
+GlyphSet, it will be destroyed.
+
+	void
+	XRenderAddGlyphs (Display		*dpy,
+			  GlyphSet		glyphset,
+			  _Xconst Glyph		*gids,
+			  _Xconst XGlyphInfo	*glyphs,
+			  int			nglyphs,
+			  _Xconst char		*images,
+			  int			nbyte_images)
+
+Add glyphs to glyphset.  The images are packed together in Z-pixmap format
+according to the depth of the PictFormat used in creating glyphset.
+
+	void
+	XRenderFreeGlyphs (Display	    *dpy,
+			   GlyphSet	    glyphset,
+			   _Xconst Glyph    *gids,
+			   int		    nglyphs)
+
+Free some glyphs from glyphset.
+
+6 Glyph Drawing Routines
+
+Xrender provides two parallel APIs for glyph rendering, a simple API which
+accepts a single string similar to XDrawString and a more complex API which
+accepts an array of XGlyphElt{8,16,32} structures, each of which includes a
+glyphset, string and x/y offsets which parallel the XDrawText API.  Xrender
+also provides glyphs in three sizes, 8 16 and 32 bits.  The simple API is
+just a convenience for the user as both forms generate the same underlying
+Render protocol.
+
+6.1 Simple single-string glyph drawing functions
+
+These are identical except for the format of the glyph ids.
+
+	void
+	XRenderCompositeString8 (Display		    *dpy,
+				 int			    op,
+				 Picture		    src,
+				 Picture		    dst,
+				 _Xconst XRenderPictFormat  *maskFormat,
+				 GlyphSet		    glyphset,
+				 int			    xSrc,
+				 int			    ySrc,
+				 int			    xDst,
+				 int			    yDst,
+				 _Xconst char		    *string,
+				 int			    nchar)
+
+	void
+	XRenderCompositeString16 (Display		    *dpy,
+				  int			    op,
+				  Picture		    src,
+				  Picture		    dst,
+				  _Xconst XRenderPictFormat *maskFormat,
+				  GlyphSet		    glyphset,
+				  int			    xSrc,
+				  int			    ySrc,
+				  int			    xDst,
+				  int			    yDst,
+				  _Xconst unsigned short    *string,
+				  int			    nchar)
+
+	void
+	XRenderCompositeString32 (Display		    *dpy,
+				  int			    op,
+				  Picture		    src,
+				  Picture		    dst,
+				  _Xconst XRenderPictFormat *maskFormat,
+				  GlyphSet		    glyphset,
+				  int			    xSrc,
+				  int			    ySrc,
+				  int			    xDst,
+				  int			    yDst,
+				  _Xconst unsigned int	    *string,
+				  int			    nchar)
+
+6.2 Complete glyph drawing functions
+
+As with the simple functions above, these differ only in the type of the
+underlying glyph id storage type.
+
+	void
+	XRenderCompositeText8 (Display			    *dpy,
+			       int			    op,
+			       Picture			    src,
+			       Picture			    dst,
+			       _Xconst XRenderPictFormat    *maskFormat,
+			       int			    xSrc,
+			       int			    ySrc,
+			       int			    xDst,
+			       int			    yDst,
+			       _Xconst XGlyphElt8	    *elts,
+			       int			    nelt)
+
+	void
+	XRenderCompositeText16 (Display			    *dpy,
+				int			    op,
+				Picture			    src,
+				Picture			    dst,
+				_Xconst XRenderPictFormat   *maskFormat,
+				int			    xSrc,
+				int			    ySrc,
+				int			    xDst,
+				int			    yDst,
+				_Xconst XGlyphElt16	    *elts,
+				int			    nelt)
+
+	void
+	XRenderCompositeText32 (Display			    *dpy,
+				int			    op,
+				Picture			    src,
+				Picture			    dst,
+				_Xconst XRenderPictFormat   *maskFormat,
+				int			    xSrc,
+				int			    ySrc,
+				int			    xDst,
+				int			    yDst,
+				_Xconst XGlyphElt32	    *elts,
+				int			    nelt)
+
+7 Basic Graphics Functions
+
+These are the simplest graphics functions upon which the other functions are
+conceptually built.
+
+7.1 Composite
+
+XRenderComposite exposes the RenderComposite protocol request directly.
+
+	void
+	XRenderComposite (Display   *dpy,
+			  int	    op,
+			  Picture   src,
+			  Picture   mask,
+			  Picture   dst,
+			  int	    src_x,
+			  int	    src_y,
+			  int	    mask_x,
+			  int	    mask_y,
+			  int	    dst_x,
+			  int	    dst_y,
+			  unsigned int	width,
+			  unsigned int	height)
+
+
+7.2 Rectangles
+
+These functions composite rectangles of the specified color, they differ
+only in that XRenderFillRectangles draws more than one at a time.
+
+	void
+	XRenderFillRectangle (Display		    *dpy,
+			      int		    op,
+			      Picture		    dst,
+			      _Xconst XRenderColor  *color,
+			      int		    x,
+			      int		    y,
+			      unsigned int	    width,
+			      unsigned int	    height)
+
+	void
+	XRenderFillRectangles (Display		    *dpy,
+			       int		    op,
+			       Picture		    dst,
+			       _Xconst XRenderColor *color,
+			       _Xconst XRectangle   *rectangles,
+			       int		    n_rects)
+
+8 Geometric Objects
+
+All geometric drawing with Render is performed with sequences of trapezoids
+or triangles; the client is responsible for breaking more complex figures
+into these simple shapes.
+
+8.1 Trapezoids
+
+	void
+	XRenderCompositeTrapezoids (Display		*dpy,
+				    int			op,
+				    Picture		src,
+				    Picture		dst,
+				    _Xconst XRenderPictFormat	*maskFormat,
+				    int			xSrc,
+				    int			ySrc,
+				    _Xconst XTrapezoid	*traps,
+				    int			ntrap)
+
+XRenderCompositeTrapezoids builds RenderTrapezoids requests to composite the
+specified list of trapezoids to dst.  XRenderCompositeTrapezoids will split
+the list of trapezoids to build requests no larger than the maximum request
+size supported by the server.  This can create rendering artifacts as the
+precompositing done by RenderTrapezoids when a maskFormat is specified
+cannot span multiple requests.
+
+8.2 Triangles
+
+Render provides three different ways of encoding triangles on the wire,
+Xrender exposes those with three separate triangle drawing routines.  As
+with trapezoids above, Xrender will split the arguments to fit requests into
+the servers limits, but this may cause rendering artifacts.