Commit | Line | Data |
---|---|---|
a09e091a JB |
1 | /* |
2 | * | |
3 | * Copyright (C) 2000 Keith Packard | |
4 | * 2004 Eric Anholt | |
5 | * 2005 Zack Rusin | |
6 | * | |
7 | * Permission to use, copy, modify, distribute, and sell this software and its | |
8 | * documentation for any purpose is hereby granted without fee, provided that | |
9 | * the above copyright notice appear in all copies and that both that | |
10 | * copyright notice and this permission notice appear in supporting | |
11 | * documentation, and that the name of copyright holders not be used in | |
12 | * advertising or publicity pertaining to distribution of the software without | |
13 | * specific, written prior permission. Copyright holders make no | |
14 | * representations about the suitability of this software for any purpose. It | |
15 | * is provided "as is" without express or implied warranty. | |
16 | * | |
17 | * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS | |
18 | * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND | |
19 | * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY | |
20 | * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
21 | * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN | |
22 | * AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING | |
23 | * OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS | |
24 | * SOFTWARE. | |
25 | */ | |
26 | ||
27 | /** @file | |
28 | * This is the header containing the public API of EXA for exa drivers. | |
29 | */ | |
30 | ||
31 | #ifndef EXA_H | |
32 | #define EXA_H | |
33 | ||
34 | #include "scrnintstr.h" | |
35 | #include "pixmapstr.h" | |
36 | #include "windowstr.h" | |
37 | #include "gcstruct.h" | |
38 | #include "picturestr.h" | |
39 | #include "fb.h" | |
40 | ||
41 | #define EXA_VERSION_MAJOR 2 | |
42 | #define EXA_VERSION_MINOR 6 | |
43 | #define EXA_VERSION_RELEASE 0 | |
44 | ||
45 | typedef struct _ExaOffscreenArea ExaOffscreenArea; | |
46 | ||
47 | typedef void (*ExaOffscreenSaveProc) (ScreenPtr pScreen, | |
48 | ExaOffscreenArea * area); | |
49 | ||
50 | typedef enum _ExaOffscreenState { | |
51 | ExaOffscreenAvail, | |
52 | ExaOffscreenRemovable, | |
53 | ExaOffscreenLocked | |
54 | } ExaOffscreenState; | |
55 | ||
56 | struct _ExaOffscreenArea { | |
57 | int base_offset; /* allocation base */ | |
58 | int offset; /* aligned offset */ | |
59 | int size; /* total allocation size */ | |
60 | unsigned last_use; | |
61 | pointer privData; | |
62 | ||
63 | ExaOffscreenSaveProc save; | |
64 | ||
65 | ExaOffscreenState state; | |
66 | ||
67 | ExaOffscreenArea *next; | |
68 | ||
69 | unsigned eviction_cost; | |
70 | ||
71 | ExaOffscreenArea *prev; /* Double-linked list for defragmentation */ | |
72 | int align; /* required alignment */ | |
73 | }; | |
74 | ||
75 | /** | |
76 | * The ExaDriver structure is allocated through exaDriverAlloc(), and then | |
77 | * fllled in by drivers. | |
78 | */ | |
79 | typedef struct _ExaDriver { | |
80 | /** | |
81 | * exa_major and exa_minor should be set by the driver to the version of | |
82 | * EXA which the driver was compiled for (or configures itself at runtime | |
83 | * to support). This allows EXA to extend the structure for new features | |
84 | * without breaking ABI for drivers compiled against older versions. | |
85 | */ | |
86 | int exa_major, exa_minor; | |
87 | ||
88 | /** | |
89 | * memoryBase is the address of the beginning of framebuffer memory. | |
90 | * The visible screen should be within memoryBase to memoryBase + | |
91 | * memorySize. | |
92 | */ | |
93 | CARD8 *memoryBase; | |
94 | ||
95 | /** | |
96 | * offScreenBase is the offset from memoryBase of the beginning of the area | |
97 | * to be managed by EXA's linear offscreen memory manager. | |
98 | * | |
99 | * In XFree86 DDX drivers, this is probably: | |
100 | * (pScrn->displayWidth * cpp * pScrn->virtualY) | |
101 | */ | |
102 | unsigned long offScreenBase; | |
103 | ||
104 | /** | |
105 | * memorySize is the length (in bytes) of framebuffer memory beginning | |
106 | * from memoryBase. | |
107 | * | |
108 | * The offscreen memory manager will manage the area beginning at | |
109 | * (memoryBase + offScreenBase), with a length of (memorySize - | |
110 | * offScreenBase) | |
111 | * | |
112 | * In XFree86 DDX drivers, this is probably (pScrn->videoRam * 1024) | |
113 | */ | |
114 | unsigned long memorySize; | |
115 | ||
116 | /** | |
117 | * pixmapOffsetAlign is the byte alignment necessary for pixmap offsets | |
118 | * within framebuffer. | |
119 | * | |
120 | * Hardware typically has a required alignment of offsets, which may or may | |
121 | * not be a power of two. EXA will ensure that pixmaps managed by the | |
122 | * offscreen memory manager meet this alignment requirement. | |
123 | */ | |
124 | int pixmapOffsetAlign; | |
125 | ||
126 | /** | |
127 | * pixmapPitchAlign is the byte alignment necessary for pixmap pitches | |
128 | * within the framebuffer. | |
129 | * | |
130 | * Hardware typically has a required alignment of pitches for acceleration. | |
131 | * For 3D hardware, Composite acceleration often requires that source and | |
132 | * mask pixmaps (textures) have a power-of-two pitch, which can be demanded | |
133 | * using EXA_OFFSCREEN_ALIGN_POT. These pitch requirements only apply to | |
134 | * pixmaps managed by the offscreen memory manager. Thus, it is up to the | |
135 | * driver to ensure that the visible screen has an appropriate pitch for | |
136 | * acceleration. | |
137 | */ | |
138 | int pixmapPitchAlign; | |
139 | ||
140 | /** | |
141 | * The flags field is bitfield of boolean values controlling EXA's behavior. | |
142 | * | |
143 | * The flags in clude EXA_OFFSCREEN_PIXMAPS, EXA_OFFSCREEN_ALIGN_POT, and | |
144 | * EXA_TWO_BITBLT_DIRECTIONS. | |
145 | */ | |
146 | int flags; | |
147 | ||
148 | /** @{ */ | |
149 | /** | |
150 | * maxX controls the X coordinate limitation for rendering from the card. | |
151 | * The driver should never receive a request for rendering beyond maxX | |
152 | * in the X direction from the origin of a pixmap. | |
153 | */ | |
154 | int maxX; | |
155 | ||
156 | /** | |
157 | * maxY controls the Y coordinate limitation for rendering from the card. | |
158 | * The driver should never receive a request for rendering beyond maxY | |
159 | * in the Y direction from the origin of a pixmap. | |
160 | */ | |
161 | int maxY; | |
162 | /** @} */ | |
163 | ||
164 | /* private */ | |
165 | ExaOffscreenArea *offScreenAreas; | |
166 | Bool needsSync; | |
167 | int lastMarker; | |
168 | ||
169 | /** @name Solid | |
170 | * @{ | |
171 | */ | |
172 | /** | |
173 | * PrepareSolid() sets up the driver for doing a solid fill. | |
174 | * @param pPixmap Destination pixmap | |
175 | * @param alu raster operation | |
176 | * @param planemask write mask for the fill | |
177 | * @param fg "foreground" color for the fill | |
178 | * | |
179 | * This call should set up the driver for doing a series of solid fills | |
180 | * through the Solid() call. The alu raster op is one of the GX* | |
181 | * graphics functions listed in X.h, and typically maps to a similar | |
182 | * single-byte "ROP" setting in all hardware. The planemask controls | |
183 | * which bits of the destination should be affected, and will only represent | |
184 | * the bits up to the depth of pPixmap. The fg is the pixel value of the | |
185 | * foreground color referred to in ROP descriptions. | |
186 | * | |
187 | * Note that many drivers will need to store some of the data in the driver | |
188 | * private record, for sending to the hardware with each drawing command. | |
189 | * | |
190 | * The PrepareSolid() call is required of all drivers, but it may fail for any | |
191 | * reason. Failure results in a fallback to software rendering. | |
192 | */ | |
193 | Bool (*PrepareSolid) (PixmapPtr pPixmap, | |
194 | int alu, Pixel planemask, Pixel fg); | |
195 | ||
196 | /** | |
197 | * Solid() performs a solid fill set up in the last PrepareSolid() call. | |
198 | * | |
199 | * @param pPixmap destination pixmap | |
200 | * @param x1 left coordinate | |
201 | * @param y1 top coordinate | |
202 | * @param x2 right coordinate | |
203 | * @param y2 bottom coordinate | |
204 | * | |
205 | * Performs the fill set up by the last PrepareSolid() call, covering the | |
206 | * area from (x1,y1) to (x2,y2) in pPixmap. Note that the coordinates are | |
207 | * in the coordinate space of the destination pixmap, so the driver will | |
208 | * need to set up the hardware's offset and pitch for the destination | |
209 | * coordinates according to the pixmap's offset and pitch within | |
210 | * framebuffer. This likely means using exaGetPixmapOffset() and | |
211 | * exaGetPixmapPitch(). | |
212 | * | |
213 | * This call is required if PrepareSolid() ever succeeds. | |
214 | */ | |
215 | void (*Solid) (PixmapPtr pPixmap, int x1, int y1, int x2, int y2); | |
216 | ||
217 | /** | |
218 | * DoneSolid() finishes a set of solid fills. | |
219 | * | |
220 | * @param pPixmap destination pixmap. | |
221 | * | |
222 | * The DoneSolid() call is called at the end of a series of consecutive | |
223 | * Solid() calls following a successful PrepareSolid(). This allows drivers | |
224 | * to finish up emitting drawing commands that were buffered, or clean up | |
225 | * state from PrepareSolid(). | |
226 | * | |
227 | * This call is required if PrepareSolid() ever succeeds. | |
228 | */ | |
229 | void (*DoneSolid) (PixmapPtr pPixmap); | |
230 | /** @} */ | |
231 | ||
232 | /** @name Copy | |
233 | * @{ | |
234 | */ | |
235 | /** | |
236 | * PrepareCopy() sets up the driver for doing a copy within video | |
237 | * memory. | |
238 | * | |
239 | * @param pSrcPixmap source pixmap | |
240 | * @param pDstPixmap destination pixmap | |
241 | * @param dx X copy direction | |
242 | * @param dy Y copy direction | |
243 | * @param alu raster operation | |
244 | * @param planemask write mask for the fill | |
245 | * | |
246 | * This call should set up the driver for doing a series of copies from the | |
247 | * the pSrcPixmap to the pDstPixmap. The dx flag will be positive if the | |
248 | * hardware should do the copy from the left to the right, and dy will be | |
249 | * positive if the copy should be done from the top to the bottom. This | |
250 | * is to deal with self-overlapping copies when pSrcPixmap == pDstPixmap. | |
251 | * If your hardware can only support blits that are (left to right, top to | |
252 | * bottom) or (right to left, bottom to top), then you should set | |
253 | * #EXA_TWO_BITBLT_DIRECTIONS, and EXA will break down Copy operations to | |
254 | * ones that meet those requirements. The alu raster op is one of the GX* | |
255 | * graphics functions listed in X.h, and typically maps to a similar | |
256 | * single-byte "ROP" setting in all hardware. The planemask controls which | |
257 | * bits of the destination should be affected, and will only represent the | |
258 | * bits up to the depth of pPixmap. | |
259 | * | |
260 | * Note that many drivers will need to store some of the data in the driver | |
261 | * private record, for sending to the hardware with each drawing command. | |
262 | * | |
263 | * The PrepareCopy() call is required of all drivers, but it may fail for any | |
264 | * reason. Failure results in a fallback to software rendering. | |
265 | */ | |
266 | Bool (*PrepareCopy) (PixmapPtr pSrcPixmap, | |
267 | PixmapPtr pDstPixmap, | |
268 | int dx, int dy, int alu, Pixel planemask); | |
269 | ||
270 | /** | |
271 | * Copy() performs a copy set up in the last PrepareCopy call. | |
272 | * | |
273 | * @param pDstPixmap destination pixmap | |
274 | * @param srcX source X coordinate | |
275 | * @param srcY source Y coordinate | |
276 | * @param dstX destination X coordinate | |
277 | * @param dstY destination Y coordinate | |
278 | * @param width width of the rectangle to be copied | |
279 | * @param height height of the rectangle to be copied. | |
280 | * | |
281 | * Performs the copy set up by the last PrepareCopy() call, copying the | |
282 | * rectangle from (srcX, srcY) to (srcX + width, srcY + width) in the source | |
283 | * pixmap to the same-sized rectangle at (dstX, dstY) in the destination | |
284 | * pixmap. Those rectangles may overlap in memory, if | |
285 | * pSrcPixmap == pDstPixmap. Note that this call does not receive the | |
286 | * pSrcPixmap as an argument -- if it's needed in this function, it should | |
287 | * be stored in the driver private during PrepareCopy(). As with Solid(), | |
288 | * the coordinates are in the coordinate space of each pixmap, so the driver | |
289 | * will need to set up source and destination pitches and offsets from those | |
290 | * pixmaps, probably using exaGetPixmapOffset() and exaGetPixmapPitch(). | |
291 | * | |
292 | * This call is required if PrepareCopy ever succeeds. | |
293 | */ | |
294 | void (*Copy) (PixmapPtr pDstPixmap, | |
295 | int srcX, | |
296 | int srcY, int dstX, int dstY, int width, int height); | |
297 | ||
298 | /** | |
299 | * DoneCopy() finishes a set of copies. | |
300 | * | |
301 | * @param pPixmap destination pixmap. | |
302 | * | |
303 | * The DoneCopy() call is called at the end of a series of consecutive | |
304 | * Copy() calls following a successful PrepareCopy(). This allows drivers | |
305 | * to finish up emitting drawing commands that were buffered, or clean up | |
306 | * state from PrepareCopy(). | |
307 | * | |
308 | * This call is required if PrepareCopy() ever succeeds. | |
309 | */ | |
310 | void (*DoneCopy) (PixmapPtr pDstPixmap); | |
311 | /** @} */ | |
312 | ||
313 | /** @name Composite | |
314 | * @{ | |
315 | */ | |
316 | /** | |
317 | * CheckComposite() checks to see if a composite operation could be | |
318 | * accelerated. | |
319 | * | |
320 | * @param op Render operation | |
321 | * @param pSrcPicture source Picture | |
322 | * @param pMaskPicture mask picture | |
323 | * @param pDstPicture destination Picture | |
324 | * | |
325 | * The CheckComposite() call checks if the driver could handle acceleration | |
326 | * of op with the given source, mask, and destination pictures. This allows | |
327 | * drivers to check source and destination formats, supported operations, | |
328 | * transformations, and component alpha state, and send operations it can't | |
329 | * support to software rendering early on. This avoids costly pixmap | |
330 | * migration to the wrong places when the driver can't accelerate | |
331 | * operations. Note that because migration hasn't happened, the driver | |
332 | * can't know during CheckComposite() what the offsets and pitches of the | |
333 | * pixmaps are going to be. | |
334 | * | |
335 | * See PrepareComposite() for more details on likely issues that drivers | |
336 | * will have in accelerating Composite operations. | |
337 | * | |
338 | * The CheckComposite() call is recommended if PrepareComposite() is | |
339 | * implemented, but is not required. | |
340 | */ | |
341 | Bool (*CheckComposite) (int op, | |
342 | PicturePtr pSrcPicture, | |
343 | PicturePtr pMaskPicture, PicturePtr pDstPicture); | |
344 | ||
345 | /** | |
346 | * PrepareComposite() sets up the driver for doing a Composite operation | |
347 | * described in the Render extension protocol spec. | |
348 | * | |
349 | * @param op Render operation | |
350 | * @param pSrcPicture source Picture | |
351 | * @param pMaskPicture mask picture | |
352 | * @param pDstPicture destination Picture | |
353 | * @param pSrc source pixmap | |
354 | * @param pMask mask pixmap | |
355 | * @param pDst destination pixmap | |
356 | * | |
357 | * This call should set up the driver for doing a series of Composite | |
358 | * operations, as described in the Render protocol spec, with the given | |
359 | * pSrcPicture, pMaskPicture, and pDstPicture. The pSrc, pMask, and | |
360 | * pDst are the pixmaps containing the pixel data, and should be used for | |
361 | * setting the offset and pitch used for the coordinate spaces for each of | |
362 | * the Pictures. | |
363 | * | |
364 | * Notes on interpreting Picture structures: | |
365 | * - The Picture structures will always have a valid pDrawable. | |
366 | * - The Picture structures will never have alphaMap set. | |
367 | * - The mask Picture (and therefore pMask) may be NULL, in which case the | |
368 | * operation is simply src OP dst instead of src IN mask OP dst, and | |
369 | * mask coordinates should be ignored. | |
370 | * - pMarkPicture may have componentAlpha set, which greatly changes | |
371 | * the behavior of the Composite operation. componentAlpha has no effect | |
372 | * when set on pSrcPicture or pDstPicture. | |
373 | * - The source and mask Pictures may have a transformation set | |
374 | * (Picture->transform != NULL), which means that the source coordinates | |
375 | * should be transformed by that transformation, resulting in scaling, | |
376 | * rotation, etc. The PictureTransformPoint() call can transform | |
377 | * coordinates for you. Transforms have no effect on Pictures when used | |
378 | * as a destination. | |
379 | * - The source and mask pictures may have a filter set. PictFilterNearest | |
380 | * and PictFilterBilinear are defined in the Render protocol, but others | |
381 | * may be encountered, and must be handled correctly (usually by | |
382 | * PrepareComposite failing, and falling back to software). Filters have | |
383 | * no effect on Pictures when used as a destination. | |
384 | * - The source and mask Pictures may have repeating set, which must be | |
385 | * respected. Many chipsets will be unable to support repeating on | |
386 | * pixmaps that have a width or height that is not a power of two. | |
387 | * | |
388 | * If your hardware can't support source pictures (textures) with | |
389 | * non-power-of-two pitches, you should set #EXA_OFFSCREEN_ALIGN_POT. | |
390 | * | |
391 | * Note that many drivers will need to store some of the data in the driver | |
392 | * private record, for sending to the hardware with each drawing command. | |
393 | * | |
394 | * The PrepareComposite() call is not required. However, it is highly | |
395 | * recommended for performance of antialiased font rendering and performance | |
396 | * of cairo applications. Failure results in a fallback to software | |
397 | * rendering. | |
398 | */ | |
399 | Bool (*PrepareComposite) (int op, | |
400 | PicturePtr pSrcPicture, | |
401 | PicturePtr pMaskPicture, | |
402 | PicturePtr pDstPicture, | |
403 | PixmapPtr pSrc, PixmapPtr pMask, PixmapPtr pDst); | |
404 | ||
405 | /** | |
406 | * Composite() performs a Composite operation set up in the last | |
407 | * PrepareComposite() call. | |
408 | * | |
409 | * @param pDstPixmap destination pixmap | |
410 | * @param srcX source X coordinate | |
411 | * @param srcY source Y coordinate | |
412 | * @param maskX source X coordinate | |
413 | * @param maskY source Y coordinate | |
414 | * @param dstX destination X coordinate | |
415 | * @param dstY destination Y coordinate | |
416 | * @param width destination rectangle width | |
417 | * @param height destination rectangle height | |
418 | * | |
419 | * Performs the Composite operation set up by the last PrepareComposite() | |
420 | * call, to the rectangle from (dstX, dstY) to (dstX + width, dstY + height) | |
421 | * in the destination Pixmap. Note that if a transformation was set on | |
422 | * the source or mask Pictures, the source rectangles may not be the same | |
423 | * size as the destination rectangles and filtering. Getting the coordinate | |
424 | * transformation right at the subpixel level can be tricky, and rendercheck | |
425 | * can test this for you. | |
426 | * | |
427 | * This call is required if PrepareComposite() ever succeeds. | |
428 | */ | |
429 | void (*Composite) (PixmapPtr pDst, | |
430 | int srcX, | |
431 | int srcY, | |
432 | int maskX, | |
433 | int maskY, int dstX, int dstY, int width, int height); | |
434 | ||
435 | /** | |
436 | * DoneComposite() finishes a set of Composite operations. | |
437 | * | |
438 | * @param pPixmap destination pixmap. | |
439 | * | |
440 | * The DoneComposite() call is called at the end of a series of consecutive | |
441 | * Composite() calls following a successful PrepareComposite(). This allows | |
442 | * drivers to finish up emitting drawing commands that were buffered, or | |
443 | * clean up state from PrepareComposite(). | |
444 | * | |
445 | * This call is required if PrepareComposite() ever succeeds. | |
446 | */ | |
447 | void (*DoneComposite) (PixmapPtr pDst); | |
448 | /** @} */ | |
449 | ||
450 | /** | |
451 | * UploadToScreen() loads a rectangle of data from src into pDst. | |
452 | * | |
453 | * @param pDst destination pixmap | |
454 | * @param x destination X coordinate. | |
455 | * @param y destination Y coordinate | |
456 | * @param width width of the rectangle to be copied | |
457 | * @param height height of the rectangle to be copied | |
458 | * @param src pointer to the beginning of the source data | |
459 | * @param src_pitch pitch (in bytes) of the lines of source data. | |
460 | * | |
461 | * UploadToScreen() copies data in system memory beginning at src (with | |
462 | * pitch src_pitch) into the destination pixmap from (x, y) to | |
463 | * (x + width, y + height). This is typically done with hostdata uploads, | |
464 | * where the CPU sets up a blit command on the hardware with instructions | |
465 | * that the blit data will be fed through some sort of aperture on the card. | |
466 | * | |
467 | * If UploadToScreen() is performed asynchronously, it is up to the driver | |
468 | * to call exaMarkSync(). This is in contrast to most other acceleration | |
469 | * calls in EXA. | |
470 | * | |
471 | * UploadToScreen() can aid in pixmap migration, but is most important for | |
472 | * the performance of exaGlyphs() (antialiased font drawing) by allowing | |
473 | * pipelining of data uploads, avoiding a sync of the card after each glyph. | |
474 | * | |
475 | * @return TRUE if the driver successfully uploaded the data. FALSE | |
476 | * indicates that EXA should fall back to doing the upload in software. | |
477 | * | |
478 | * UploadToScreen() is not required, but is recommended if Composite | |
479 | * acceleration is supported. | |
480 | */ | |
481 | Bool (*UploadToScreen) (PixmapPtr pDst, | |
482 | int x, | |
483 | int y, int w, int h, char *src, int src_pitch); | |
484 | ||
485 | /** | |
486 | * UploadToScratch() is no longer used and will be removed next time the EXA | |
487 | * major version needs to be bumped. | |
488 | */ | |
489 | Bool (*UploadToScratch) (PixmapPtr pSrc, PixmapPtr pDst); | |
490 | ||
491 | /** | |
492 | * DownloadFromScreen() loads a rectangle of data from pSrc into dst | |
493 | * | |
494 | * @param pSrc source pixmap | |
495 | * @param x source X coordinate. | |
496 | * @param y source Y coordinate | |
497 | * @param width width of the rectangle to be copied | |
498 | * @param height height of the rectangle to be copied | |
499 | * @param dst pointer to the beginning of the destination data | |
500 | * @param dst_pitch pitch (in bytes) of the lines of destination data. | |
501 | * | |
502 | * DownloadFromScreen() copies data from offscreen memory in pSrc from | |
503 | * (x, y) to (x + width, y + height), to system memory starting at | |
504 | * dst (with pitch dst_pitch). This would usually be done | |
505 | * using scatter-gather DMA, supported by a DRM call, or by blitting to AGP | |
506 | * and then synchronously reading from AGP. Because the implementation | |
507 | * might be synchronous, EXA leaves it up to the driver to call | |
508 | * exaMarkSync() if DownloadFromScreen() was asynchronous. This is in | |
509 | * contrast to most other acceleration calls in EXA. | |
510 | * | |
511 | * DownloadFromScreen() can aid in the largest bottleneck in pixmap | |
512 | * migration, which is the read from framebuffer when evicting pixmaps from | |
513 | * framebuffer memory. Thus, it is highly recommended, even though | |
514 | * implementations are typically complicated. | |
515 | * | |
516 | * @return TRUE if the driver successfully downloaded the data. FALSE | |
517 | * indicates that EXA should fall back to doing the download in software. | |
518 | * | |
519 | * DownloadFromScreen() is not required, but is highly recommended. | |
520 | */ | |
521 | Bool (*DownloadFromScreen) (PixmapPtr pSrc, | |
522 | int x, int y, | |
523 | int w, int h, char *dst, int dst_pitch); | |
524 | ||
525 | /** | |
526 | * MarkSync() requests that the driver mark a synchronization point, | |
527 | * returning an driver-defined integer marker which could be requested for | |
528 | * synchronization to later in WaitMarker(). This might be used in the | |
529 | * future to avoid waiting for full hardware stalls before accessing pixmap | |
530 | * data with the CPU, but is not important in the current incarnation of | |
531 | * EXA. | |
532 | * | |
533 | * Note that drivers should call exaMarkSync() when they have done some | |
534 | * acceleration, rather than their own MarkSync() handler, as otherwise EXA | |
535 | * will be unaware of the driver's acceleration and not sync to it during | |
536 | * fallbacks. | |
537 | * | |
538 | * MarkSync() is optional. | |
539 | */ | |
540 | int (*MarkSync) (ScreenPtr pScreen); | |
541 | ||
542 | /** | |
543 | * WaitMarker() waits for all rendering before the given marker to have | |
544 | * completed. If the driver does not implement MarkSync(), marker is | |
545 | * meaningless, and all rendering by the hardware should be completed before | |
546 | * WaitMarker() returns. | |
547 | * | |
548 | * Note that drivers should call exaWaitSync() to wait for all acceleration | |
549 | * to finish, as otherwise EXA will be unaware of the driver having | |
550 | * synchronized, resulting in excessive WaitMarker() calls. | |
551 | * | |
552 | * WaitMarker() is required of all drivers. | |
553 | */ | |
554 | void (*WaitMarker) (ScreenPtr pScreen, int marker); | |
555 | ||
556 | /** @{ */ | |
557 | /** | |
558 | * PrepareAccess() is called before CPU access to an offscreen pixmap. | |
559 | * | |
560 | * @param pPix the pixmap being accessed | |
561 | * @param index the index of the pixmap being accessed. | |
562 | * | |
563 | * PrepareAccess() will be called before CPU access to an offscreen pixmap. | |
564 | * This can be used to set up hardware surfaces for byteswapping or | |
565 | * untiling, or to adjust the pixmap's devPrivate.ptr for the purpose of | |
566 | * making CPU access use a different aperture. | |
567 | * | |
568 | * The index is one of #EXA_PREPARE_DEST, #EXA_PREPARE_SRC, | |
569 | * #EXA_PREPARE_MASK, #EXA_PREPARE_AUX_DEST, #EXA_PREPARE_AUX_SRC, or | |
570 | * #EXA_PREPARE_AUX_MASK. Since only up to #EXA_NUM_PREPARE_INDICES pixmaps | |
571 | * will have PrepareAccess() called on them per operation, drivers can have | |
572 | * a small, statically-allocated space to maintain state for PrepareAccess() | |
573 | * and FinishAccess() in. Note that PrepareAccess() is only called once per | |
574 | * pixmap and operation, regardless of whether the pixmap is used as a | |
575 | * destination and/or source, and the index may not reflect the usage. | |
576 | * | |
577 | * PrepareAccess() may fail. An example might be the case of hardware that | |
578 | * can set up 1 or 2 surfaces for CPU access, but not 3. If PrepareAccess() | |
579 | * fails, EXA will migrate the pixmap to system memory. | |
580 | * DownloadFromScreen() must be implemented and must not fail if a driver | |
581 | * wishes to fail in PrepareAccess(). PrepareAccess() must not fail when | |
582 | * pPix is the visible screen, because the visible screen can not be | |
583 | * migrated. | |
584 | * | |
585 | * @return TRUE if PrepareAccess() successfully prepared the pixmap for CPU | |
586 | * drawing. | |
587 | * @return FALSE if PrepareAccess() is unsuccessful and EXA should use | |
588 | * DownloadFromScreen() to migate the pixmap out. | |
589 | */ | |
590 | Bool (*PrepareAccess) (PixmapPtr pPix, int index); | |
591 | ||
592 | /** | |
593 | * FinishAccess() is called after CPU access to an offscreen pixmap. | |
594 | * | |
595 | * @param pPix the pixmap being accessed | |
596 | * @param index the index of the pixmap being accessed. | |
597 | * | |
598 | * FinishAccess() will be called after finishing CPU access of an offscreen | |
599 | * pixmap set up by PrepareAccess(). Note that the FinishAccess() will not be | |
600 | * called if PrepareAccess() failed and the pixmap was migrated out. | |
601 | */ | |
602 | void (*FinishAccess) (PixmapPtr pPix, int index); | |
603 | ||
604 | /** | |
605 | * PixmapIsOffscreen() is an optional driver replacement to | |
606 | * exaPixmapHasGpuCopy(). Set to NULL if you want the standard behaviour | |
607 | * of exaPixmapHasGpuCopy(). | |
608 | * | |
609 | * @param pPix the pixmap | |
610 | * @return TRUE if the given drawable is in framebuffer memory. | |
611 | * | |
612 | * exaPixmapHasGpuCopy() is used to determine if a pixmap is in offscreen | |
613 | * memory, meaning that acceleration could probably be done to it, and that it | |
614 | * will need to be wrapped by PrepareAccess()/FinishAccess() when accessing it | |
615 | * with the CPU. | |
616 | * | |
617 | * | |
618 | */ | |
619 | Bool (*PixmapIsOffscreen) (PixmapPtr pPix); | |
620 | ||
621 | /** @name PrepareAccess() and FinishAccess() indices | |
622 | * @{ | |
623 | */ | |
624 | /** | |
625 | * EXA_PREPARE_DEST is the index for a pixmap that may be drawn to or | |
626 | * read from. | |
627 | */ | |
628 | #define EXA_PREPARE_DEST 0 | |
629 | /** | |
630 | * EXA_PREPARE_SRC is the index for a pixmap that may be read from | |
631 | */ | |
632 | #define EXA_PREPARE_SRC 1 | |
633 | /** | |
634 | * EXA_PREPARE_SRC is the index for a second pixmap that may be read | |
635 | * from. | |
636 | */ | |
637 | #define EXA_PREPARE_MASK 2 | |
638 | /** | |
639 | * EXA_PREPARE_AUX* are additional indices for other purposes, e.g. | |
640 | * separate alpha maps with Composite operations. | |
641 | */ | |
642 | #define EXA_PREPARE_AUX_DEST 3 | |
643 | #define EXA_PREPARE_AUX_SRC 4 | |
644 | #define EXA_PREPARE_AUX_MASK 5 | |
645 | #define EXA_NUM_PREPARE_INDICES 6 | |
646 | /** @} */ | |
647 | ||
648 | /** | |
649 | * maxPitchPixels controls the pitch limitation for rendering from | |
650 | * the card. | |
651 | * The driver should never receive a request for rendering a pixmap | |
652 | * that has a pitch (in pixels) beyond maxPitchPixels. | |
653 | * | |
654 | * Setting this field is optional -- if your hardware doesn't have | |
655 | * a pitch limitation in pixels, don't set this. If neither this value | |
656 | * nor maxPitchBytes is set, then maxPitchPixels is set to maxX. | |
657 | * If set, it must not be smaller than maxX. | |
658 | * | |
659 | * @sa maxPitchBytes | |
660 | */ | |
661 | int maxPitchPixels; | |
662 | ||
663 | /** | |
664 | * maxPitchBytes controls the pitch limitation for rendering from | |
665 | * the card. | |
666 | * The driver should never receive a request for rendering a pixmap | |
667 | * that has a pitch (in bytes) beyond maxPitchBytes. | |
668 | * | |
669 | * Setting this field is optional -- if your hardware doesn't have | |
670 | * a pitch limitation in bytes, don't set this. | |
671 | * If set, it must not be smaller than maxX * 4. | |
672 | * There's no default value for maxPitchBytes. | |
673 | * | |
674 | * @sa maxPitchPixels | |
675 | */ | |
676 | int maxPitchBytes; | |
677 | ||
678 | /* Hooks to allow driver to its own pixmap memory management */ | |
679 | void *(*CreatePixmap) (ScreenPtr pScreen, int size, int align); | |
680 | void (*DestroyPixmap) (ScreenPtr pScreen, void *driverPriv); | |
681 | /** | |
682 | * Returning a pixmap with non-NULL devPrivate.ptr implies a pixmap which is | |
683 | * not offscreen, which will never be accelerated and Prepare/FinishAccess won't | |
684 | * be called. | |
685 | */ | |
686 | Bool (*ModifyPixmapHeader) (PixmapPtr pPixmap, int width, int height, | |
687 | int depth, int bitsPerPixel, int devKind, | |
688 | pointer pPixData); | |
689 | ||
690 | /* hooks for drivers with tiling support: | |
691 | * driver MUST fill out new_fb_pitch with valid pitch of pixmap | |
692 | */ | |
693 | void *(*CreatePixmap2) (ScreenPtr pScreen, int width, int height, | |
694 | int depth, int usage_hint, int bitsPerPixel, | |
695 | int *new_fb_pitch); | |
696 | /** @} */ | |
697 | Bool (*SharePixmapBacking)(PixmapPtr pPixmap, ScreenPtr slave, void **handle_p); | |
698 | ||
699 | Bool (*SetSharedPixmapBacking)(PixmapPtr pPixmap, void *handle); | |
700 | ||
701 | } ExaDriverRec, *ExaDriverPtr; | |
702 | ||
703 | /** @name EXA driver flags | |
704 | * @{ | |
705 | */ | |
706 | /** | |
707 | * EXA_OFFSCREEN_PIXMAPS indicates to EXA that the driver can support | |
708 | * offscreen pixmaps. | |
709 | */ | |
710 | #define EXA_OFFSCREEN_PIXMAPS (1 << 0) | |
711 | ||
712 | /** | |
713 | * EXA_OFFSCREEN_ALIGN_POT indicates to EXA that the driver needs pixmaps | |
714 | * to have a power-of-two pitch. | |
715 | */ | |
716 | #define EXA_OFFSCREEN_ALIGN_POT (1 << 1) | |
717 | ||
718 | /** | |
719 | * EXA_TWO_BITBLT_DIRECTIONS indicates to EXA that the driver can only | |
720 | * support copies that are (left-to-right, top-to-bottom) or | |
721 | * (right-to-left, bottom-to-top). | |
722 | */ | |
723 | #define EXA_TWO_BITBLT_DIRECTIONS (1 << 2) | |
724 | ||
725 | /** | |
726 | * EXA_HANDLES_PIXMAPS indicates to EXA that the driver can handle | |
727 | * all pixmap addressing and migration. | |
728 | */ | |
729 | #define EXA_HANDLES_PIXMAPS (1 << 3) | |
730 | ||
731 | /** | |
732 | * EXA_SUPPORTS_PREPARE_AUX indicates to EXA that the driver can handle the | |
733 | * EXA_PREPARE_AUX* indices in the Prepare/FinishAccess hooks. If there are no | |
734 | * such hooks, this flag has no effect. | |
735 | */ | |
736 | #define EXA_SUPPORTS_PREPARE_AUX (1 << 4) | |
737 | ||
738 | /** | |
739 | * EXA_SUPPORTS_OFFSCREEN_OVERLAPS indicates to EXA that the driver Copy hooks | |
740 | * can handle the source and destination occupying overlapping offscreen memory | |
741 | * areas. This allows the offscreen memory defragmentation code to defragment | |
742 | * areas where the defragmented position overlaps the fragmented position. | |
743 | * | |
744 | * Typically this is supported by traditional 2D engines but not by 3D engines. | |
745 | */ | |
746 | #define EXA_SUPPORTS_OFFSCREEN_OVERLAPS (1 << 5) | |
747 | ||
748 | /** | |
749 | * EXA_MIXED_PIXMAPS will hide unacceleratable pixmaps from drivers and manage the | |
750 | * problem known software fallbacks like trapezoids. This only migrates pixmaps one way | |
751 | * into a driver pixmap and then pins it. | |
752 | */ | |
753 | #define EXA_MIXED_PIXMAPS (1 << 6) | |
754 | ||
755 | /** @} */ | |
756 | ||
757 | /* in exa.c */ | |
758 | extern _X_EXPORT ExaDriverPtr exaDriverAlloc(void); | |
759 | ||
760 | extern _X_EXPORT Bool | |
761 | exaDriverInit(ScreenPtr pScreen, ExaDriverPtr pScreenInfo); | |
762 | ||
763 | extern _X_EXPORT void | |
764 | exaDriverFini(ScreenPtr pScreen); | |
765 | ||
766 | extern _X_EXPORT void | |
767 | exaMarkSync(ScreenPtr pScreen); | |
768 | extern _X_EXPORT void | |
769 | exaWaitSync(ScreenPtr pScreen); | |
770 | ||
771 | extern _X_EXPORT unsigned long | |
772 | exaGetPixmapOffset(PixmapPtr pPix); | |
773 | ||
774 | extern _X_EXPORT unsigned long | |
775 | exaGetPixmapPitch(PixmapPtr pPix); | |
776 | ||
777 | extern _X_EXPORT unsigned long | |
778 | exaGetPixmapSize(PixmapPtr pPix); | |
779 | ||
780 | extern _X_EXPORT void *exaGetPixmapDriverPrivate(PixmapPtr p); | |
781 | ||
782 | /* in exa_offscreen.c */ | |
783 | extern _X_EXPORT ExaOffscreenArea *exaOffscreenAlloc(ScreenPtr pScreen, | |
784 | int size, int align, | |
785 | Bool locked, | |
786 | ExaOffscreenSaveProc save, | |
787 | pointer privData); | |
788 | ||
789 | extern _X_EXPORT ExaOffscreenArea *exaOffscreenFree(ScreenPtr pScreen, | |
790 | ExaOffscreenArea * area); | |
791 | ||
792 | extern _X_EXPORT void | |
793 | ExaOffscreenMarkUsed(PixmapPtr pPixmap); | |
794 | ||
795 | extern _X_EXPORT void | |
796 | exaEnableDisableFBAccess(ScreenPtr pScreen, Bool enable); | |
797 | ||
798 | extern _X_EXPORT Bool | |
799 | exaDrawableIsOffscreen(DrawablePtr pDrawable); | |
800 | ||
801 | /* in exa.c */ | |
802 | extern _X_EXPORT void | |
803 | exaMoveInPixmap(PixmapPtr pPixmap); | |
804 | ||
805 | extern _X_EXPORT void | |
806 | exaMoveOutPixmap(PixmapPtr pPixmap); | |
807 | ||
808 | /* in exa_unaccel.c */ | |
809 | extern _X_EXPORT CARD32 | |
810 | exaGetPixmapFirstPixel(PixmapPtr pPixmap); | |
811 | ||
812 | /** | |
813 | * Returns TRUE if the given planemask covers all the significant bits in the | |
814 | * pixel values for pDrawable. | |
815 | */ | |
816 | #define EXA_PM_IS_SOLID(_pDrawable, _pm) \ | |
817 | (((_pm) & FbFullMask((_pDrawable)->depth)) == \ | |
818 | FbFullMask((_pDrawable)->depth)) | |
819 | ||
820 | #endif /* EXA_H */ |