1/*
2 * Copyright © 2007 Red Hat, Inc.
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Soft-
6 * ware"), to deal in the Software without restriction, including without
7 * limitation the rights to use, copy, modify, merge, publish, distribute,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, provided that the above copyright
10 * notice(s) and this permission notice appear in all copies of the Soft-
11 * ware and that both the above copyright notice(s) and this permission
12 * notice appear in supporting documentation.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL-
16 * ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY
17 * RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN
18 * THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSE-
19 * QUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
20 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
21 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFOR-
22 * MANCE OF THIS SOFTWARE.
23 *
24 * Except as contained in this notice, the name of a copyright holder shall
25 * not be used in advertising or otherwise to promote the sale, use or
26 * other dealings in this Software without prior written authorization of
27 * the copyright holder.
28 *
29 * Authors:
30 *   Kristian Høgsberg (krh@redhat.com)
31 */
32
33#ifndef _DRI2_H_
34#define _DRI2_H_
35
36#include <X11/extensions/dri2tokens.h>
37
38/* Version 2 structure (with format at the end) */
39typedef struct {
40    unsigned int attachment;
41    unsigned int name;
42    unsigned int pitch;
43    unsigned int cpp;
44    unsigned int flags;
45    unsigned int format;
46    void *driverPrivate;
47} DRI2BufferRec, *DRI2BufferPtr;
48
49extern CARD8 dri2_major;        /* version of DRI2 supported by DDX */
50extern CARD8 dri2_minor;
51
52typedef DRI2BufferRec DRI2Buffer2Rec, *DRI2Buffer2Ptr;
53typedef void (*DRI2SwapEventPtr) (ClientPtr client, void *data, int type,
54                                  CARD64 ust, CARD64 msc, CARD32 sbc);
55
56typedef DRI2BufferPtr(*DRI2CreateBuffersProcPtr) (DrawablePtr pDraw,
57                                                  unsigned int *attachments,
58                                                  int count);
59typedef void (*DRI2DestroyBuffersProcPtr) (DrawablePtr pDraw,
60                                           DRI2BufferPtr buffers, int count);
61typedef void (*DRI2CopyRegionProcPtr) (DrawablePtr pDraw,
62                                       RegionPtr pRegion,
63                                       DRI2BufferPtr pDestBuffer,
64                                       DRI2BufferPtr pSrcBuffer);
65typedef void (*DRI2WaitProcPtr) (WindowPtr pWin, unsigned int sequence);
66typedef int (*DRI2AuthMagicProcPtr) (int fd, uint32_t magic);
67typedef int (*DRI2AuthMagic2ProcPtr) (ScreenPtr pScreen, uint32_t magic);
68
69/**
70 * Schedule a buffer swap
71 *
72 * This callback is used to support glXSwapBuffers and the OML_sync_control
73 * extension (see it for a description of the params).
74 *
75 * Drivers should queue an event for the frame count that satisfies the
76 * parameters passed in.  If the event is in the future (i.e. the conditions
77 * aren't currently satisfied), the server may block the client at the next
78 * GLX request using DRI2WaitSwap. When the event arrives, drivers should call
79 * \c DRI2SwapComplete, which will handle waking the client and returning
80 * the appropriate data.
81 *
82 * The DDX is responsible for doing a flip, exchange, or blit of the swap
83 * when the corresponding event arrives.  The \c DRI2CanFlip and
84 * \c DRI2CanExchange functions can be used as helpers for this purpose.
85 *
86 * \param client client pointer (used for block/unblock)
87 * \param pDraw drawable whose count we want
88 * \param pDestBuffer current front buffer
89 * \param pSrcBuffer current back buffer
90 * \param target_msc frame count to wait for
91 * \param divisor divisor for condition equation
92 * \param remainder remainder for division equation
93 * \param func function to call when the swap completes
94 * \param data data for the callback \p func.
95 */
96typedef int (*DRI2ScheduleSwapProcPtr) (ClientPtr client,
97                                        DrawablePtr pDraw,
98                                        DRI2BufferPtr pDestBuffer,
99                                        DRI2BufferPtr pSrcBuffer,
100                                        CARD64 * target_msc,
101                                        CARD64 divisor,
102                                        CARD64 remainder,
103                                        DRI2SwapEventPtr func, void *data);
104typedef DRI2BufferPtr(*DRI2CreateBufferProcPtr) (DrawablePtr pDraw,
105                                                 unsigned int attachment,
106                                                 unsigned int format);
107typedef void (*DRI2DestroyBufferProcPtr) (DrawablePtr pDraw,
108                                          DRI2BufferPtr buffer);
109/**
110 * Notifies driver when DRI2GetBuffers reuses a dri2 buffer.
111 *
112 * Driver may rename the dri2 buffer in this notify if it is required.
113 *
114 * \param pDraw drawable whose count we want
115 * \param buffer buffer that will be returned to client
116 */
117typedef void (*DRI2ReuseBufferNotifyProcPtr) (DrawablePtr pDraw,
118                                              DRI2BufferPtr buffer);
119/**
120 * Get current media stamp counter values
121 *
122 * This callback is used to support the SGI_video_sync and OML_sync_control
123 * extensions.
124 *
125 * Drivers should return the current frame counter and the timestamp from
126 * when the returned frame count was last incremented.
127 *
128 * The count should correspond to the screen where the drawable is currently
129 * visible.  If the drawable isn't visible (e.g. redirected), the server
130 * should return BadDrawable to the client, pending GLX spec updates to
131 * define this behavior.
132 *
133 * \param pDraw drawable whose count we want
134 * \param ust timestamp from when the count was last incremented.
135 * \param mst current frame count
136 */
137typedef int (*DRI2GetMSCProcPtr) (DrawablePtr pDraw, CARD64 * ust,
138                                  CARD64 * msc);
139/**
140 * Schedule a frame count related wait
141 *
142 * This callback is used to support the SGI_video_sync and OML_sync_control
143 * extensions.  See those specifications for details on how to handle
144 * the divisor and remainder parameters.
145 *
146 * Drivers should queue an event for the frame count that satisfies the
147 * parameters passed in.  If the event is in the future (i.e. the conditions
148 * aren't currently satisfied), the driver should block the client using
149 * \c DRI2BlockClient.  When the event arrives, drivers should call
150 * \c DRI2WaitMSCComplete, which will handle waking the client and returning
151 * the appropriate data.
152 *
153 * \param client client pointer (used for block/unblock)
154 * \param pDraw drawable whose count we want
155 * \param target_msc frame count to wait for
156 * \param divisor divisor for condition equation
157 * \param remainder remainder for division equation
158 */
159typedef int (*DRI2ScheduleWaitMSCProcPtr) (ClientPtr client,
160                                           DrawablePtr pDraw,
161                                           CARD64 target_msc,
162                                           CARD64 divisor, CARD64 remainder);
163
164typedef void (*DRI2InvalidateProcPtr) (DrawablePtr pDraw, void *data, XID id);
165
166/**
167 * DRI2 calls this hook when ever swap_limit is going to be changed. Default
168 * implementation for the hook only accepts one as swap_limit. If driver can
169 * support other swap_limits it has to implement supported limits with this
170 * callback.
171 *
172 * \param pDraw drawable whose swap_limit is going to be changed
173 * \param swap_limit new swap_limit that going to be set
174 * \return TRUE if limit is support, FALSE if not.
175 */
176typedef Bool (*DRI2SwapLimitValidateProcPtr) (DrawablePtr pDraw,
177                                              int swap_limit);
178
179typedef DRI2BufferPtr(*DRI2CreateBuffer2ProcPtr) (ScreenPtr pScreen,
180                                                  DrawablePtr pDraw,
181                                                  unsigned int attachment,
182                                                  unsigned int format);
183typedef void (*DRI2DestroyBuffer2ProcPtr) (ScreenPtr pScreen, DrawablePtr pDraw,
184                                          DRI2BufferPtr buffer);
185
186typedef void (*DRI2CopyRegion2ProcPtr) (ScreenPtr pScreen, DrawablePtr pDraw,
187                                        RegionPtr pRegion,
188                                        DRI2BufferPtr pDestBuffer,
189                                        DRI2BufferPtr pSrcBuffer);
190
191/**
192 * \brief Get the value of a parameter.
193 *
194 * The parameter's \a value is looked up on the screen associated with
195 * \a pDrawable.
196 *
197 * \return \c Success or error code.
198 */
199typedef int (*DRI2GetParamProcPtr) (ClientPtr client,
200                                    DrawablePtr pDrawable,
201                                    CARD64 param,
202                                    BOOL *is_param_recognized,
203                                    CARD64 *value);
204
205/**
206 * Version of the DRI2InfoRec structure defined in this header
207 */
208#define DRI2INFOREC_VERSION 9
209
210typedef struct {
211    unsigned int version;       /**< Version of this struct */
212    int fd;
213    const char *driverName;
214    const char *deviceName;
215
216    DRI2CreateBufferProcPtr CreateBuffer;
217    DRI2DestroyBufferProcPtr DestroyBuffer;
218    DRI2CopyRegionProcPtr CopyRegion;
219    DRI2WaitProcPtr Wait;
220
221    /* added in version 4 */
222
223    DRI2ScheduleSwapProcPtr ScheduleSwap;
224    DRI2GetMSCProcPtr GetMSC;
225    DRI2ScheduleWaitMSCProcPtr ScheduleWaitMSC;
226
227    /* number of drivers in the driverNames array */
228    unsigned int numDrivers;
229    /* array of driver names, indexed by DRI2Driver* driver types */
230    /* a name of NULL means that driver is not supported */
231    const char *const *driverNames;
232
233    /* added in version 5 */
234
235    DRI2AuthMagicProcPtr AuthMagic;
236
237    /* added in version 6 */
238
239    DRI2ReuseBufferNotifyProcPtr ReuseBufferNotify;
240    DRI2SwapLimitValidateProcPtr SwapLimitValidate;
241
242    /* added in version 7 */
243    DRI2GetParamProcPtr GetParam;
244
245    /* added in version 8 */
246    /* AuthMagic callback which passes extra context */
247    /* If this is NULL the AuthMagic callback is used */
248    /* If this is non-NULL the AuthMagic callback is ignored */
249    DRI2AuthMagic2ProcPtr AuthMagic2;
250
251    /* added in version 9 */
252    DRI2CreateBuffer2ProcPtr CreateBuffer2;
253    DRI2DestroyBuffer2ProcPtr DestroyBuffer2;
254    DRI2CopyRegion2ProcPtr CopyRegion2;
255} DRI2InfoRec, *DRI2InfoPtr;
256
257extern _X_EXPORT Bool DRI2ScreenInit(ScreenPtr pScreen, DRI2InfoPtr info);
258
259extern _X_EXPORT void DRI2CloseScreen(ScreenPtr pScreen);
260
261extern _X_EXPORT Bool DRI2HasSwapControl(ScreenPtr pScreen);
262
263extern _X_EXPORT Bool DRI2Connect(ClientPtr client, ScreenPtr pScreen,
264                                  unsigned int driverType,
265                                  int *fd,
266                                  const char **driverName,
267                                  const char **deviceName);
268
269extern _X_EXPORT Bool DRI2Authenticate(ClientPtr client, ScreenPtr pScreen, uint32_t magic);
270
271extern _X_EXPORT int DRI2CreateDrawable(ClientPtr client,
272                                        DrawablePtr pDraw,
273                                        XID id,
274                                        DRI2InvalidateProcPtr invalidate,
275                                        void *priv);
276
277extern _X_EXPORT int DRI2CreateDrawable2(ClientPtr client,
278                                         DrawablePtr pDraw,
279                                         XID id,
280                                         DRI2InvalidateProcPtr invalidate,
281                                         void *priv,
282                                         XID *dri2_id_out);
283
284extern _X_EXPORT DRI2BufferPtr *DRI2GetBuffers(DrawablePtr pDraw,
285                                               int *width,
286                                               int *height,
287                                               unsigned int *attachments,
288                                               int count, int *out_count);
289
290extern _X_EXPORT int DRI2CopyRegion(DrawablePtr pDraw,
291                                    RegionPtr pRegion,
292                                    unsigned int dest, unsigned int src);
293
294/**
295 * Determine the major and minor version of the DRI2 extension.
296 *
297 * Provides a mechanism to other modules (e.g., 2D drivers) to determine the
298 * version of the DRI2 extension.  While it is possible to peek directly at
299 * the \c XF86ModuleData from a layered module, such a module will fail to
300 * load (due to an unresolved symbol) if the DRI2 extension is not loaded.
301 *
302 * \param major  Location to store the major version of the DRI2 extension
303 * \param minor  Location to store the minor version of the DRI2 extension
304 *
305 * \note
306 * This interface was added some time after the initial release of the DRI2
307 * module.  Layered modules that wish to use this interface must first test
308 * its existence by calling \c xf86LoaderCheckSymbol.
309 */
310extern _X_EXPORT void DRI2Version(int *major, int *minor);
311
312extern _X_EXPORT DRI2BufferPtr *DRI2GetBuffersWithFormat(DrawablePtr pDraw,
313                                                         int *width,
314                                                         int *height,
315                                                         unsigned int
316                                                         *attachments,
317                                                         int count,
318                                                         int *out_count);
319
320extern _X_EXPORT void DRI2SwapInterval(DrawablePtr pDrawable, int interval);
321extern _X_EXPORT Bool DRI2SwapLimit(DrawablePtr pDraw, int swap_limit);
322extern _X_EXPORT int DRI2SwapBuffers(ClientPtr client, DrawablePtr pDrawable,
323                                     CARD64 target_msc, CARD64 divisor,
324                                     CARD64 remainder, CARD64 * swap_target,
325                                     DRI2SwapEventPtr func, void *data);
326extern _X_EXPORT Bool DRI2WaitSwap(ClientPtr client, DrawablePtr pDrawable);
327
328extern _X_EXPORT int DRI2GetMSC(DrawablePtr pDrawable, CARD64 * ust,
329                                CARD64 * msc, CARD64 * sbc);
330extern _X_EXPORT int DRI2WaitMSC(ClientPtr client, DrawablePtr pDrawable,
331                                 CARD64 target_msc, CARD64 divisor,
332                                 CARD64 remainder);
333extern _X_EXPORT int ProcDRI2WaitMSCReply(ClientPtr client, CARD64 ust,
334                                          CARD64 msc, CARD64 sbc);
335extern _X_EXPORT int DRI2WaitSBC(ClientPtr client, DrawablePtr pDraw,
336                                 CARD64 target_sbc);
337extern _X_EXPORT Bool DRI2ThrottleClient(ClientPtr client, DrawablePtr pDraw);
338
339extern _X_EXPORT Bool DRI2CanFlip(DrawablePtr pDraw);
340
341extern _X_EXPORT Bool DRI2CanExchange(DrawablePtr pDraw);
342
343/* Note: use *only* for MSC related waits */
344extern _X_EXPORT void DRI2BlockClient(ClientPtr client, DrawablePtr pDraw);
345
346extern _X_EXPORT void DRI2SwapComplete(ClientPtr client, DrawablePtr pDraw,
347                                       int frame, unsigned int tv_sec,
348                                       unsigned int tv_usec, int type,
349                                       DRI2SwapEventPtr swap_complete,
350                                       void *swap_data);
351extern _X_EXPORT void DRI2WaitMSCComplete(ClientPtr client, DrawablePtr pDraw,
352                                          int frame, unsigned int tv_sec,
353                                          unsigned int tv_usec);
354
355extern _X_EXPORT int DRI2GetParam(ClientPtr client,
356                                  DrawablePtr pDrawable,
357                                  CARD64 param,
358                                  BOOL *is_param_recognized,
359                                  CARD64 *value);
360
361extern _X_EXPORT DrawablePtr DRI2UpdatePrime(DrawablePtr pDraw, DRI2BufferPtr pDest);
362#endif
363