Edit
IABSD.fr/xenocara/lib/libXrender/doc
matthieu
- libXrender.txt
-
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 correspond 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 corresponding 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 12 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.