Version 0.2
July 19, 2001
Editor: Jon Leech, SGI
1.1. This document is intended to solve three related problems. First, defining the ABIs and runtime environment for applications using OpenML. This will enable applications using the OpenML APIs for rendering to run on a variety of underlying implementations transparently.
Second, defining the Software Development Kit (SDK) (for developing apps using OpenGL. This includes header file locations, conventions for use of extensions, etc.
Finally, defining the Device Driver Interface (DDI) for appropriate portions of OpenML.
These standards target multiple platforms. For Linux and Microsoft Windows, where multiple vendors will supply OpenML implementations, the standards are proscriptive; all conformant OpenML implementations must satisfy the ABI, SDK, and DDI requirements. For other platforms (at this time, vendor-specific Unix platforms such as IRIX or Solaris), only some parts of the standards are required, while others are recommended, for maximal portability between platforms.
It may eventually be appropriate to share these standards with broader standards bodies such as the Free Standards Group on Linux.
1.2. There are many open issues in the initial draft; this is intended for discussion and extensive modification. Open issues are summarized in the appendix. Some decisions are largely arbitrary (filenames and file locations, for example), and in those cases we have been guided by existing practice where possible.
1.3. This document is intended to become part of the OpenML Specification on its approval, and is a joint work of the Khronos SIG.
OpenML requires implementations of several separate APIs: ML, MLdc, and OpenGL. For the most part, the ABIs, SDKs, and DDIs required for each of these APIs are not related, and are described separately. Interactions are documented where needed.
ML is the Media Library component of OpenML. It is a low-level API for accessing video and audio hardware.
MLdc is the Display Control component of OpenML. It manages multiple video channels, including aspects such as video formats, timing, gamma tables, etc.
OpenGL is the Graphics component of OpenML. It is a low-level API for performing 3D rendering. OpenGL is standardized separately from OpenML by the OpenGL Architecture Review Board; OpenML simply requires a specific version of OpenGL with a small number of added API extensions for managing video data.
Because OpenGL is a pre-existing API with shipping implementations, this document mostly refers to other standards (such as the OpenGL ABI for Linux) when defining OpenGL-specific standards.
This document defines ABIs and DDIs for the OpenML 1.0 APIs.
OPEN - need to define ML datatype required sizes, Windows / Linux / etc. conventions.
OPEN - need to define MLdc datatype required sizes, Windows / Linux / etc. conventions.
3.3.1. Linux - the OpenGL implementation must follow the calling and datatype conventions defined by the OpenGL ABI for Linux.
3.3.2. Windows - the OpenGL implementation must follow the calling and datatype conventions established de facto by Microsoft's OPENGL32.DLL and header files.
3.3.3. Other Platforms - calling conventions are platform-dependent. Datatype conventions are platform dependent so long as they satisfy the minimum size requirements of the OpenGL Specification.
Issues: Do we need to address C++ linking issues? Need more detail on calling conventions for Linux?
There is a single user-level ML link library. It includes ML entry points, and in general makes use of underlying hardware drivers for hardware device access. Hardware drivers may be incorporated into the link library, but in general they are loaded by the link library at runtime, and accessed through a Device Driver Interface defined below.
4.1.1 Linux - the link library has two names: that used on the ld command line, and the DT_SONAME within that library (specified by the -soname switch when linking the library), defining where it's looked up at runtime. Both forms must exist so that both linking and running will operate properly.
The DT_SONAME includes the ML major version number, and is libML.so.1. The link library name is libML.so. libML.so must be implemented as a symbolic link to libML.so.1. This allows future major revisions of ML to be implemented transparently to applications by simply changing the link; new applications will link with the new runtime library, while old, compiled applications will continue to use the old runtime.
Issues: do we need static link libraries?
Both ML libraries must be located in /usr/lib.
4.1.2. Windows - the link library is named ML32.DLL. It must be located in \System\???
Issues: What the heck are the Windows system library conventions, anyway? And will we run into the horrid Windows XP "driver signing" mess by mandating the library live in \System?
4.1.3. Other Platforms - the base name of the library should be libML, so that crossplatform Unix build systems can always use "-lML" on their link lines. The ML major version number (1) should be incorporated into the link library name in appropriate fashion. The library should be shared, and should use whatever the platform's library versioning mechanism is to cause compiled applications to resolve to resolve to the correct version of libML (e.g. the one they were linked against), even if a newer major version has become the default.
The ML library is typically located in /usr/lib, although platform conventions may override this. The important point is that there be a single, standard location for the link library on that platform.
There is a single user-level MLdc link library. It includes MLdc entry points, and in general makes use of underlying hardware drivers for hardware device access. Hardware drivers may be incorporated into the link library, but in general they are loaded by the link library or the window system at runtime, and accessed through a Device Driver Interface defined below.
4.2.1 Linux - the link library has two names: that used on the ld command line, and the DT_SONAME within that library (specified by the -soname switch when linking the library), defining where it's looked up at runtime. Both forms must exist so that both linking and running will operate properly.
The DT_SONAME includes the MLdc major version number, and is libMLdc.so.1. The link library name is libMLdc.so. libMLdc.so must be implemented as a symbolic link to libMLdc.so.1. This allows future major revisions of MLdc to be implemented transparently to applications by simply changing the link; new applications will link with the new runtime library, while old, compiled applications will continue to use the old runtime.
Issues: do we need static link libraries?
Both MLdc libraries must be located in /usr/lib.
4.2.2. Windows - the link library is named MLDC32.DLL. It must be located in \System\???
Issues: As for ML32.DLL - decide where the library lives. "driver signing" mess by mandating the library live in \System?
4.2.3. Other Platforms - the base name of the library should be libMLdc, so that crossplatform Unix build systems can always use "-lMLdc" on their link lines. The MLdc major version number (1) should be incorporated into the link library name in appropriate fashion. The library should be shared, and should use whatever the platform's library versioning mechanism is to cause compiled applications to resolve to resolve to the correct version of libMLdc (e.g. the one they were linked against), even if a newer major version has become the default.
The MLdc library is typically located in /usr/lib, although platform conventions may override this. The important point is that there be a single, standard location for the link library on that platform.
There is a single user-level OpenGL link library. It includes OpenGL entry points, and in general makes use of underlying hardware drivers for hardware device access. Hardware drivers may be incorporated into the link library, but in general they are loaded by the link library or the window system at runtime, and accessed through a Device Driver Interface defined below.
4.3.1 Linux - the OpenGL library naming, location, and versioning conventions are as defined by the OpenGL ABI for Linux.
4.3.2. Windows - the OpenGL library is shipped by Microsoft in \System\OPENGL32.DLL.
4.3.3. Other Platforms - follow existing conventions on those platforms (typically the OpenGL library is linked via "-lGL"). New platforms without existing conventions should follow the Linux conventions insofar as possible.
5.1.1. The following header files are required for ML:
Language bindings supported - TBD (C and C++?)
Header locations - TBD (presumably /usr/include/ML on Linux/Unix)
Header contents - TBD (ML 1.0)
5.2.1. The following header files are required for MLdc:
Language bindings supported - TBD (C and C++?)
Header locations - TBD (/usr/include/ML? check w/Cary)
Header contents - TBD (MLdc 1.0)
5.3.1 Linux - the OpenGL header file requirements are as defined by the OpenGL ABI for Linux. In addition, glext.h and glxext.h must define interfaces for the OpenGL and GLX extensions, respectively, required by OpenML 1.0.
5.3.2. Windows - the following header files are required:
gl.h, glu.h, and wgl.h are typically supplied by Microsoft, while glext.h and wglext.h should be obtained from the OpenGL extension registry. glext.h and wglext.h must define interfaces for the OpenGL and WGL extensions, respectively, required by OpenML 1.0.
Header locations - TBD (check existing practice for MS-supplied headers; define a location for others).
5.3.3. Other Platforms - follow existing conventions on those platforms (typically header files are placed in /usr/include/GL). However, all implementations must provide glext.h and, for implementations on the X Window System and GLX, glxext.h, and all OpenML 1.0 extensions must be defined in those headers.
New platforms without existing conventions should follow the Linux conventions insofar as possible.
Required header files must not pull in internal headers or headers from other packages where that would cause unexpected namespace pollution. They must be protected against multiple inclusion and should not themselves include any headers that are not so protected.
Vendor-specific shortcuts, such as macros for higher performance GL entry points, are intrinsically unportable. These should not be present in any required header files, but instead in a vendor-specific header file that requires explicit effort by developers to access, such as defining a vendor-specific preprocessor symbol or including a vendor-specific header file.
The ML, MLdc, and OpenGL APIs may be extended by individual vendors or groups of vendors to provide functionality specific to some implementations. Such extensions take the form of new entry points and/or new parameters to existing functions.
In general each API will be exposed to applications as a single link library, with the library dispatching functions to hardware-specific drivers as appropriate. If vendors providing extensions each provided a modified link library, binary applications could not reliably be moved from system to system, because incompatible interfaces would be provided depending on the source of the library.
To deal with this, each API provides an extension mechanism which lets applications obtain new entry points (pointers to functions within driver modules) dynamically at runtime.
Similarly, if each vendor provided modified header files adding their extensions, it would be difficult to build applications consistently in different environments. To deal with this, each API defines the structure of a extension header which defines interfaces for all known extensions and can be maintained at a central source.
6.2.1. The ML extension mechanism and extension headers are not defined yet; this will be done for OpenML 1.1.
6.3.1. Need to insert MLdc extension mechanism.
6.4.1. Linux - The OpenGL ABI for Linux defines the required extension functionality, including the glXGetProcAddressARB function (provided by the GLX_ARB_get_proc_address extension) used to query extension interfaces. The glext.h and glxext.h headers from the OpenGL extension registry define interfaces to known OpenGL and GLX extensions.
6.4.2. Windows - WGL provides the wglGetProcAddress function used to query extension interfaces (unlike the GLX equivalent, returned function pointers are context dependent; portable code must be aware of this difference). glext.h (identical to the Linux version) and wglext.h headers from the OpenGL extension registry define interfaces to known OpenGL and WGL extensions.
6.4.3. Other Platforms - Unix platforms should follow the Linux conventions, providing the GLX_ARB_get_proc_address extension as well as glext.h and glxext.h. Other platforms should define an extension with similar functionality and provide glext.h; a companion extension header for window system interface extensions may also need to be provided.
TBD - waiting on dmSDK DDI.
TBD
Change Log