diff options
Diffstat (limited to 'libXrender/doc/libXrender.txt')
| -rw-r--r-- | libXrender/doc/libXrender.txt | 600 |
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. |