aboutsummaryrefslogtreecommitdiff
path: root/libXrender/doc/libXrender.txt
blob: 27cc75d72cb6b7f5caaf2def61cf9793c3c9dc92 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
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 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.