1/*
2 * Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas.
3 * All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the
7 * "Software"), to deal in the Software without restriction, including
8 * without limitation the rights to use, copy, modify, merge, publish,
9 * distribute, sub license, and/or sell copies of the Software, and to
10 * permit persons to whom the Software is furnished to do so, subject to
11 * the following conditions:
12 *
13 * The above copyright notice and this permission notice (including the
14 * next paragraph) shall be included in all copies or substantial portions
15 * of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
20 * IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
21 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 */
25
26/**
27 * \file dri_util.h
28 * DRI utility functions definitions.
29 *
30 * This module acts as glue between GLX and the actual hardware driver.  A DRI
31 * driver doesn't really \e have to use any of this - it's optional.  But, some
32 * useful stuff is done here that otherwise would have to be duplicated in most
33 * drivers.
34 *
35 * Basically, these utility functions take care of some of the dirty details of
36 * screen initialization, context creation, context binding, DRM setup, etc.
37 *
38 * These functions are compiled into each DRI driver so libGL.so knows nothing
39 * about them.
40 *
41 * \sa dri_util.c.
42 *
43 * \author Kevin E. Martin <kevin@precisioninsight.com>
44 * \author Brian Paul <brian@precisioninsight.com>
45 */
46
47/**
48 * The following structs are shared between DRISW and DRI2, the DRISW structs
49 * are essentially base classes of the DRI2 structs. DRISW needs to compile on
50 * platforms without DRM, so keep the structs opaque to DRM.
51 */
52
53#ifndef _DRI_UTIL_H_
54#define _DRI_UTIL_H_
55
56#include <GL/gl.h>
57#include <GL/internal/dri_interface.h>
58#include "main/menums.h"
59#include "main/formats.h"
60#include "util/xmlconfig.h"
61#include <stdbool.h>
62
63struct gl_config;
64struct gl_context;
65
66/**
67 * Extensions.
68 */
69extern const __DRIcoreExtension driCoreExtension;
70extern const __DRIswrastExtension driSWRastExtension;
71extern const __DRIdri2Extension driDRI2Extension;
72extern const __DRI2configQueryExtension dri2ConfigQueryExtension;
73extern const __DRIcopySubBufferExtension driCopySubBufferExtension;
74extern const __DRI2flushControlExtension dri2FlushControlExtension;
75
76/**
77 * Description of the attributes used to create a config.
78 *
79 * This is passed as the context_config parameter to CreateContext. The idea
80 * with this struct is that it can be extended without having to modify all of
81 * the drivers. The first three members (major/minor_version and flags) are
82 * always valid, but the remaining members are only valid if the corresponding
83 * flag is set for the attribute. If the flag is not set then the default
84 * value should be assumed. That way the driver can quickly check if any
85 * attributes were set that it doesn't understand and report an error.
86 */
87struct __DriverContextConfig {
88    /* These members are always valid */
89    unsigned major_version;
90    unsigned minor_version;
91    uint32_t flags;
92
93    /* Flags describing which of the remaining members are valid */
94    uint32_t attribute_mask;
95
96    /* Only valid if __DRIVER_CONTEXT_ATTRIB_RESET_STRATEGY is set */
97    int reset_strategy;
98
99    /* Only valid if __DRIVER_CONTEXT_PRIORITY is set */
100    unsigned priority;
101
102    /* Only valid if __DRIVER_CONTEXT_ATTRIB_RELEASE_BEHAVIOR is set */
103    int release_behavior;
104};
105
106#define __DRIVER_CONTEXT_ATTRIB_RESET_STRATEGY   (1 << 0)
107#define __DRIVER_CONTEXT_ATTRIB_PRIORITY         (1 << 1)
108#define __DRIVER_CONTEXT_ATTRIB_RELEASE_BEHAVIOR (1 << 2)
109
110/**
111 * Driver callback functions.
112 *
113 * Each DRI driver must have one of these structures with all the pointers set
114 * to appropriate functions within the driver.
115 *
116 * When glXCreateContext() is called, for example, it'll call a helper function
117 * dri_util.c which in turn will jump through the \a CreateContext pointer in
118 * this structure.
119 */
120struct __DriverAPIRec {
121    const __DRIconfig **(*InitScreen) (__DRIscreen * priv);
122
123    void (*DestroyScreen)(__DRIscreen *driScrnPriv);
124
125    GLboolean (*CreateContext)(gl_api api,
126                               const struct gl_config *glVis,
127                               __DRIcontext *driContextPriv,
128                               const struct __DriverContextConfig *ctx_config,
129                               unsigned *error,
130                               void *sharedContextPrivate);
131
132    void (*DestroyContext)(__DRIcontext *driContextPriv);
133
134    GLboolean (*CreateBuffer)(__DRIscreen *driScrnPriv,
135                              __DRIdrawable *driDrawPriv,
136                              const struct gl_config *glVis,
137                              GLboolean pixmapBuffer);
138
139    void (*DestroyBuffer)(__DRIdrawable *driDrawPriv);
140
141    void (*SwapBuffers)(__DRIdrawable *driDrawPriv);
142
143    GLboolean (*MakeCurrent)(__DRIcontext *driContextPriv,
144                             __DRIdrawable *driDrawPriv,
145                             __DRIdrawable *driReadPriv);
146
147    GLboolean (*UnbindContext)(__DRIcontext *driContextPriv);
148
149    __DRIbuffer *(*AllocateBuffer) (__DRIscreen *screenPrivate,
150                                    unsigned int attachment,
151                                    unsigned int format,
152                                    int width, int height);
153
154    void (*ReleaseBuffer) (__DRIscreen *screenPrivate, __DRIbuffer *buffer);
155
156    void (*CopySubBuffer)(__DRIdrawable *driDrawPriv, int x, int y,
157                          int w, int h);
158};
159
160extern const struct __DriverAPIRec driDriverAPI;
161extern const struct __DriverAPIRec *globalDriverAPI;
162
163/**
164 * Per-screen private driver information.
165 */
166struct __DRIscreenRec {
167    /**
168     * Driver-specific entrypoints provided by the driver's
169     * __DRIDriverVtableExtensionRec.
170     */
171    const struct __DriverAPIRec *driver;
172
173    /**
174     * Current screen's number
175     */
176    int myNum;
177
178    /**
179     * File descriptor returned when the kernel device driver is opened.
180     *
181     * Used to:
182     *   - authenticate client to kernel
183     *   - map the frame buffer, SAREA, etc.
184     *   - close the kernel device driver
185     */
186    int fd;
187
188    /**
189     * Device-dependent private information (not stored in the SAREA).
190     *
191     * This pointer is never touched by the DRI layer.
192     */
193    void *driverPrivate;
194
195    void *loaderPrivate;
196
197    int max_gl_core_version;
198    int max_gl_compat_version;
199    int max_gl_es1_version;
200    int max_gl_es2_version;
201
202    const __DRIextension **extensions;
203
204    const __DRIswrastLoaderExtension *swrast_loader;
205
206    struct {
207	/* Flag to indicate that this is a DRI2 screen.  Many of the above
208	 * fields will not be valid or initializaed in that case. */
209	const __DRIdri2LoaderExtension *loader;
210	const __DRIimageLookupExtension *image;
211	const __DRIuseInvalidateExtension *useInvalidate;
212        const __DRIbackgroundCallableExtension *backgroundCallable;
213    } dri2;
214
215    struct {
216        const __DRIimageLoaderExtension *loader;
217    } image;
218
219    struct {
220       const __DRImutableRenderBufferLoaderExtension *loader;
221    } mutableRenderBuffer;
222
223    driOptionCache optionInfo;
224    driOptionCache optionCache;
225
226    unsigned int api_mask;
227};
228
229/**
230 * Per-context private driver information.
231 */
232struct __DRIcontextRec {
233    /**
234     * Device driver's private context data.  This structure is opaque.
235     */
236    void *driverPrivate;
237
238    /**
239     * The loaders's private context data.  This structure is opaque.
240     */
241    void *loaderPrivate;
242
243    /**
244     * Pointer to drawable currently bound to this context for drawing.
245     */
246    __DRIdrawable *driDrawablePriv;
247
248    /**
249     * Pointer to drawable currently bound to this context for reading.
250     */
251    __DRIdrawable *driReadablePriv;
252
253    /**
254     * Pointer to screen on which this context was created.
255     */
256    __DRIscreen *driScreenPriv;
257
258    struct {
259	int draw_stamp;
260	int read_stamp;
261    } dri2;
262};
263
264/**
265 * Per-drawable private DRI driver information.
266 */
267struct __DRIdrawableRec {
268    /**
269     * Driver's private drawable information.
270     *
271     * This structure is opaque.
272     */
273    void *driverPrivate;
274
275    /**
276     * Private data from the loader.  We just hold on to it and pass
277     * it back when calling into loader provided functions.
278     */
279    void *loaderPrivate;
280
281    /**
282     * Pointer to context to which this drawable is currently bound.
283     */
284    __DRIcontext *driContextPriv;
285
286    /**
287     * Pointer to screen on which this drawable was created.
288     */
289    __DRIscreen *driScreenPriv;
290
291    /**
292     * Reference count for number of context's currently bound to this
293     * drawable.
294     *
295     * Once it reaches zero, the drawable can be destroyed.
296     *
297     * \note This behavior will change with GLX 1.3.
298     */
299    int refcount;
300
301    /**
302     * Last value of the stamp.
303     *
304     * If this differs from the value stored at __DRIdrawable::dri2.stamp,
305     * then the drawable information has been modified by the X server, and the
306     * drawable information (below) should be retrieved from the X server.
307     */
308    unsigned int lastStamp;
309
310    int w, h;
311
312    /**
313     * Drawable timestamp.  Increased when the loader calls invalidate.
314     */
315    struct {
316	unsigned int stamp;
317    } dri2;
318};
319
320extern uint32_t
321driGLFormatToImageFormat(mesa_format format);
322
323extern uint32_t
324driGLFormatToSizedInternalGLFormat(mesa_format format);
325
326extern mesa_format
327driImageFormatToGLFormat(uint32_t image_format);
328
329extern void
330dri2InvalidateDrawable(__DRIdrawable *drawable);
331
332extern void
333driUpdateFramebufferSize(struct gl_context *ctx, const __DRIdrawable *dPriv);
334
335extern void
336driContextSetFlags(struct gl_context *ctx, uint32_t flags);
337
338extern const __DRIimageDriverExtension driImageDriverExtension;
339
340extern const __DRInoErrorExtension dri2NoErrorExtension;
341
342#endif /* _DRI_UTIL_H_ */
343