aboutsummaryrefslogtreecommitdiff
path: root/libXrender/doc/libXrender.txt
diff options
context:
space:
mode:
Diffstat (limited to 'libXrender/doc/libXrender.txt')
-rw-r--r--libXrender/doc/libXrender.txt600
1 files changed, 600 insertions, 0 deletions
diff --git a/libXrender/doc/libXrender.txt b/libXrender/doc/libXrender.txt
new file mode 100644
index 000000000..79af0345a
--- /dev/null
+++ b/libXrender/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.