libXrender.txt revision 2fd96bc7 
1                         The Xrender Library
2			    Version 0.7
3			      2002-11-6
4			    Keith Packard
5			  keithp@xfree86.org
6
71. Introduction
8
9The Xrender library is designed as a lightweight library interface to the
10Render extension.  This document describes how the library maps to the
11protocol without duplicating the semantics described by that document.
12
132. Data Types
14
152.1 Primitive Types
16
17For resources represented as CARD32 or XID on the wire, Xrender exposes them
18using an 'unsigned long' type as is the norm for 32-bit data objects in an
19Xlib compatible API.
20
21	typedef unsigned long	Glyph;
22	typedef unsigned long	GlyphSet;
23	typedef unsigned long	Picture;
24	typedef unsigned long	PictFormat;
25
26Glyphs are just CARD32 objects, while GlyphSet, Picture and PictFormat
27values are XIDs.
28
29	typedef int XFixed;
30
31Fixed point numbers buck the Xlib convention by being represented as ints.
32Machines for which 'int' is smaller than 32 bits cannot support the Xrender
33library.
34
352.2 PictFormat descriptions.
36
37The definition of a PictFormat is exposed by two data structures:
38
39	typedef struct {
40	    short   red;
41	    short   redMask;
42	    short   green;
43	    short   greenMask;
44	    short   blue;
45	    short   blueMask;
46	    short   alpha;
47	    short   alphaMask;
48	} XRenderDirectFormat;
49
50	typedef struct {
51	    PictFormat		id;
52	    int			type;
53	    int			depth;
54	    XRenderDirectFormat	direct;
55	    Colormap		colormap;
56	} XRenderPictFormat;
57
58These serve both as a description of the available formats and as patterns
59against which available formats are matched.
60
612.3 Picture Attributes
62
63When creating or changing Picture objects, attributes are passed much as
64they are for XCreateWindow/XChangeWindowAttributes.  A structure capable of
65holding all of the attributes has the relevant ones set and a bitmask passed
66as a separate argument which marks the valid entries.
67
68	typedef struct _XRenderPictureAttributes {
69	    Bool		repeat;
70	    Picture		alpha_map;
71	    int			alpha_x_origin;
72	    int			alpha_y_origin;
73	    int			clip_x_origin;
74	    int			clip_y_origin;
75	    Pixmap		clip_mask;
76	    Bool		graphics_exposures;
77	    int			subwindow_mode;
78	    int			poly_edge;
79	    int			poly_mode;
80	    Atom		dither;
81	    Bool		component_alpha;
82	} XRenderPictureAttributes;
83
842.4 Colors
85
86The core protocol XColor type doesn't include an alpha component, so Xrender
87has a separate type. Note that XRender expects premultiplied alpha in all
88cases except with the gradient operations.
89
90	typedef struct {
91	    unsigned short   red;
92	    unsigned short   green;
93	    unsigned short   blue;
94	    unsigned short   alpha;
95	} XRenderColor;
96
972.5 Glyph Types
98
99Glyphs are stored in the server, so these definitions are passed from the
100client to the library and on to the server as glyphs are rasterized and
101transmitted over the wire.
102
103	typedef struct _XGlyphInfo {
104	    unsigned short  width;
105	    unsigned short  height;
106	    short	    x;
107	    short	    y;
108	    short	    xOff;
109	    short	    yOff;
110	} XGlyphInfo;
111
1122.6 Glyph Rendering types
113
114Glyph rendering can either take a single string of glyph indices or an array
115of one of the following structures.
116
117	typedef struct _XGlyphElt8 {
118	    GlyphSet		    glyphset;
119	    _Xconst char	    *chars;
120	    int			    nchars;
121	    int			    xOff;
122	    int			    yOff;
123	} XGlyphElt8;
124
125	typedef struct _XGlyphElt16 {
126	    GlyphSet		    glyphset;
127	    _Xconst unsigned short  *chars;
128	    int			    nchars;
129	    int			    xOff;
130	    int			    yOff;
131	} XGlyphElt16;
132
133	typedef struct _XGlyphElt32 {
134	    GlyphSet		    glyphset;
135	    _Xconst unsigned int    *chars;
136	    int			    nchars;
137	    int			    xOff;
138	    int			    yOff;
139	} XGlyphElt32;
140
1412.7 Geometric Types
142
143Geometric operations directly expose the available protocol datatypes
144
145	typedef struct _XPointFixed {
146	    XFixed  x, y;
147	} XPointFixed;
148
149	typedef struct _XLineFixed {
150	    XPointFixed	p1, p2;
151	} XLineFixed;
152
153	typedef struct _XTriangle {
154	    XPointFixed	p1, p2, p3;
155	} XTriangle;
156
157	typedef struct _XTrapezoid {
158	    XFixed  top, bottom;
159	    XLineFixed	left, right;
160	} XTrapezoid;
161
162	typedef struct _XTransform {
163	    XFixed  matrix[3][3];
164	} XTransform;
165
1662.8 Transformation Filters
167
168All of the filters are named simultaneously; Xrender provides no convenience
169functions for dealing with them.
170
171	typedef struct _XFilters {
172	    int	    nfilter;
173	    char    **filter;
174	    int	    nalias;
175	    short   *alias;
176	} XFilters;
177
1782.9 Index type PictFormat colors
179
180PictFormats of Index type advertise which colors will be used for drawing
181through this type.
182
183	typedef struct _XIndexValue {
184	    unsigned long    pixel;
185	    unsigned short   red, green, blue, alpha;
186	} XIndexValue;
187
188
1893 Application Startup Functions
190
1913.1 Initialization functions
192
193	Bool XRenderQueryExtension (Display *dpy,
194			            int     *event_basep,
195				    int     *error_basep)
196
197This function returns True if the Render extension is available on dpy.
198event_basep and error_basep will be filled in with the first event and error
199numbers used by the extension (note that Render currently uses no events).
200
201	Status XRenderQueryVersion (Display *dpy,
202				    int     *major_versionp,
203				    int     *minor_versionp)
204
205XRenderQueryVersion returns zero if the Render extension is not present or
206some error occurred while attempting to discover the current Render version
207number.  Otherwise, XRenderQueryVersion returns 1 and stores the version
208number returned by the server in *major_versionp and *minor_versionp, which
209will be less than or equal to the library version numbers RENDER_MAJOR and
210RENDER_MINOR.
211
212	Status XRenderQueryFormats (Display *dpy)
213
214XRenderQueryFormats returns 1 if it successfully fetches the available
215PictFormat information from the X server, 0 otherwise.  Applications needn't
216invoke this function directly (hmm, perhaps it should be removed from the
217external interfaces then).
218
2193.2 Subpixel Order
220
221	int XRenderQuerySubpixelOrder (Display *dpy, int screen)
222
223	Bool XRenderSetSubpixelOrder (Display *dpy, int screen, int subpixel)
224
225Applications interested in the geometry of the elements making up a single
226pixel on the screen should use XRenderQuerySubpixelOrder and not cache the
227return value.  XRenderSetSubpixelOrder is used by the XRandR library to
228update the value stored by Xrender when the subpixel order changes as a
229result of screen reconfiguration.
230
2313.3 PictFormat matching
232
233Xrender provides these APIs to help locate appropriate PictFormats; they are
234intended to work much like the Visual matching APIs in Xlib.  The
235application provides a specification including the necessary PictFormat
236characteristics and Xrender returns a matching XRenderPictFormat structure
237which describes the PictFormat.
238
239	XRenderPictFormat *
240	XRenderFindFormat (Display			*dpy,
241			   unsigned long		mask,
242			   _Xconst XRenderPictFormat	*templ,
243			   int				count)
244
245	#define PictFormatID	    (1 << 0)
246	#define PictFormatType	    (1 << 1)
247	#define PictFormatDepth	    (1 << 2)
248	#define PictFormatRed	    (1 << 3)
249	#define PictFormatRedMask   (1 << 4)
250	#define PictFormatGreen	    (1 << 5)
251	#define PictFormatGreenMask (1 << 6)
252	#define PictFormatBlue	    (1 << 7)
253	#define PictFormatBlueMask  (1 << 8)
254	#define PictFormatAlpha	    (1 << 9)
255	#define PictFormatAlphaMask (1 << 10)
256	#define PictFormatColormap  (1 << 11)
257
258XRenderFindFormat locates a PictFormat matching the characteristics provided
259in the templ.  Only elements whose associated bit in mask are compared.
260
261	XRenderPictFormat *
262	XRenderFindVisualFormat (Display *dpy, _Xconst Visual *visual)
263
264Finds the PictFormat suitable for use with the specified visual.
265
266	XRenderPictFormat *
267	XRenderFindStandardFormat (Display		*dpy,
268				   int			format)
269
270	#define PictStandardARGB32  0
271	#define PictStandardRGB24   1
272	#define PictStandardA8	    2
273	#define PictStandardA4	    3
274	#define PictStandardA1	    4
275	#define PictStandardNUM	    5
276
277As a convenience, this function locates PictFormats that correspond to
278commonly used formats.
279
280	ARGB32		depth 32, bits 31-24 A, 23-16 R, 15-8 G, 7-0 B
281	RGB24		depth 24, bits 23-16 R, 15-8 G, 7-0 B
282	A8		depth 8, bits 7-0 A
283	A4		depth 4, bits 3-0 A
284	A1		depth 1, bits 0 A
285
286Any server supporting Render must have a PictFormat corresponding to each of
287these standard formats.
288
2893.4 Index type PictFormat color values
290
291	XIndexValue *
292	XRenderQueryPictIndexValues(Display			*dpy,
293				    _Xconst XRenderPictFormat	*format,
294				    int				*num)
295
296If format refers to an Index type PictFormat, XRenderQueryPictIndexValues
297returns the set of pixel values and their associated colors used when
298drawing to Pictures created with that format.  Otherwise,
299XRenderQueryPictIndexValues generates a BadMatch error.
300
3013.5 Querying available filters
302
303	XFilters *
304	XRenderQueryFilters (Display *dpy, Drawable drawable);
305
306Filters are used with non-identity transformation matrices, this function
307returns a datastructure identifying the available filters on display that
308can be associated with pictures for the screen associated with drawable.
309
310Free this structure with XFree.
311
3124 Picture Functions
313
314	Picture
315	XRenderCreatePicture (Display				*dpy,
316			      Drawable				drawable,
317			      _Xconst XRenderPictFormat		*format,
318			      unsigned long			valuemask,
319			      _Xconst XRenderPictureAttributes	*attributes)
320
321	#define CPRepeat			    (1 << 0)
322	#define CPAlphaMap			    (1 << 1)
323	#define CPAlphaXOrigin			    (1 << 2)
324	#define CPAlphaYOrigin			    (1 << 3)
325	#define CPClipXOrigin			    (1 << 4)
326	#define CPClipYOrigin			    (1 << 5)
327	#define CPClipMask			    (1 << 6)
328	#define CPGraphicsExposure		    (1 << 7)
329	#define CPSubwindowMode			    (1 << 8)
330	#define CPPolyEdge			    (1 << 9)
331	#define CPPolyMode			    (1 << 10)
332	#define CPDither			    (1 << 11)
333	#define CPComponentAlpha		    (1 << 12)
334	#define CPLastBit			    12
335
336Creates a picture for drawable in the specified format.  Any values
337specified in 'attributes' and 'valuemask' are used in place of the default
338values.
339
340	void
341	XRenderChangePicture (Display				*dpy,
342			      Picture				picture,
343			      unsigned long			valuemask,
344			      _Xconst XRenderPictureAttributes  *attributes)
345
346Change values in picture to those specified by valuemask and attributes.
347
348
349	void
350	XRenderSetPictureClipRectangles (Display	    *dpy,
351					 Picture	    picture,
352					 int		    xOrigin,
353					 int		    yOrigin,
354					 _Xconst XRectangle *rects,
355					 int		    n)
356
357Sets the clip mask in picture to the union of rects offset by
358xOrigin/yOrigin.
359
360	void
361	XRenderSetPictureClipRegion (Display	    *dpy,
362				     Picture	    picture,
363				     Region	    r)
364
365Sets the clip mask in picture to r.
366
367	void
368	XRenderSetPictureTransform (Display	    *dpy,
369				    Picture	    picture,
370				    XTransform	    *transform)
371
372Sets the projective transformation matrix of picture to transform.
373
374	void
375	XRenderFreePicture (Display                   *dpy,
376			    Picture                   picture)
377
378Instructs the server to free picture.
379
3805 GlyphSet functions
381
382	GlyphSet
383	XRenderCreateGlyphSet (Display *dpy, _Xconst XRenderPictFormat *format)
384
385Creates a glyphset, every glyph in the set will use PictFormat format.
386
387	GlyphSet
388	XRenderReferenceGlyphSet (Display *dpy, GlyphSet existing)
389
390Creates a new GlyphSet ID which references an existing GlyphSet.  The
391two IDs refer to the same object so that changes using one ID will be
392visible through the other ID.  This is designed to allow multiple clients to
393share the same GlyphSet so that it doesn't get destroyed when the first
394client exits.
395
396	void
397	XRenderFreeGlyphSet (Display *dpy, GlyphSet glyphset)
398
399Frees the glyphset ID.  If no other GlyphSet IDs refer to the underlying
400GlyphSet, it will be destroyed.
401
402	void
403	XRenderAddGlyphs (Display		*dpy,
404			  GlyphSet		glyphset,
405			  _Xconst Glyph		*gids,
406			  _Xconst XGlyphInfo	*glyphs,
407			  int			nglyphs,
408			  _Xconst char		*images,
409			  int			nbyte_images)
410
411Add glyphs to glyphset.  The images are packed together in Z-pixmap format
412according to the depth of the PictFormat used in creating glyphset.
413
414	void
415	XRenderFreeGlyphs (Display	    *dpy,
416			   GlyphSet	    glyphset,
417			   _Xconst Glyph    *gids,
418			   int		    nglyphs)
419
420Free some glyphs from glyphset.
421
4226 Glyph Drawing Routines
423
424Xrender provides two parallel APIs for glyph rendering, a simple API which
425accepts a single string similar to XDrawString and a more complex API which
426accepts an array of XGlyphElt{8,16,32} structures, each of which includes a
427glyphset, string and x/y offsets which parallel the XDrawText API.  Xrender
428also provides glyphs in three sizes, 8 16 and 32 bits.  The simple API is
429just a convenience for the user as both forms generate the same underlying
430Render protocol.
431
4326.1 Simple single-string glyph drawing functions
433
434These are identical except for the format of the glyph ids.
435
436	void
437	XRenderCompositeString8 (Display		    *dpy,
438				 int			    op,
439				 Picture		    src,
440				 Picture		    dst,
441				 _Xconst XRenderPictFormat  *maskFormat,
442				 GlyphSet		    glyphset,
443				 int			    xSrc,
444				 int			    ySrc,
445				 int			    xDst,
446				 int			    yDst,
447				 _Xconst char		    *string,
448				 int			    nchar)
449
450	void
451	XRenderCompositeString16 (Display		    *dpy,
452				  int			    op,
453				  Picture		    src,
454				  Picture		    dst,
455				  _Xconst XRenderPictFormat *maskFormat,
456				  GlyphSet		    glyphset,
457				  int			    xSrc,
458				  int			    ySrc,
459				  int			    xDst,
460				  int			    yDst,
461				  _Xconst unsigned short    *string,
462				  int			    nchar)
463
464	void
465	XRenderCompositeString32 (Display		    *dpy,
466				  int			    op,
467				  Picture		    src,
468				  Picture		    dst,
469				  _Xconst XRenderPictFormat *maskFormat,
470				  GlyphSet		    glyphset,
471				  int			    xSrc,
472				  int			    ySrc,
473				  int			    xDst,
474				  int			    yDst,
475				  _Xconst unsigned int	    *string,
476				  int			    nchar)
477
4786.2 Complete glyph drawing functions
479
480As with the simple functions above, these differ only in the type of the
481underlying glyph id storage type.
482
483	void
484	XRenderCompositeText8 (Display			    *dpy,
485			       int			    op,
486			       Picture			    src,
487			       Picture			    dst,
488			       _Xconst XRenderPictFormat    *maskFormat,
489			       int			    xSrc,
490			       int			    ySrc,
491			       int			    xDst,
492			       int			    yDst,
493			       _Xconst XGlyphElt8	    *elts,
494			       int			    nelt)
495
496	void
497	XRenderCompositeText16 (Display			    *dpy,
498				int			    op,
499				Picture			    src,
500				Picture			    dst,
501				_Xconst XRenderPictFormat   *maskFormat,
502				int			    xSrc,
503				int			    ySrc,
504				int			    xDst,
505				int			    yDst,
506				_Xconst XGlyphElt16	    *elts,
507				int			    nelt)
508
509	void
510	XRenderCompositeText32 (Display			    *dpy,
511				int			    op,
512				Picture			    src,
513				Picture			    dst,
514				_Xconst XRenderPictFormat   *maskFormat,
515				int			    xSrc,
516				int			    ySrc,
517				int			    xDst,
518				int			    yDst,
519				_Xconst XGlyphElt32	    *elts,
520				int			    nelt)
521
5227 Basic Graphics Functions
523
524These are the simplest graphics functions upon which the other functions are
525conceptually built.
526
5277.1 Composite
528
529XRenderComposite exposes the RenderComposite protocol request directly.
530If a format with alpha is used, make sure it is premultiplied into the
531color channels.
532
533	void
534	XRenderComposite (Display   *dpy,
535			  int	    op,
536			  Picture   src,
537			  Picture   mask,
538			  Picture   dst,
539			  int	    src_x,
540			  int	    src_y,
541			  int	    mask_x,
542			  int	    mask_y,
543			  int	    dst_x,
544			  int	    dst_y,
545			  unsigned int	width,
546			  unsigned int	height)
547
548
5497.2 Rectangles
550
551These functions composite rectangles of the specified color, they differ
552only in that XRenderFillRectangles draws more than one at a time.
553
554	void
555	XRenderFillRectangle (Display		    *dpy,
556			      int		    op,
557			      Picture		    dst,
558			      _Xconst XRenderColor  *color,
559			      int		    x,
560			      int		    y,
561			      unsigned int	    width,
562			      unsigned int	    height)
563
564	void
565	XRenderFillRectangles (Display		    *dpy,
566			       int		    op,
567			       Picture		    dst,
568			       _Xconst XRenderColor *color,
569			       _Xconst XRectangle   *rectangles,
570			       int		    n_rects)
571
5728 Geometric Objects
573
574All geometric drawing with Render is performed with sequences of trapezoids
575or triangles; the client is responsible for breaking more complex figures
576into these simple shapes.
577
5788.1 Trapezoids
579
580	void
581	XRenderCompositeTrapezoids (Display		*dpy,
582				    int			op,
583				    Picture		src,
584				    Picture		dst,
585				    _Xconst XRenderPictFormat	*maskFormat,
586				    int			xSrc,
587				    int			ySrc,
588				    _Xconst XTrapezoid	*traps,
589				    int			ntrap)
590
591XRenderCompositeTrapezoids builds RenderTrapezoids requests to composite the
592specified list of trapezoids to dst.  XRenderCompositeTrapezoids will split
593the list of trapezoids to build requests no larger than the maximum request
594size supported by the server.  This can create rendering artifacts as the
595precompositing done by RenderTrapezoids when a maskFormat is specified
596cannot span multiple requests.
597
5988.2 Triangles
599
600Render provides three different ways of encoding triangles on the wire,
601Xrender exposes those with three separate triangle drawing routines.  As
602with trapezoids above, Xrender will split the arguments to fit requests into
603the servers limits, but this may cause rendering artifacts.
604