mirror of OpenBSD xenocara tree
github.com/openbsd/xenocara
openbsd
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.