exa.h@ 99743

Last change on this file since 99743 was 32163, checked in by vboxsync, 14 years ago
Additions/x11/x11include: additional headers for building drivers for X.Org Server 1.9
Property svn:eol-style set to `native`
File size: 33.1 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Additions/x11/x11include/xorg-server-1.9.0/exa.h@ 99743

Download in other formats: