libXrender.txt revision 6fae4e5d 
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.
88
89	typedef struct {
90	    unsigned short   red;
91	    unsigned short   green;
92	    unsigned short   blue;
93	    unsigned short   alpha;
94	} XRenderColor;
95
962.5 Glyph Types
97
98Glyphs are stored in the server, so these definitions are passed from the
99client to the library and on to the server as glyphs are rasterized and
100transmitted over the wire.
101
102	typedef struct _XGlyphInfo {
103	    unsigned short  width;
104	    unsigned short  height;
105	    short	    x;
106	    short	    y;
107	    short	    xOff;
108	    short	    yOff;
109	} XGlyphInfo;
110
1112.6 Glyph Rendering types
112
113Glyph rendering can either take a single string of glyph indices or an array
114of one of the following structures.
115
116	typedef struct _XGlyphElt8 {
117	    GlyphSet		    glyphset;
118	    _Xconst char	    *chars;
119	    int			    nchars;
120	    int			    xOff;
121	    int			    yOff;
122	} XGlyphElt8;
123
124	typedef struct _XGlyphElt16 {
125	    GlyphSet		    glyphset;
126	    _Xconst unsigned short  *chars;
127	    int			    nchars;
128	    int			    xOff;
129	    int			    yOff;
130	} XGlyphElt16;
131
132	typedef struct _XGlyphElt32 {
133	    GlyphSet		    glyphset;
134	    _Xconst unsigned int    *chars;
135	    int			    nchars;
136	    int			    xOff;
137	    int			    yOff;
138	} XGlyphElt32;
139
1402.7 Geometric Types
141
142Geometric operations directly expose the available protocol datatypes
143
144	typedef struct _XPointFixed {
145	    XFixed  x, y;
146	} XPointFixed;
147
148	typedef struct _XLineFixed {
149	    XPointFixed	p1, p2;
150	} XLineFixed;
151
152	typedef struct _XTriangle {
153	    XPointFixed	p1, p2, p3;
154	} XTriangle;
155
156	typedef struct _XTrapezoid {
157	    XFixed  top, bottom;
158	    XLineFixed	left, right;
159	} XTrapezoid;
160
161	typedef struct _XTransform {
162	    XFixed  matrix[3][3];
163	} XTransform;
164
1652.8 Transformation Filters
166
167All of the filters are named simultaneously; Xrender provides no convenience
168functions for dealing with them.
169
170	typedef struct _XFilters {
171	    int	    nfilter;
172	    char    **filter;
173	    int	    nalias;
174	    short   *alias;
175	} XFilters;
176
1772.9 Index type PictFormat colors
178
179PictFormats of Index type advertise which colors will be used for drawing
180through this type.
181
182	typedef struct _XIndexValue {
183	    unsigned long    pixel;
184	    unsigned short   red, green, blue, alpha;
185	} XIndexValue;
186
187
1883 Application Startup Functions
189
1903.1 Initialization functions
191
192	Bool XRenderQueryExtension (Display *dpy,
193			            int     *event_basep,
194				    int     *error_basep)
195
196This function returns True if the Render extension is available on dpy.
197event_basep and error_basep will be filled in with the first event and error
198numbers used by the extension (note that Render currently uses no events).
199
200	Status XRenderQueryVersion (Display *dpy,
201				    int     *major_versionp,
202				    int     *minor_versionp)
203
204XRenderQueryVersion returns zero if the Render extension is not present or
205some error occurred while attempting to discover the current Render version
206number.  Otherwise, XRenderQueryVersion returns 1 and stores the version
207number returned by the server in *major_versionp and *minor_versionp, which
208will be less than or equal to the library version numbers RENDER_MAJOR and
209RENDER_MINOR.
210
211	Status XRenderQueryFormats (Display *dpy)
212
213XRenderQueryFormats returns 1 if it successfully fetches the available
214PictFormat information from the X server, 0 otherwise.  Applications needn't
215invoke this function directly (hmm, perhaps it should be removed from the
216external interfaces then).
217
2183.2 Subpixel Order
219
220	int XRenderQuerySubpixelOrder (Display *dpy, int screen)
221
222	Bool XRenderSetSubpixelOrder (Display *dpy, int screen, int subpixel)
223
224Applications interested in the geometry of the elements making up a single
225pixel on the screen should use XRenderQuerySubpixelOrder and not cache the
226return value.  XRenderSetSubpixelOrder is used by the XRandR library to
227update the value stored by Xrender when the subpixel order changes as a
228result of screen reconfiguration.
229
2303.3 PictFormat matching
231
232Xrender provides these APIs to help locate appropriate PictFormats; they are
233intended to work much like the Visual matching APIs in Xlib.  The
234application provides a specification including the necessary PictFormat
235characteristics and Xrender returns a matching XRenderPictFormat structure
236which describes the PictFormat.
237
238	XRenderPictFormat *
239	XRenderFindFormat (Display			*dpy,
240			   unsigned long		mask,
241			   _Xconst XRenderPictFormat	*templ,
242			   int				count)
243
244	#define PictFormatID	    (1 << 0)
245	#define PictFormatType	    (1 << 1)
246	#define PictFormatDepth	    (1 << 2)
247	#define PictFormatRed	    (1 << 3)
248	#define PictFormatRedMask   (1 << 4)
249	#define PictFormatGreen	    (1 << 5)
250	#define PictFormatGreenMask (1 << 6)
251	#define PictFormatBlue	    (1 << 7)
252	#define PictFormatBlueMask  (1 << 8)
253	#define PictFormatAlpha	    (1 << 9)
254	#define PictFormatAlphaMask (1 << 10)
255	#define PictFormatColormap  (1 << 11)
256
257XRenderFindFormat locates a PictFormat matching the characteristics provided
258in the templ.  Only elements whose associated bit in mask are compared.
259
260	XRenderPictFormat *
261	XRenderFindVisualFormat (Display *dpy, _Xconst Visual *visual)
262
263Finds the PictFormat suitable for use with the specified visual.
264
265	XRenderPictFormat *
266	XRenderFindStandardFormat (Display		*dpy,
267				   int			format)
268
269	#define PictStandardARGB32  0
270	#define PictStandardRGB24   1
271	#define PictStandardA8	    2
272	#define PictStandardA4	    3
273	#define PictStandardA1	    4
274	#define PictStandardNUM	    5
275
276As a convenience, this function locates PictFormats that correspond to
277commonly used formats.
278
279	ARGB32		depth 32, bits 31-24 A, 23-16 R, 15-8 G, 7-0 B
280	RGB24		depth 24, bits 23-16 R, 15-8 G, 7-0 B
281	A8		depth 8, bits 7-0 A
282	A4		depth 4, bits 3-0 A
283	A1		depth 1, bits 0 A
284
285Any server supporting Render must have a PictFormat corresponding to each of
286these standard formats.
287
2883.4 Index type PictFormat color values
289
290	XIndexValue *
291	XRenderQueryPictIndexValues(Display			*dpy,
292				    _Xconst XRenderPictFormat	*format,
293				    int				*num)
294
295If format refers to an Index type PictFormat, XRenderQueryPictIndexValues
296returns the set of pixel values and their associated colors used when
297drawing to Pictures created with that format.  Otherwise,
298XRenderQueryPictIndexValues generates a BadMatch error.
299
3003.5 Querying available filters
301
302	XFilters *
303	XRenderQueryFilters (Display *dpy, Drawable drawable);
304
305Filters are used with non-identity transformation matrices, this function
306returns a datastructure identifying the available filters on display that
307can be associated with pictures for the screen associated with drawable.
308
309Free this structure with XFree.
310
3114 Picture Functions
312
313	Picture
314	XRenderCreatePicture (Display				*dpy,
315			      Drawable				drawable,
316			      _Xconst XRenderPictFormat		*format,
317			      unsigned long			valuemask,
318			      _Xconst XRenderPictureAttributes	*attributes)
319
320	#define CPRepeat			    (1 << 0)
321	#define CPAlphaMap			    (1 << 1)
322	#define CPAlphaXOrigin			    (1 << 2)
323	#define CPAlphaYOrigin			    (1 << 3)
324	#define CPClipXOrigin			    (1 << 4)
325	#define CPClipYOrigin			    (1 << 5)
326	#define CPClipMask			    (1 << 6)
327	#define CPGraphicsExposure		    (1 << 7)
328	#define CPSubwindowMode			    (1 << 8)
329	#define CPPolyEdge			    (1 << 9)
330	#define CPPolyMode			    (1 << 10)
331	#define CPDither			    (1 << 11)
332	#define CPComponentAlpha		    (1 << 12)
333	#define CPLastBit			    12
334
335Creates a picture for drawable in the specified format.  Any values
336specified in 'attributes' and 'valuemask' are used in place of the default
337values.
338
339	void
340	XRenderChangePicture (Display				*dpy,
341			      Picture				picture,
342			      unsigned long			valuemask,
343			      _Xconst XRenderPictureAttributes  *attributes)
344
345Change values in picture to those specified by valuemask and attributes.
346
347
348	void
349	XRenderSetPictureClipRectangles (Display	    *dpy,
350					 Picture	    picture,
351					 int		    xOrigin,
352					 int		    yOrigin,
353					 _Xconst XRectangle *rects,
354					 int		    n)
355
356Sets the clip mask in picture to the union of rects offset by
357xOrigin/yOrigin.
358
359	void
360	XRenderSetPictureClipRegion (Display	    *dpy,
361				     Picture	    picture,
362				     Region	    r)
363
364Sets the clip mask in picture to r.
365
366	void
367	XRenderSetPictureTransform (Display	    *dpy,
368				    Picture	    picture,
369				    XTransform	    *transform)
370
371Sets the projective transformation matrix of picture to transform.
372
373	void
374	XRenderFreePicture (Display                   *dpy,
375			    Picture                   picture)
376
377Instructs the server to free picture.
378
3795 GlyphSet functions
380
381	GlyphSet
382	XRenderCreateGlyphSet (Display *dpy, _Xconst XRenderPictFormat *format)
383
384Creates a glyphset, every glyph in the set will use PictFormat format.
385
386	GlyphSet
387	XRenderReferenceGlyphSet (Display *dpy, GlyphSet existing)
388
389Creates a new GlyphSet ID which references an existing GlyphSet.  The
390two IDs refer to the same object so that changes using one ID will be
391visible through the other ID.  This is designed to allow multiple clients to
392share the same GlyphSet so that it doesn't get destroyed when the first
393client exits.
394
395	void
396	XRenderFreeGlyphSet (Display *dpy, GlyphSet glyphset)
397
398Frees the glyphset ID.  If no other GlyphSet IDs refer to the underlying
399GlyphSet, it will be destroyed.
400
401	void
402	XRenderAddGlyphs (Display		*dpy,
403			  GlyphSet		glyphset,
404			  _Xconst Glyph		*gids,
405			  _Xconst XGlyphInfo	*glyphs,
406			  int			nglyphs,
407			  _Xconst char		*images,
408			  int			nbyte_images)
409
410Add glyphs to glyphset.  The images are packed together in Z-pixmap format
411according to the depth of the PictFormat used in creating glyphset.
412
413	void
414	XRenderFreeGlyphs (Display	    *dpy,
415			   GlyphSet	    glyphset,
416			   _Xconst Glyph    *gids,
417			   int		    nglyphs)
418
419Free some glyphs from glyphset.
420
4216 Glyph Drawing Routines
422
423Xrender provides two parallel APIs for glyph rendering, a simple API which
424accepts a single string similar to XDrawString and a more complex API which
425accepts an array of XGlyphElt{8,16,32} structures, each of which includes a
426glyphset, string and x/y offsets which parallel the XDrawText API.  Xrender
427also provides glyphs in three sizes, 8 16 and 32 bits.  The simple API is
428just a convenience for the user as both forms generate the same underlying
429Render protocol.
430
4316.1 Simple single-string glyph drawing functions
432
433These are identical except for the format of the glyph ids.
434
435	void
436	XRenderCompositeString8 (Display		    *dpy,
437				 int			    op,
438				 Picture		    src,
439				 Picture		    dst,
440				 _Xconst XRenderPictFormat  *maskFormat,
441				 GlyphSet		    glyphset,
442				 int			    xSrc,
443				 int			    ySrc,
444				 int			    xDst,
445				 int			    yDst,
446				 _Xconst char		    *string,
447				 int			    nchar)
448
449	void
450	XRenderCompositeString16 (Display		    *dpy,
451				  int			    op,
452				  Picture		    src,
453				  Picture		    dst,
454				  _Xconst XRenderPictFormat *maskFormat,
455				  GlyphSet		    glyphset,
456				  int			    xSrc,
457				  int			    ySrc,
458				  int			    xDst,
459				  int			    yDst,
460				  _Xconst unsigned short    *string,
461				  int			    nchar)
462
463	void
464	XRenderCompositeString32 (Display		    *dpy,
465				  int			    op,
466				  Picture		    src,
467				  Picture		    dst,
468				  _Xconst XRenderPictFormat *maskFormat,
469				  GlyphSet		    glyphset,
470				  int			    xSrc,
471				  int			    ySrc,
472				  int			    xDst,
473				  int			    yDst,
474				  _Xconst unsigned int	    *string,
475				  int			    nchar)
476
4776.2 Complete glyph drawing functions
478
479As with the simple functions above, these differ only in the type of the
480underlying glyph id storage type.
481
482	void
483	XRenderCompositeText8 (Display			    *dpy,
484			       int			    op,
485			       Picture			    src,
486			       Picture			    dst,
487			       _Xconst XRenderPictFormat    *maskFormat,
488			       int			    xSrc,
489			       int			    ySrc,
490			       int			    xDst,
491			       int			    yDst,
492			       _Xconst XGlyphElt8	    *elts,
493			       int			    nelt)
494
495	void
496	XRenderCompositeText16 (Display			    *dpy,
497				int			    op,
498				Picture			    src,
499				Picture			    dst,
500				_Xconst XRenderPictFormat   *maskFormat,
501				int			    xSrc,
502				int			    ySrc,
503				int			    xDst,
504				int			    yDst,
505				_Xconst XGlyphElt16	    *elts,
506				int			    nelt)
507
508	void
509	XRenderCompositeText32 (Display			    *dpy,
510				int			    op,
511				Picture			    src,
512				Picture			    dst,
513				_Xconst XRenderPictFormat   *maskFormat,
514				int			    xSrc,
515				int			    ySrc,
516				int			    xDst,
517				int			    yDst,
518				_Xconst XGlyphElt32	    *elts,
519				int			    nelt)
520
5217 Basic Graphics Functions
522
523These are the simplest graphics functions upon which the other functions are
524conceptually built.
525
5267.1 Composite
527
528XRenderComposite exposes the RenderComposite protocol request directly.
529
530	void
531	XRenderComposite (Display   *dpy,
532			  int	    op,
533			  Picture   src,
534			  Picture   mask,
535			  Picture   dst,
536			  int	    src_x,
537			  int	    src_y,
538			  int	    mask_x,
539			  int	    mask_y,
540			  int	    dst_x,
541			  int	    dst_y,
542			  unsigned int	width,
543			  unsigned int	height)
544
545
5467.2 Rectangles
547
548These functions composite rectangles of the specified color, they differ
549only in that XRenderFillRectangles draws more than one at a time.
550
551	void
552	XRenderFillRectangle (Display		    *dpy,
553			      int		    op,
554			      Picture		    dst,
555			      _Xconst XRenderColor  *color,
556			      int		    x,
557			      int		    y,
558			      unsigned int	    width,
559			      unsigned int	    height)
560
561	void
562	XRenderFillRectangles (Display		    *dpy,
563			       int		    op,
564			       Picture		    dst,
565			       _Xconst XRenderColor *color,
566			       _Xconst XRectangle   *rectangles,
567			       int		    n_rects)
568
5698 Geometric Objects
570
571All geometric drawing with Render is performed with sequences of trapezoids
572or triangles; the client is responsible for breaking more complex figures
573into these simple shapes.
574
5758.1 Trapezoids
576
577	void
578	XRenderCompositeTrapezoids (Display		*dpy,
579				    int			op,
580				    Picture		src,
581				    Picture		dst,
582				    _Xconst XRenderPictFormat	*maskFormat,
583				    int			xSrc,
584				    int			ySrc,
585				    _Xconst XTrapezoid	*traps,
586				    int			ntrap)
587
588XRenderCompositeTrapezoids builds RenderTrapezoids requests to composite the
589specified list of trapezoids to dst.  XRenderCompositeTrapezoids will split
590the list of trapezoids to build requests no larger than the maximum request
591size supported by the server.  This can create rendering artifacts as the
592precompositing done by RenderTrapezoids when a maskFormat is specified
593cannot span multiple requests.
594
5958.2 Triangles
596
597Render provides three different ways of encoding triangles on the wire,
598Xrender exposes those with three separate triangle drawing routines.  As
599with trapezoids above, Xrender will split the arguments to fit requests into
600the servers limits, but this may cause rendering artifacts.
601