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. Note that XRender expects premultiplied alpha in all
cases except with the gradient operations.
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.
If a format with alpha is used, make sure it is premultiplied into the
color channels.
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.
Generated by dwww version 1.15 on Thu Jun 27 23:13:04 CEST 2024.