Articles / Linux ABI/SDK standards for…

Linux ABI/SDK standards for OpenGL/Mesa

A proposal for standardizing X11 OpenGL/Mesa ABI and SDK issues on Linux has been drafted by Jon Leech, an employee of SGI. Click the details link to read more.Jon Leech, who works for SGI has reported on the Linux/OpenGL Base working group. Jon Reports:
We've had a group (including representatives from LSB, Mesa, Metro Link, NVIDIA, PTC, Precision Insight, SGI, XFree86, and Xi Graphics) working on a proposal for standardizing X11 OpenGL/Mesa ABI and SDK issues on Linux. The purpose is to allow applications to build against any implementation following this standard and the resulting binaries to run against any other implementation; this interoperability will be increasingly important as the amount of 3D activity on Linux grows and the variety of drivers increases even further.

A mailing list has been created for further discussion and finalization of this proposal. We're unable to follow discussions in all the forums where this announcement is being made, so if you want to have an effect, please join this mailing list. We particularly solicit participation by ISVs writing OpenGL-based applications on Linux, IHVs writing OpenGL drivers on Linux, and Linux distributions.

For those interested, there are mailing lists. To initially subscribe to the list, send a message with body "subscribe oglbase-discuss" to external-majordomo@corp.sgi.com To participate in the list after you've subscribed, send messages to oglbase-discuss@corp.sgi.com. To unsubscribe to the list, send a message containing the body unsubscribe oglbase-discuss to external-majordomo@corp.sgi.com

Daniel Quinlan of TransMeta, the Steering Committee Chairman of the LSB Project refered us to Stuart Anderson of MetroLink for the offical LSB comment. Stuart confirmed that this was being developed outside of the LSB, but may later be implemented, here is what he had to say:

I'm the LSB rep in that group. This group is an excellent example of how groups can be formed to focus on specific problem domains, with the results being fed back into the LSB. The LSB is using the experience gained from working with this group to help define a model for establishing future working groups to be able to focus on other problem domains. This is exciting to see so many projects & vendors working together to ensure interoperability on Linux.

Editorial Comment: Hopefully, if this becomes part of the LSB, it will be an "X" layer, so that a smaller base layer can be used to build servers and other systems on.

Down to the Details!

Linux/OpenGL Base
Draft Version 0.9
September 7, 1999

Index

1. Overview and Goals

1.1. This document is intended to solve two related problems. First, defining the ABI and runtime environment for OpenGL under X11 on Linux. This will enable applications using the OpenGL API for rendering to run on a variety of underlying implementations transparently. The intent is to address all of open source, commercial closed binary, OpenGL SI-based, and Mesa-based implementations.

Second, defining the SDK for developing apps using OpenGL. This includes header file locations, conventions for use of extensions, etc.

It has similar goals to the Linux Standard Base, but focused much more narrowly: on the OpenGL API. Representatives from LSB are involved and ultimately this effort should be part of LSB.

1.2. Things we do not attempt to address include:

  • Internal implementation dependent issues - details of direct rendering, loadable driver modules, etc. This should all be hidden from the public interfaces by the implementation.
  • Operating systems other than Linux. BSD etc. are welcome to use whatever comes out of this project, but we are explicitly not trying to solve this problem for every free OS in the world.
  • Changes to the OpenGL API. The definition of OpenGL is controlled by the OpenGL Architecture Review Board, and we in no way challenge this. Very modest extensions specific to the Linux runtime environment may be needed, however.
  • Use of 3D outside the X11/GLX context. There are a variety of approaches (fxMesa, GGI, etc.) that again are welcome to use relevant parts of this project, but whose support is not part of its goals.

1.3. We believe the relevant areas have all been identified, but not all the decisions have been made. Many of the decisions are largely arbitrary (filenames and locations, for example) and although feedback on such areas will not be ignored, we are interested in finalizing this document soon.

1.4. Participants in this effort to date include people working at or involved with the following companies and open source projects:

  • Linux Standard Base
  • Mesa
  • Metro Link
  • NVIDIA
  • Parametric Technology Corporation
  • Precision Insight
  • SGI
  • XFree86
  • Xi Graphics

2. Calling Conventions

2.1. OpenGL already includes its own datatypes (GLint, GLshort, etc.) used in the API. Guaranteed minimum sizes are stated (see table 2.2 of the OpenGL Specification), but the actual choice of C datatype is left to the implementation. For our purposes, however, all implementations on a given binary architecture must have common definitions of these datatypes.

For the IA32 architecture, the definitions should be:

GL datatype Description gcc equivalent for IA32
GLboolean 8-bit boolean unsigned char
GLbyte signed 8-bit 2's-complement integer signed char
GLubyte unsigned 8-bit integer unsigned char
GLshort signed 16-bit 2's-complement integer short
GLushort unsigned 16-bit integer unsigned short
GLint signed 32-bit 2's-complement integer int
GLuint unsigned 32-bit integer unsigned int
GLsizei non-negative 32-bit binary integer size int
GLenum enumerated 32-bit value unsigned int
GLbitfield 32 bit bitfield unsigned int
GLfloat 32-bit IEEE754 floating-point float
GLclampf Same as GLfloat, but in range [0, 1] float
GLdouble 64-bit IEEE754 floating-point double
GLclampd Same as GLdouble, but in range [0, 1] double

Open Issue: Define GL datatypes for other supported Linux architectures - Alpha, PowerPC, MIPS, etc. (in general these will be identical to the IA32 types).
Note: We may want to suggest GLlong and GLulong as 64-bit datatypes for future OpenGL revisions.

2.2. Assembly-level call conventions must be universal. Since the OpenGL implementation may use C++ code internally (e.g. for GLU), this is potentially a serious problem. Static linking of C++ libraries used by OpenGL libraries will probably be required of the implementation (also see the Libraries section below)
Open Issue: Identify problem areas. Is the gcc/egcs split a problem?
What about static constructor/destructor issues when e.g. a C main() is linked against GLU?

3. Libraries

3.1. There are two link-level libraries. libGL includes the OpenGL and GLX entry points and in general depends on underlying hardware and/or X server dependent code that may or may not be incorporated into this library. libGLU includes the GLU utility routines and in general is hardware independent, using only the OpenGL API. Exact names of these libraries may vary depending on the underlying OpenGL version supported and on external naming conventions; for example, the LSB uses the convention libfoo.lsb.N where the lsb.N reflects the version of LSB in use. However, it's not clear we should be tied to a particular version of LSB.

Using non-LSB conventions, the library names proposed are:

  • OpenGL 1.1 and GLU 1.2: libGL.so.1.1 and libGLU.so.1.2
  • OpenGL 1.2 and GLU 1.3: libGL.so.1.2 and libGLU.so.1.3

In either case, libGL.so and libGLU.so would be symbolic links pointing to the most recent installed version of the libraries.

Using LSB conventions, the library names proposed are:

  • OpenGL 1.1 and GLU 1.2: libGL.1.1.lsb.N and libGLU.1.2.lsb.N
  • OpenGL 1.2 and GLU 1.3: libGL.1.2.lsb.N and libGLU.1.3.lsb.N

Open Issues: Choose library names and LSB/non-LSB naming convention.
Does LSB include symbolic links from generic to specific version numbers of libraries?

3.2. The libraries should be located in /usr/lib. /usr/lib/X11 or another X-specific location was considered, but existing practice on Linux and other platforms indicates that /usr/lib is preferable.
Note: This is a somewhat out of keeping with other X extensions, and driven by existing practice. This location could present some issues in having both X and non-X OpenGL implementations resident on the same platform.

3.3. C++ runtime environments are likely to be incompatible cross-platform, including both the standard C++ library location and entry points, and the semantics of issues such as static constructors and destructors. The LSB apparently mandates static linking of libraries which aren't already in LSB, but this could lead to problems with multiple C++ RTLs present in the same app using C++.
Open Issue: State requirements on GL libraries using C++ or other auxiliary libraries such that they won't interfere with apps also using those libraries.

3.4. Entry points supported by these libraries must include either of:

  • All OpenGL 1.1, GLU 1.2, and GLX 1.2 entry points
  • All OpenGL 1.2, GLU 1.3, GLX 1.3, and ARB_multitexture entry points

3.5. Because non-ARB extensions vary so widely and are constantly increasing in number, it's infeasible to require that they all be supported, and extensions can always be added to hardware drivers after the base link libraries are released. These drivers are dynamically loaded by libGL, so extensions not in the base library must also be obtained dynamically. We thus require that libGL also export an entry point notionally called

void (*glGetProcAddressEXT(GLubyte *))(...);

Open Issues: Should the call also take a GLXContext argument? At present it returns the appropriate function for the current context, just like its WGL counterpart.
Which functions can be returned by this query? Just GL and GLX? GLU is a client-side library sitting above the GL layer, so it probably doesn't make sense to be able to query GLU.

3.6. This function takes the string name of an extension entry point and returns a pointer to that entry point appropriate to the driver whose context is current. It is functionally identical to the wglGetProcAddress function supplied by the Windows OpenGL library.
Open Issue: Determine what non-ARB extensions, if any, should be standard entry points not requiring this dynamic lookup.

3.7. Thread safety - the ability to issue OpenGL calls to different graphics contexts from different application threads - may be required. There are unresolved issues regarding the thread model assumed by app and library code, and the performance implications of requiring threadsafe implementations are unclear at this point.
Open Issue: This issue needs to be explored in depth and recommendations made by people familiar with the relevant aspects of GLX, DRI, glibc, pthreads, and the Linux kernel.

4. Header Files

4.1. The following header files are required:

  • - OpenGL
  • - GLX
  • - GLU
  • - Extensions

These headers should properly define prototypes and enumerants for use by applications written in either C or C++. Other language bindings are not addressed at this time.
Note: This may present some issues in having both X and non-X OpenGL implementations resident on the same platform.

4.2. The header files must be located in /usr/include/GL. /usr/include/X11/GL was considered and rejected in the same fashion as library locations in section 3.2 above.

4.3. The required headers must not pull in internal headers or headers from other packages where that would cause unexpected namespace pollution (for example, on IRIX glx.h pulls in ). Likewise the required headers must be protected against multiple inclusion and should not themselves include any headers that are not so protected.

4.4. gl.h should include the prototype of the glGetProcAddressEXT extension described above.
Open Issues: Define the exact prototype and write the GL extension specification for it.
Should this really be a GL extension? It was previously put in GLX but doesn't really belong there, either, because it's a metafunction returning information about GL and GLX. It's intended to allow access to all driver entry points, but will need to be found in libGL since that's where dynamic driver loading will typically happen. An alternative is to create a new GL namespace and call the query e.g. glextGetProcAddress() and the header file version number (see section 5.2) GLEXT_VERSION.

4.5. All OpenGL 1.2 and ARB_multitexture, GLU 1.3, and GLX 1.3 entry points and enumerants must be present in the corresponding header files gl.h, glu.h, and glx.h, even if only OpenGL 1.1 is provided by the associated runtime libraries.
Note: This requirement anticipates wide availability of OpenGL 1.2 capable hardware and drivers, easing writing apps for them today. Since applications should already check both compile and runtime OpenGL version numbers, no problems due to lacking support for 1.2 are expected.

4.6. Non-ARB extensions are in general to be defined in glext.h. If they are also defined in one of the other required headers, this must be done conditionally so that multiple definition problems don't occur.

4.7. Vendor-specific shortcuts, such as macros for higher performance GL entry points, are intrinsically unportable. These should not be present in the required header files, but instead in a vendor-specific header file that requires explicit effort to access, such as defining a vendor-specific preprocessor symbol. Likewise vendors who are not willing to include their extensions in glext.h must isolate those extensions in vendor-specific headers.

5. Extension Headers

5.1. Providing prototypes and enumerants for OpenGL extensions is challenging because of the expected wide variety of hardware drivers, continuing creation of extensions, and multiple sources of header files on Linux OpenGL implementations. Some extensions will be supported only for a specific source base, such as Mesa, and some will be supported only for a specific hardware driver. This situation does not lend itself easily to independent maintenance of header files definining the extensions.

Instead, we require a single header file defining essentially all extensions be supplied from a central point and updated on a continuing basis as new extensions are added to the OpenGL extension registry (which is similarly centrally maintained). Probably the central point will be a download site on www.opengl.org.

An initial version of this header has been defined by Michael Gold; it is available for examination at http://www.berkelium.com/OpenGL/examples/glext.h. At present this header is targeted at Windows OpenGL implementations; we will enhance it for Linux and other crossplatform use.
Note: glext.h is an exception to the Linux-centric nature of this document, since it is already being used on other platforms.

5.2. The centrally maintained glext.h will be continually updated, so version creep is expected. This could cause problems for open source projects distributing source code. The proper solution is for users to update glext.h to the latest version, but versioning has proven helpful with other extensible aspects of OpenGL. Therefore glext.h must include a preprocessor version symbol GL_GLEXT_VERSION_EXT, enabling apps to do something like:

#include
#if GL_GLEXT_VERSION_EXT < 42
#error "I need a newer . Please download it from opengl.org."
#endif

Note: Applications should not use this version number to test for presence or absence of specific extension prototypes. Always use the extension-specific symbols described in section 5.3.

5.3. Only extensions whose fully documented specifications have been made available to the extension registry and whose authors have committed to shipping them in their drivers will be included in glext.h. The required format for extensions in glext.h is:

#ifndef GL_EXT_extensionname
#define GL_EXT_extensionname 1
Define enumerants specific to this extension
Define prototypes specific to this extension
Typedef function pointers for entry points dynamically obtained with glGetProcAddressEXT
#endif

The preprocessor symbol protecting the extension declaration must be the same as the name string identifying the extension at runtime and in the extension registry.
Note: All OpenGL extensions that are shipping should have a full extension specification in the extension registry on opengl.org. Vendors failing to document and specify their extensions will not be allowed to incorporate the resulting inadequate interfaces into this work.
Open Issue: Other structures for the extension prototypes have been suggested, such as having separate header files for each extension. Having both structures may be preferable, but it imposes more maintenance burden on the people responsible for glext.h.

6. Feedback

A mailing list has been created for further discussion and finalization of this proposal. We particularly welcome participation by ISVs writing OpenGL-based applications on Linux and IHVs writing OpenGL drivers on Linux.

To initially subscribe to the list, send a message with body

subscribe oglbase-discuss

to external-majordomo@corp.sgi.com

To participate in the list after you've subscribed, send messages to oglbase-discuss@corp.sgi.com.

To unsubscribe to the list, send a message containing the body

unsubscribe oglbase-discuss

to external-majordomo@corp.sgi.com

Screenshot

Project Spotlight

Kigo Video Converter Ultimate for Mac

A tool for converting and editing videos.

Screenshot

Project Spotlight

Kid3

An efficient tagger for MP3, Ogg/Vorbis, and FLAC files.