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) 81 extern "C" { 82 #endif 83 84 /** 85 * An opaque pointer representing a vendor library. 86 */ 87 typedef struct GlxServerVendorRec GlxServerVendor; 88 89 typedef int (* GlxServerDispatchProc) (ClientPtr client); 90 91 typedef struct GlxServerImportsRec GlxServerImports; 92 93 /** 94 * Functions exported by libglvnd to the vendor library. 95 */ 96 typedef 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 alraedy 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 252 extern _X_EXPORT const GlxServerExports glxServer; 253 254 /** 255 * Functions exported by the vendor library to libglvnd. 256 */ 257 struct 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