1/*
2 * Copyright (c) 2016, NVIDIA CORPORATION.
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and/or associated documentation files (the
6 * "Materials"), to deal in the Materials without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Materials, and to
9 * permit persons to whom the Materials are furnished to do so, subject to
10 * the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included
13 * unaltered in all copies or substantial portions of the Materials.
14 * Any additions, deletions, or changes to the original source files
15 * must be clearly indicated in accompanying documentation.
16 *
17 * If only executable code is distributed, then the accompanying
18 * documentation must state that "this software is based in part on the
19 * work of the Khronos Group."
20 *
21 * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
24 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
25 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
26 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
27 * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
28 */
29
30/**
31 * \file
32 *
33 * Defines the interface between the libglvnd server module and a vendor
34 * library.
35 *
36 * Each screen may have one vendor library assigned to it. The GLVND module
37 * will examine each GLX request to determine which screen it goes to, and then
38 * it will forward that request to whichever vendor is assigned to that screen.
39 *
40 * Each vendor library is represented by an opaque __GLXServerVendor handle.
41 * Display drivers are responsible for creating handles for its GLX
42 * implementations, and assigning those handles to each screen.
43 *
44 * The GLVND module keeps a list of callbacks, which are called from
45 * InitExtensions. Drivers should use that callback to assign a vendor
46 * handle to whichever screens they support.
47 *
48 * Additional notes about dispatching:
49 * - If a request has one or more GLXContextTag values, then the dispatch stub
50 *   must ensure that all of the tags belong to the vendor that it forwards the
51 *   request to. Otherwise, if a vendor library tries to look up the private
52 *   data for the tag, it could get the data from another vendor and crash.
53 * - Following from the last point, if a request takes a GLXContextTag value,
54 *   then the dispatch stub should use the tag to select a vendor. If the
55 *   request takes two or more tags, then the vendor must ensure that they all
56 *   map to the same vendor.
57 */
58
59#ifndef GLXVENDORABI_H
60#define GLXVENDORABI_H
61
62#include <scrnintstr.h>
63#include <extnsionst.h>
64#include <GL/glxproto.h>
65
66/*!
67 * Current version of the ABI.
68 *
69 * This version number contains a major number in the high-order 16 bits, and
70 * a minor version number in the low-order 16 bits.
71 *
72 * The major version number is incremented when an interface change will break
73 * backwards compatibility with existing vendor libraries. The minor version
74 * number is incremented when there's a change but existing vendor libraries
75 * will still work.
76 */
77#define GLXSERVER_VENDOR_ABI_MAJOR_VERSION 0
78#define GLXSERVER_VENDOR_ABI_MINOR_VERSION 1
79
80#if defined(__cplusplus)
81extern "C" {
82#endif
83
84/**
85 * An opaque pointer representing a vendor library.
86 */
87typedef struct GlxServerVendorRec GlxServerVendor;
88
89typedef int (* GlxServerDispatchProc) (ClientPtr client);
90
91typedef struct GlxServerImportsRec GlxServerImports;
92
93/**
94 * Functions exported by libglvnd to the vendor library.
95 */
96typedef struct GlxServerExportsRec {
97    int majorVersion;
98    int minorVersion;
99
100    /**
101     * This callback is called during each server generation when the GLX
102     * extension is initialized.
103     *
104     * Drivers may create a __GLXServerVendor handle at any time, but may only
105     * assign a vendor to a screen from this callback.
106     *
107     * The callback is called with the ExtensionEntry pointer for the GLX
108     * extension.
109     */
110    CallbackListPtr *extensionInitCallback;
111
112    /**
113     * Allocates and zeroes a __GLXserverImports structure.
114     *
115     * Future versions of the GLVND interface may add optional members to the
116     * end of the __GLXserverImports struct. Letting the GLVND layer allocate
117     * the __GLXserverImports struct allows backward compatibility with
118     * existing drivers.
119     */
120    GlxServerImports * (* allocateServerImports) (void);
121
122    /**
123     * Frees a __GLXserverImports structure that was allocated with
124     * \c allocateServerImports.
125     */
126    void (* freeServerImports) (GlxServerImports *imports);
127
128    /**
129     * Creates a new vendor library handle.
130     */
131    GlxServerVendor * (* createVendor) (const GlxServerImports *imports);
132
133    /**
134     * Destroys a vendor library handle.
135     *
136     * This function may not be called while the vendor handle is assigned to a
137     * screen, but it may be called from the __GLXserverImports::extensionCloseDown
138     * callback.
139     */
140    void (* destroyVendor) (GlxServerVendor *vendor);
141
142    /**
143     * Sets the vendor library to use for a screen.
144     *
145     * This function should be called from the screen's CreateScreenResources
146     * callback.
147     */
148    Bool (* setScreenVendor) (ScreenPtr screen, GlxServerVendor *vendor);
149
150
151    /**
152     * Adds an entry to the XID map.
153     *
154     * This mapping is used to dispatch requests based on an XID.
155     *
156     * Client-generated XID's (contexts, drawables, etc) must be added to the
157     * map by the dispatch stub.
158     *
159     * XID's that are generated in the server should be added by the vendor
160     * library.
161     *
162     * Vendor libraries are responsible for keeping track of any additional
163     * data they need for the XID's.
164     *
165     * Note that adding GLXFBConfig ID's appears to be unnecessary -- every GLX
166     * request I can find that takes a GLXFBConfig also takes a screen number.
167     *
168     * \param id The XID to add to the map. The XID must not already be in the
169     *      map.
170     * \param vendor The vendor library to associate with \p id.
171     * \return True on success, or False on failure.
172     */
173    Bool (* addXIDMap) (XID id, GlxServerVendor *vendor);
174
175    /**
176     * Returns the vendor and data for an XID, as added with \c addXIDMap.
177     *
178     * If \p id wasn't added with \c addXIDMap (for example, if it's a regular
179     * X window), then libglvnd will try to look it up as a drawable and return
180     * the vendor for whatever screen it's on.
181     *
182     * \param id The XID to look up.
183     * \return The vendor that owns the XID, or \c NULL if no matching vendor
184     * was found.
185     */
186    GlxServerVendor * (* getXIDMap) (XID id);
187
188    /**
189     * Removes an entry from the XID map.
190     */
191    void (* removeXIDMap) (XID id);
192
193    /**
194     * Looks up a context tag.
195     *
196     * Context tags are created and managed by libglvnd to ensure that they're
197     * unique between vendors.
198     *
199     * \param client The client connection.
200     * \param tag The context tag.
201     * \return The vendor that owns the context tag, or \c NULL if the context
202     * tag is invalid.
203     */
204    GlxServerVendor * (* getContextTag)(ClientPtr client, GLXContextTag tag);
205
206    /**
207     * Assigns a pointer to vendor-private data for a context tag.
208     *
209     * Since the tag values are assigned by GLVND, vendors can use this
210     * function to store any private data they need for a context tag.
211     *
212     * \param client The client connection.
213     * \param tag The context tag.
214     * \param data An arbitrary pointer value.
215     */
216    Bool (* setContextTagPrivate)(ClientPtr client, GLXContextTag tag, void *data);
217
218    /**
219     * Returns the private data pointer that was assigned from
220     * setContextTagPrivate.
221     *
222     * This function is safe to use in __GLXserverImports::makeCurrent to look
223     * up the old context private pointer.
224     *
225     * However, this function is not safe to use from a ClientStateCallback,
226     * because GLVND may have already deleted the tag by that point.
227     */
228    void * (* getContextTagPrivate)(ClientPtr client, GLXContextTag tag);
229
230    GlxServerVendor * (* getVendorForScreen) (ClientPtr client, ScreenPtr screen);
231
232    /**
233     * Forwards a request to a vendor library.
234     *
235     * \param vendor The vendor to send the request to.
236     * \param client The client.
237     */
238    int (* forwardRequest) (GlxServerVendor *vendor, ClientPtr client);
239
240    /**
241     * Sets the vendor library to use for a screen for a specific client.
242     *
243     * This function changes which vendor should handle GLX requests for a
244     * screen. Unlike \c setScreenVendor, this function can be called at any
245     * time, and only applies to requests from a single client.
246     *
247     * This function is available in GLXVND version 0.1 or later.
248     */
249    Bool (* setClientScreenVendor) (ClientPtr client, ScreenPtr screen, GlxServerVendor *vendor);
250} GlxServerExports;
251
252extern _X_EXPORT const GlxServerExports glxServer;
253
254/**
255 * Functions exported by the vendor library to libglvnd.
256 */
257struct GlxServerImportsRec {
258    /**
259     * Called on a server reset.
260     *
261     * This is called from the extension's CloseDown callback.
262     *
263     * Note that this is called after freeing all of GLVND's per-screen data,
264     * so the callback may destroy any vendor handles.
265     *
266     * If the server is exiting, then GLVND will free any remaining vendor
267     * handles after calling the extensionCloseDown callbacks.
268     */
269    void (* extensionCloseDown) (const ExtensionEntry *extEntry);
270
271    /**
272     * Handles a GLX request.
273     */
274    int (* handleRequest) (ClientPtr client);
275
276    /**
277     * Returns a dispatch function for a request.
278     *
279     * \param minorOpcode The minor opcode of the request.
280     * \param vendorCode The vendor opcode, if \p minorOpcode
281     *      is \c X_GLXVendorPrivate or \c X_GLXVendorPrivateWithReply.
282     * \return A dispatch function, or NULL if the vendor doesn't support this
283     *      request.
284     */
285    GlxServerDispatchProc (* getDispatchAddress) (CARD8 minorOpcode, CARD32 vendorCode);
286
287    /**
288     * Handles a MakeCurrent request.
289     *
290     * This function is called to handle any MakeCurrent request. The vendor
291     * library should deal with changing the current context. After the vendor
292     * returns GLVND will send the reply.
293     *
294     * In addition, GLVND will call this function with any current contexts
295     * when a client disconnects.
296     *
297     * To ensure that context tags are unique, libglvnd will select a context
298     * tag and pass it to the vendor library.
299     *
300     * The vendor can use \c __GLXserverExports::getContextTagPrivate to look
301     * up the private data pointer for \p oldContextTag.
302     *
303     * Likewise, the vendor can use \c __GLXserverExports::setContextTagPrivate
304     * to assign a private data pointer to \p newContextTag.
305     */
306    int (* makeCurrent) (ClientPtr client,
307        GLXContextTag oldContextTag,
308        XID drawable,
309        XID readdrawable,
310        XID context,
311        GLXContextTag newContextTag);
312};
313
314#if defined(__cplusplus)
315}
316#endif
317
318#endif // GLXVENDORABI_H
319