To: opengl-licensees@sgi.com Subject: GLX 1.3 and the fbconfig and pbuffer extensions Date: Thu, 09 May 96 19:13:10 -0700 From: "Paula Womack" We need to discuss GLX 1.3, fbconfig and pbuffers at the upcoming ARB meeting. At the GLX meeting in April, we decided that the ARB should define EXT extensions for fbconfig and pbuffers first and then, after the extensions had been implemented by at least one other vendor (SGI already implemented the SGIX versions), we could discuss incorporating them into GLX 1.3 It was suggested that the best way to discuss fbconfig and pbuffers was to list the problems that each extension solved and then go through the problems one-by-one and prioritize them. I updated the GLX 1.3 document (included below) to reflect the decisions made at the last GLX meeting and also, added this list of problems. Note that no information has been deleted from this document -- when a proposal is rejected I just move it to a new spot in the document. Paula ------- GLX 1.3 ------- NEW FEATURES: -------------- 1. fbconfig (see extension spec) What problems should fbconfig solve? ------------------------------------ SGIX_fbconfig solves the following problems: a. Removes similarity requirement for contexts and drawables. Instead it introduces a "compatibility" requirement. A GLXContext and a GLXDrawable are compatible if - the render_type attribute for the context is supported by the GLXFBConfigSGIX that the drawable was created with. (e.g., if the context was created with render_type GLX_RGBA_TYPE_SGIX, then the GLXFBConfigSGIX's GLX_RENDER_TYPE_SGIX attribute must have the GLX_RGBA_BIT_SGIX bit set.) - all color buffers and ancillary buffers that exist in both GLXFBConfigSGIXs have the same depth. For example, a GLXDrawable that had a front left buffer and a back left buffer with red, green and blue sizes of 4 would not be compatible with a GLXFBConfigSGIX that had only a front left buffer with red, green and blue sizes of 8. However, it would be compatible with a GLXFBConfigSGIX that had only a front left buffer if the red, green and blue sizes were 4. b. Doesn't require configurations to work on all types of drawables A particular fbconfig may only support a subset of drawables (pbuffer, pixmap, window). c. Allows RGBA rendering to single-channel visuals. It allows RGBA rendering to windows created with PseudoColor, StaticColor, StaticGray and GreyScale visuals d. Adds the following configuration attributes: - visual caveat (slow or non-confomant) - transparent pixel information - X visual type (if the configuration has an associated X visual) e. Implements new configuration/visual selection mechanism (see spec) We may want EXT_fbconfig to also solve these problems: a. Completely remove similarity requirement. This would allow, for example, a 4/4 double buffered drawable and an 8 bit single buffer drawable to be bound to the same context. b. Allow contexts to support both RGBA and color index rendering c. Reduce visual explosion. In order to reduce visual explosion we would need to be able to map many fbconfigs to one visual. d. Reduce fbconfig explosion e. Promote colormap sharing by allowing multiple FBConfigs to map to a single X visual. Currently X will return a BadMatch if the colormap was not created with the same visual as the window. (This could also be solved via an X extension) Spec Notes: ---------- a) Replaces visual_info, visual_rating and transparent_pixel (visual_info and visual_rating were in the preliminary draft of 1.2; visual_info replaces transparent_pixel) b) The new create context call should really take a GLXContextID for share_list instead of a GLXContext. c) If we remove the "compatibility" then the create context call would not require a GLXFBConfig argument; instead a screen i.d. would be required. The new entry point for CreateContext would look something like: GLXContext glXCreateNewContext(Display *dpy, int render_type, GLXContextID share_list, Bool direct); (although we will probably want to think up a better name) Note that if we remove the compatibility constraints then the actual bias produced by PolygonOffset may have to be recomputed. (As well as any derived state in a sw implementation) d) If we allow multiple FBConfigs to map to a single X visual then the framebuffer configuration is not fixed when the window is created. Thus a new glx call would need to be added: GLXWindow glXCreateGLXWindowWithConfig(Display *dpy, GLXFBConfigSGIX config, Window win); A GLX program then looks something like: < open connection, check if GLX supported and what version > fbconfig = glXChooseFBConfig(dpy, screen, attrib_list, &nelements); < get colormap > ctx = glXCreateNewContext(dpy, GLX_RGBA_TYPE, NULL, True); vis = glXGetVisualFromFBConfig(dpy, fbconfig[0]); win = XCreateWindow(dpy, root, x, y, width, height, 0, vis->depth, InputOutput, vis->visual, mask, attr); draw = glXCreateGLXWindowWithConfig(dpy, fbconfig[0], win); < set window properties, etc > glXMakeCurrent(dpy, draw, ctx); : Is this too many steps? 2. pbuffer (see extension spec) What problems should pbuffers solve? ------------------------------------ SGIX_pbuffer introduces non-visible buffers with the following attributes: 1. Rendering to them is accelerated Since these buffers are accelerated they will live in offscreen framebuffer memory unless the hw can render into system memory. Thus, it is important to expose the mechanisms for managing a fixed resource. 2. They are guaranteed to work with direct rendering contexts. (Unlike pixmaps, pbuffers *must* work with direct rendering contexts.) 3. They are not associated with a window and are therefore not clipped to the window boundaries. (e.g., they aren't like aux buffers) CLARIFICATIONS AND ISSUES: The important issues were discussed at the Feb ARB meeting and advisory votes were taken. Thus, there is no need to discuss these issues. 0. New enums should have unique values (as they do in OpenGL) 1. Don't use the term "renderer" 2. Clarify what is client state and what is server state 3. Expand on definition of Rendering Context in Section 2.1, "Rendering Contexts and Drawing Surfaces" 4. In the discussion of display lists (Section 2.4, "OpenGL Display Lists"), the spec says: "In general, OpenGL commands are not atomic." This is the wrong term and needs to be clarified. If you have two contexts that share a display list and both the contexts are current to some thread, then it is possible for one context to be executing a list while another is changing it. Since many commands may be sent to create a display list (glNewList, cmd, ... glEndList) it is important that the existing list not be superseded until the definition is complete. 5. Remove references to IrisGL in section 2.6, "Aligning Multiple Drawables" 6. Add description of error codes to section 3.1, on "Errors" (e.g., Describe what the error_base is and give the value of the first error code that is added to error base) 7. Switch descriptions of glXMakeCurrent and glXCopyContext (so glXMakeCurrent comes first). 8. In Section 2.2, clarify that glFlush() does not flush the X buffer for an direct rendering context. (Note that direct rendering is not described yet) 9. Section 3.2.4, under glXMakeCurrent, 4th paragraph, clarify how viewport is modified. >From Pat Brown: The first time ctx is made current to any GLXDrawable, the viewport is set to the size of the drawable as though glViewport(0, 0, w, h) were called. The viewport regions are not modified when ctx is subsequently made current to any GLXDrawable. I removed references to glScissor() since you don't need to set the scissor to clip to the drawable. Also, we need to clarify that the first time the server context state is made current, the viewport is set. 10. Make it clear what glXDestroyGLXPixmap does vs XFreePixmap 11. Explicitly state that indirect rendering is required. The ARB decided (13 yes - 1 no) that this was required at the Winter '95 meeting. 12. Correct bit-count-in-color-buffer terminology In Table 1 (configuration attributes don't use framebuffer; color buffer should be used instead since there can be multiple color buffers in a framebuffer configuration) 13. Is pixmap support required? Possibilities are: a) Don't require any pixmap support b) Don't require pixmap support for all visuals (Note that fbconfig addresses this) c) Don't require an implementation to allow a context to be bound to a pixmap and a window. d) Require pixmaps to be fully supported RECOMMEND: Option c. ARB advisory vote from Feb '96 meeting: options (b) and (c) approved 5-1-1 Note on c: This should probably cause a BadMatch error. Side issue: Should glXCopyContext work between indirect and direct rendering contexts? (i.e., between different address spaces.) What are implementors doing now for glXCopyContext on hw that cannot read back into a host-side context. 14. Should an error be generated if a glx function is called between glBegin() and glEnd()? In section 3.2, the spec says: "If a GLX function is called within a glBegin/glEnd pair, then the result is undefined; however, no error is reported." Then later, under glXMakeCurrent, it says: "GLXBadContextState will also be generated if glXMakeCurrent is called between a glBegin and its corresponding glEnd." RECOMMEND: Don't report an error (i.e., leave first statement and remove second). At a previous meeting we decided not to report an error when a glx function was called between glBegin() and glEnd() since it is difficult to do so during direct rendering. ARB advisory vote from Feb '96 meeting: recommended solution approved 6-0-1 REJECTED PROPOSALS: 1. The specification says that glXUseXFont performs an implicit glFlush(). This isn't necessary. Since glXUseXFont() is in both the X and the OpenGL streams (it gets the font definition from X then creates an OpenGL display list with a glBitmap command in it) there isn't any reason to force the OpenGL stream to be flushed beforehand. Nonetheless, we shouldn't change this behaviour since applications will break if we remove this and they were counting on the flush. 2. make current read OK as an extension for now. 3. import context From an early draft of the GLX 1.2 spec: int glXQueryContextInfo(Display *dpy, GLXContext ctx, int attribute, int *value); glxQueryContextInfo returns through the value of for . It may cause a round trip to the server. The values and types corresponding to each GLX context attribute are listed in the table below. GLX context attribute type context information --------------------- ---- ------------------- GLX_SHARE_CONTEXT GLXContextID XID of the share list context GLX_VISUAL_ID XID visual id GLX_SCREEN int screen number glXQueryContextInfo returns GLX_BAD_ATTRIBUTE if is invalid. a GLXBadContext error is generated if is not a valid rendering context. To obtain the XID of a GLXContext, use GLXContextID glXGetContextIDEXT(const GLXContext context); Call glXImportContext to create a GLXContext given the XID of an existing GLXContext: GLXContext glXImportContextEXT(Display *dpy, GLXContextID contextID); glXImportContextEXT may be used in place of glXCreateContext to share another process's indirect rendering context. Only the server-side context information can be shared between X clients; client-side state, such as pixel storage modes, cannot be shared. Thus, glXImportContextEXT, must allocate memory to store client-side information and initialize the client side state to the default OpenGL state. This memory is freed by calling glXDestroyClientContext. This call does not create a new XID. It merely makes an existing object available to the importing client (Display *). Like any XID, it goes away when the creating client drops its connection or the XID is explicitly deleted. Note that this is when the XID goes away. The object goes away when the XID goes away AND the context is not current to any thread. If does not refer to a valid context, then a BadContext error is generated; if refers to direct rendering context then no error is generated but glXImportContextEXT returns NULL. To free the client-side part of a GLXContext, use: void glXDestroyClientContext(Display *dpy, GLXContext context); glXDestroyClientContext does not free the server-side context information or the XID associated with the server-side context. Suggested changes: Share list query: GLX_SHARE_CONTEXT should be boolean glXGetCurrentDisplay already there. It is important to distintuish between client and server state. Every client has it's own client side context which is created by calling glXCreateContext() or glXImportContext(). In the case of glXCreateContext() a server context is also created. In the case of glXImportContext(), a server context is "imported". glXDestroyContext destroys both the client and server context. If the server context is current to another thread then the XID is freed (and the server context cannot subsequently be made current to any thread); the context itself is destroyed once it is no longer current. Issue: Should there be a way to get the list of XID's for a share list?