extensions/OML/abi.html - external/github.com/KhronosGroup/OpenGL-Registry - Git at Google

 <!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
 <html>
 <head>

 <title>OpenML ABI/DDI (DRAFT July 19, 2001)</title>

 <meta name="description" content="OpenML ABI/DDI standards">
 <meta name="keywords" content="OpenML, OpenGL, ABI, Linux">
 <meta name="owner" content="Jon Leech">

 <center>
 <h2> OpenML&reg; Application Binary Interface (ABI) and Device Driver
     Interface (DDI) Standards </h2>

 <p>Version 0.2<br>
    July 19, 2001<br>
    Editor: Jon Leech, SGI
 </center>

 <p><hr></p>

 <h2> Index </h2>

     <ul>
     <li><a href="#1">1. Overview and Goals </a>
     <li><a href="#2">2. OpenML Component APIs and Versions</a>
     <li><a href="#3">3. Calling Conventions</a>
     <li><a href="#4">4. Libraries</a>
     <li><a href="#5">5. Header Files</a>
     <li><a href="#6">6. Extension Mechanism and Extension Headers</a>
     <li><a href="#7">7. Device Driver Interfaces</a>
     <li><a href="#app">Appendix: Open Issues</a>
     <li><a href="#log">Change Log</a>
     </ul>

 <a name="1">
 <h2> 1. Overview and Goals  </h2>

 <p> 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.

 <p> Second, defining the Software Development Kit (SDK) (for developing
     apps using OpenGL. This includes header file locations, conventions
     for use of extensions, etc.

 <p> Finally, defining the Device Driver Interface (DDI) for appropriate
     portions of OpenML.

 <p> These standards target multiple platforms. For Linux and Microsoft
     Windows, where multiple vendors will supply OpenML implementations,
     the standards are <b>proscriptive</b>; 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 <b>recommended</b>, for maximal portability between
     platforms.

 <p> It may eventually be appropriate to share these standards with
     broader standards bodies such as the
     <a href="http://www.freestandards.org">Free Standards Group</a> on
     Linux.

 <p> 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 <a href="#app">appendix</a>. Some decisions are
     largely arbitrary (filenames and file locations, for example), and
     in those cases we have been guided by existing practice where
     possible.

 <p> 1.3. This document is intended to become part of the OpenML
     Specification on its approval, and is a joint work of the
     <a href="http://www.khronos.org">Khronos SIG</a>.</p>

 <a name="2">
 <h2> 2. OpenML Component APIs and Versions </h2>

 <h3> 2.1. Component APIs </h3>

 <p> OpenML requires implementations of several separate APIs: <b>ML</b>,
     <b>MLdc</b>, and <b>OpenGL</b>. 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.

 <h3> 2.2. ML </h3>

 <p> ML is the <i>Media Library</i> component of OpenML. It is a
     low-level API for accessing video and audio hardware.

 <h3> 2.3. MLdc </h3>

 <p> MLdc is the <i>Display Control</i> component of OpenML. It manages
     multiple video <i>channels</i>, including aspects such as video
     formats, timing, gamma tables, etc.

 <h3> 2.4. OpenGL </h3>

 <p> OpenGL is the <i>Graphics</i> component of OpenML. It is a low-level
     API for performing 3D rendering. OpenGL is standardized separately
     from OpenML by the <a href="http://www.opengl.org/">OpenGL
     Architecture Review Board</a>; OpenML simply requires a specific
     version of OpenGL with a small number of added API extensions for
     managing video data.

 <p> Because OpenGL is a pre-existing API with shipping implementations,
     this document mostly refers to other standards (such as the <a
     href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
     Linux</a>) when defining OpenGL-specific standards.</p>

 <h3> 2.5. Versions </h3>

 <p> This document defines ABIs and DDIs for the OpenML 1.0 APIs. </p>

 <a name="3">
 <h2> 3. Calling Conventions </h2>

 <h3> 3.1. ML Calling Conventions </h3>

 <p> <b>OPEN</b> - need to define ML datatype required sizes, Windows / Linux
     / etc. conventions.

 <h3> 3.2. MLdc Calling Conventions </h3>

 <p> <b>OPEN</b> - need to define MLdc datatype required sizes, Windows /
     Linux / etc. conventions.

 <h3> 3.3. OpenGL Calling Conventions </h3>

 <p> 3.3.1. <b>Linux</b> - the OpenGL implementation must follow the
     calling and datatype conventions defined by the <a
     href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
     Linux</a>.

 <p> 3.3.2. <b>Windows</b> - the OpenGL implementation must follow the
     calling and datatype conventions established <i>de facto</i> by
     Microsoft's <tt>OPENGL32.DLL</tt> and header files.

 <p> 3.3.3. <b>Other Platforms</b> - calling conventions are
     platform-dependent. Datatype conventions are platform dependent so
     long as they satisfy the minimum size requirements of the OpenGL
     Specification.

 <p> <b>Issues:</b> Do we need to address C++ linking issues? Need more
     detail on calling conventions for Linux?</p>

 <a name="4">
 <h2> 4. Libraries </h2>

 <h3> 4.1. ML Library </h3>

 <p> 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 <a href="#DDIsection">Device
     Driver Interface</a> defined below.

 <p> 4.1.1 <b>Linux</b> - the link library has two names: that used on
     the ld command line, and the <tt>DT_SONAME</tt> within that library
     (specified by the <i>-soname</i> 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.

 <p> The <tt>DT_SONAME</tt> includes the ML major version number, and is
     <tt>libML.so.1</tt>. The <i>link library name</i> is
     <tt>libML.so</tt>. <tt>libML.so</tt> must be implemented as a
     symbolic link to <tt>libML.so.1</tt>. 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.

 <p> <b>Issues:</b> do we need static link libraries?

 <p> Both ML libraries must be located in <tt>/usr/lib</tt>.

 <p> 4.1.2. <b>Windows</b> - the link library is named <tt>ML32.DLL</tt>.
     It must be located in <tt>\System\???</tt>

 <p> <b>Issues:</b> What the heck are the Windows system library
     conventions, anyway? And will we run into the horrid Windows XP
     &quot;driver signing&quot; mess by mandating the library live in
     <tt>\System</tt>?

 <p> 4.1.3. <b>Other Platforms</b> - the base name of the library should
     be <tt>libML</tt>, 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
     <tt>libML</tt> (e.g. the one they were linked against), even if a
     newer major version has become the default.

 <p> The ML library is typically located in <tt>/usr/lib</tt>, although
     platform conventions may override this. The important point is that
     there be a single, standard location for the link library on that
     platform.

 <h3> 4.2. MLdc Library </h3>

 <p> 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 <a href="#DDIsection">Device Driver Interface</a> defined
     below.

 <p> 4.2.1 <b>Linux</b> - the link library has two names: that used on
     the ld command line, and the <tt>DT_SONAME</tt> within that library
     (specified by the <i>-soname</i> 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.

 <p> The <tt>DT_SONAME</tt> includes the MLdc major version number, and
     is <tt>libMLdc.so.1</tt>. The <i>link library name</i> is
     <tt>libMLdc.so</tt>. <tt>libMLdc.so</tt> must be implemented as a
     symbolic link to <tt>libMLdc.so.1</tt>. 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.

 <p> <b>Issues:</b> do we need static link libraries?

 <p> Both MLdc libraries must be located in <tt>/usr/lib</tt>.

 <p> 4.2.2. <b>Windows</b> - the link library is named
     <tt>MLDC32.DLL</tt>. It must be located in <tt>\System\???</tt>

 <p> <b>Issues:</b> As for <tt>ML32.DLL</tt> - decide where
     the library lives.
     &quot;driver signing&quot; mess by mandating the library live in
     <tt>\System</tt>?

 <p> 4.2.3. <b>Other Platforms</b> - the base name of the library should
     be <tt>libMLdc</tt>, 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 <tt>libMLdc</tt> (e.g. the one they were linked against), even if
     a newer major version has become the default.

 <p> The MLdc library is typically located in <tt>/usr/lib</tt>, although
     platform conventions may override this. The important point is that
     there be a single, standard location for the link library on that
     platform.

 <h3> 4.3. OpenGL Library </h3>

 <p> 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 <a href="#DDIsection">Device Driver Interface</a> defined
     below.

 <p> 4.3.1 <b>Linux</b> - the OpenGL library naming, location, and
     versioning conventions are as defined by the <a
     href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
     Linux</a>.

 <p> 4.3.2. <b>Windows</b> - the OpenGL library is shipped by Microsoft
     in <tt>\System\OPENGL32.DLL</tt>.

 <p> 4.3.3. <b>Other Platforms</b> - 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.

 <h3> 4.4. Additional Issues </h3>

 <p> <ul>
     <li> C++ runtime issues on Linux?
     <li> Entry points guaranteed in each library.
     <li> Thread safety.
     <li> Transitive linking of required libraries.
     </ul>

 <a name="5">
 <h2> 5. Header Files </h2>

 <h3> 5.1. ML Header Files </h3>

 <p> 5.1.1. The following header files are required for ML:

     <ul>
     <li> <b>TBD</b>
     </ul>

 <p> Language bindings supported - <b>TBD</b> (C and C++?)

 <p> Header locations - <b>TBD</b> (presumably /usr/include/ML on
     Linux/Unix)

 <p> Header contents - <b>TBD</b> (ML 1.0)

 <h3> 5.2. MLdc Header Files</h3>

 <p> 5.2.1. The following header files are required for MLdc:

     <ul>
     <li> <b>TBD</b>
     </ul>

 <p> Language bindings supported - <b>TBD</b> (C and C++?)

 <p> Header locations - <b>TBD</b> (/usr/include/ML? check w/Cary)

 <p> Header contents - <b>TBD</b> (MLdc 1.0)

 <h3> 5.3. OpenGL Header Files </h3>

 <p> 5.3.1 <b>Linux</b> - the OpenGL header file requirements are as
     defined by the <a
     href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
     Linux</a>. In addition, <tt>glext.h</tt> and <tt>glxext.h</tt> must
     define interfaces for the OpenGL and GLX extensions, respectively,
     required by OpenML 1.0.

 <p> 5.3.2. <b>Windows</b> - the following header files
     are required:

     <ul>
     <li> <tt>&lt;GL/gl.h&gt;</tt> - OpenGL
     <li> <tt>&lt;GL/wgl.h&gt;</tt> - WGL
     <li> <tt>&lt;GL/glu.h&gt;</tt> - GLU
     <li> <tt>&lt;GL/glext.h&gt;</tt> - OpenGL Extensions
     <li> <tt>&lt;GL/wglext.h&gt;</tt> - WGL Extensions
     </ul>

 <p> gl.h, glu.h, and wgl.h are typically supplied by Microsoft,
     while <tt>glext.h</tt> and <tt>wglext.h</tt> should be obtained from
     the OpenGL extension registry. <tt>glext.h</tt> and
     <tt>wglext.h</tt> must define interfaces for the OpenGL and WGL
     extensions, respectively, required by OpenML 1.0.

 <p> Header locations - <b>TBD</b> (check existing practice for
     MS-supplied headers; define a location for others).

 <p> 5.3.3. <b>Other Platforms</b> - follow existing conventions on those
     platforms (typically header files are placed in
     <tt>/usr/include/GL</tt>). However, all implementations must provide
     <tt>glext.h</tt> and, for implementations on the X Window System and
     GLX, <tt>glxext.h</tt>, and all OpenML 1.0 extensions must be
     defined in those headers.

 <p> New platforms without existing conventions should follow the Linux
     conventions insofar as possible.

 <h3> 5.4. General Issues </h3>

 <p> 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.

 <p> Vendor-specific shortcuts, such as macros for higher performance GL
     entry points, are intrinsically unportable. These should <b>not</b>
     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.</p>

 <!-- <font face="Arial" size="2">yadda yadda</font> -->

 <a name="6">
 <h2> 6. Extension Mechanism and Extension Headers </h2>

 <h3> 6.1. General Requirements </h3>

 <p> 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.

 <p> 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.

 <p> To deal with this, each API provides an <i>extension mechanism</i>
     which lets applications obtain new entry points (pointers to
     functions within driver modules) dynamically at runtime.

 <p> 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 <i>extension header</i> which defines
     interfaces for all known extensions and can be maintained at a
     central source.

 <h3> 6.2. ML Extensions </h3>

 <p> 6.2.1. The ML extension mechanism and extension headers
     are not defined yet; this will be done for OpenML 1.1.

 <h3> 6.3. MLdc Extensions </h3>

 <p> 6.3.1. <i>Need to insert MLdc extension mechanism</i>.

 <h3> 6.4. OpenGL Extensions </h3>

 <p> 6.4.1. <b>Linux</b> - The OpenGL ABI for Linux defines the required
     extension functionality, including the <b>glXGetProcAddressARB</b>
     function (provided by the <tt>GLX_ARB_get_proc_address</tt>
     extension) used to query extension interfaces. The <tt>glext.h</tt>
     and <tt>glxext.h</tt> headers from the OpenGL extension registry
     define interfaces to known OpenGL and GLX extensions.

 <p> 6.4.2. <b>Windows</b> - WGL provides the <b>wglGetProcAddress</b>
     function used to query extension interfaces (unlike the GLX
     equivalent, returned function pointers are <i>context dependent</i>;
     portable code must be aware of this difference). <tt>glext.h</tt>
     (identical to the Linux version) and <tt>wglext.h</tt> headers from
     the OpenGL extension registry define interfaces to known OpenGL and
     WGL extensions.

 <p> 6.4.3. <b>Other Platforms</b> - Unix platforms should follow the
     Linux conventions, providing the <tt>GLX_ARB_get_proc_address</tt>
     extension as well as <tt>glext.h</tt> and <tt>glxext.h</tt>. Other
     platforms should define an extension with similar functionality and
     provide <tt>glext.h</tt>; a companion extension header for window
     system interface extensions may also need to be provided. </p>

 <a name="7">
 <h2> 7. Device Driver Interfaces </h2>

 <p> <b>TBD</b> - waiting on dmSDK DDI.


 <p><hr></p>

 <a name="app">
 <h2> Appendix: Open Issues </h2>

 <p> <b>TBD</b>

 <!-- <p><a name="issue2.1">
     <b>Section 2.1</b>:
     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 <tt>GLlong</tt> and
     <tt>GLulong</tt> as 64-bit datatypes for future OpenGL revisions.
 -->


 <a name="log">
 <h2> Change Log </h2>

 <ul>
 <li> 2001/07/19 - Added extension mechanism section.
 <li> 2001/04/17 - Initial version.
 </ul>

 </body>
 </html>
	<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
	<html>
	<head>

	<title>OpenML ABI/DDI (DRAFT July 19, 2001)</title>

	<meta name="description" content="OpenML ABI/DDI standards">
	<meta name="keywords" content="OpenML, OpenGL, ABI, Linux">
	<meta name="owner" content="Jon Leech">

	<center>
	<h2> OpenML® Application Binary Interface (ABI) and Device Driver
	Interface (DDI) Standards </h2>

	<p>Version 0.2<br>
	July 19, 2001<br>
	Editor: Jon Leech, SGI
	</center>

	<p><hr></p>

	<h2> Index </h2>

	<ul>
	<li><a href="#1">1. Overview and Goals </a>
	<li><a href="#2">2. OpenML Component APIs and Versions</a>
	<li><a href="#3">3. Calling Conventions</a>
	<li><a href="#4">4. Libraries</a>
	<li><a href="#5">5. Header Files</a>
	<li><a href="#6">6. Extension Mechanism and Extension Headers</a>
	<li><a href="#7">7. Device Driver Interfaces</a>
	<li><a href="#app">Appendix: Open Issues</a>
	<li><a href="#log">Change Log</a>
	</ul>

	<a name="1">
	<h2> 1. Overview and Goals </h2>

	<p> 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.

	<p> Second, defining the Software Development Kit (SDK) (for developing
	apps using OpenGL. This includes header file locations, conventions
	for use of extensions, etc.

	<p> Finally, defining the Device Driver Interface (DDI) for appropriate
	portions of OpenML.

	<p> These standards target multiple platforms. For Linux and Microsoft
	Windows, where multiple vendors will supply OpenML implementations,
	the standards are <b>proscriptive</b>; 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 <b>recommended</b>, for maximal portability between
	platforms.

	<p> It may eventually be appropriate to share these standards with
	broader standards bodies such as the
	<a href="http://www.freestandards.org">Free Standards Group</a> on
	Linux.

	<p> 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 <a href="#app">appendix</a>. Some decisions are
	largely arbitrary (filenames and file locations, for example), and
	in those cases we have been guided by existing practice where
	possible.

	<p> 1.3. This document is intended to become part of the OpenML
	Specification on its approval, and is a joint work of the
	<a href="http://www.khronos.org">Khronos SIG</a>.</p>

	<a name="2">
	<h2> 2. OpenML Component APIs and Versions </h2>

	<h3> 2.1. Component APIs </h3>

	<p> OpenML requires implementations of several separate APIs: <b>ML</b>,
	<b>MLdc</b>, and <b>OpenGL</b>. 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.

	<h3> 2.2. ML </h3>

	<p> ML is the <i>Media Library</i> component of OpenML. It is a
	low-level API for accessing video and audio hardware.

	<h3> 2.3. MLdc </h3>

	<p> MLdc is the <i>Display Control</i> component of OpenML. It manages
	multiple video <i>channels</i>, including aspects such as video
	formats, timing, gamma tables, etc.

	<h3> 2.4. OpenGL </h3>

	<p> OpenGL is the <i>Graphics</i> component of OpenML. It is a low-level
	API for performing 3D rendering. OpenGL is standardized separately
	from OpenML by the <a href="http://www.opengl.org/">OpenGL
	Architecture Review Board</a>; OpenML simply requires a specific
	version of OpenGL with a small number of added API extensions for
	managing video data.

	<p> Because OpenGL is a pre-existing API with shipping implementations,
	this document mostly refers to other standards (such as the <a
	href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
	Linux</a>) when defining OpenGL-specific standards.</p>

	<h3> 2.5. Versions </h3>

	<p> This document defines ABIs and DDIs for the OpenML 1.0 APIs. </p>

	<a name="3">
	<h2> 3. Calling Conventions </h2>

	<h3> 3.1. ML Calling Conventions </h3>

	<p> <b>OPEN</b> - need to define ML datatype required sizes, Windows / Linux
	/ etc. conventions.

	<h3> 3.2. MLdc Calling Conventions </h3>

	<p> <b>OPEN</b> - need to define MLdc datatype required sizes, Windows /
	Linux / etc. conventions.

	<h3> 3.3. OpenGL Calling Conventions </h3>

	<p> 3.3.1. <b>Linux</b> - the OpenGL implementation must follow the
	calling and datatype conventions defined by the <a
	href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
	Linux</a>.

	<p> 3.3.2. <b>Windows</b> - the OpenGL implementation must follow the
	calling and datatype conventions established <i>de facto</i> by
	Microsoft's <tt>OPENGL32.DLL</tt> and header files.

	<p> 3.3.3. <b>Other Platforms</b> - calling conventions are
	platform-dependent. Datatype conventions are platform dependent so
	long as they satisfy the minimum size requirements of the OpenGL
	Specification.

	<p> <b>Issues:</b> Do we need to address C++ linking issues? Need more
	detail on calling conventions for Linux?</p>

	<a name="4">
	<h2> 4. Libraries </h2>

	<h3> 4.1. ML Library </h3>

	<p> 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 <a href="#DDIsection">Device
	Driver Interface</a> defined below.

	<p> 4.1.1 <b>Linux</b> - the link library has two names: that used on
	the ld command line, and the <tt>DT_SONAME</tt> within that library
	(specified by the <i>-soname</i> 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.

	<p> The <tt>DT_SONAME</tt> includes the ML major version number, and is
	<tt>libML.so.1</tt>. The <i>link library name</i> is
	<tt>libML.so</tt>. <tt>libML.so</tt> must be implemented as a
	symbolic link to <tt>libML.so.1</tt>. 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.

	<p> <b>Issues:</b> do we need static link libraries?

	<p> Both ML libraries must be located in <tt>/usr/lib</tt>.

	<p> 4.1.2. <b>Windows</b> - the link library is named <tt>ML32.DLL</tt>.
	It must be located in <tt>\System\???</tt>

	<p> <b>Issues:</b> 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
	<tt>\System</tt>?

	<p> 4.1.3. <b>Other Platforms</b> - the base name of the library should
	be <tt>libML</tt>, 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
	<tt>libML</tt> (e.g. the one they were linked against), even if a
	newer major version has become the default.

	<p> The ML library is typically located in <tt>/usr/lib</tt>, although
	platform conventions may override this. The important point is that
	there be a single, standard location for the link library on that
	platform.

	<h3> 4.2. MLdc Library </h3>

	<p> 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 <a href="#DDIsection">Device Driver Interface</a> defined
	below.

	<p> 4.2.1 <b>Linux</b> - the link library has two names: that used on
	the ld command line, and the <tt>DT_SONAME</tt> within that library
	(specified by the <i>-soname</i> 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.

	<p> The <tt>DT_SONAME</tt> includes the MLdc major version number, and
	is <tt>libMLdc.so.1</tt>. The <i>link library name</i> is
	<tt>libMLdc.so</tt>. <tt>libMLdc.so</tt> must be implemented as a
	symbolic link to <tt>libMLdc.so.1</tt>. 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.

	<p> <b>Issues:</b> do we need static link libraries?

	<p> Both MLdc libraries must be located in <tt>/usr/lib</tt>.

	<p> 4.2.2. <b>Windows</b> - the link library is named
	<tt>MLDC32.DLL</tt>. It must be located in <tt>\System\???</tt>

	<p> <b>Issues:</b> As for <tt>ML32.DLL</tt> - decide where
	the library lives.
	"driver signing" mess by mandating the library live in
	<tt>\System</tt>?

	<p> 4.2.3. <b>Other Platforms</b> - the base name of the library should
	be <tt>libMLdc</tt>, 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 <tt>libMLdc</tt> (e.g. the one they were linked against), even if
	a newer major version has become the default.

	<p> The MLdc library is typically located in <tt>/usr/lib</tt>, although
	platform conventions may override this. The important point is that
	there be a single, standard location for the link library on that
	platform.

	<h3> 4.3. OpenGL Library </h3>

	<p> 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 <a href="#DDIsection">Device Driver Interface</a> defined
	below.

	<p> 4.3.1 <b>Linux</b> - the OpenGL library naming, location, and
	versioning conventions are as defined by the <a
	href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
	Linux</a>.

	<p> 4.3.2. <b>Windows</b> - the OpenGL library is shipped by Microsoft
	in <tt>\System\OPENGL32.DLL</tt>.

	<p> 4.3.3. <b>Other Platforms</b> - 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.

	<h3> 4.4. Additional Issues </h3>

	<p> <ul>
	<li> C++ runtime issues on Linux?
	<li> Entry points guaranteed in each library.
	<li> Thread safety.
	<li> Transitive linking of required libraries.
	</ul>

	<a name="5">
	<h2> 5. Header Files </h2>

	<h3> 5.1. ML Header Files </h3>

	<p> 5.1.1. The following header files are required for ML:

	<ul>
	<li> <b>TBD</b>
	</ul>

	<p> Language bindings supported - <b>TBD</b> (C and C++?)

	<p> Header locations - <b>TBD</b> (presumably /usr/include/ML on
	Linux/Unix)

	<p> Header contents - <b>TBD</b> (ML 1.0)

	<h3> 5.2. MLdc Header Files</h3>

	<p> 5.2.1. The following header files are required for MLdc:

	<ul>
	<li> <b>TBD</b>
	</ul>

	<p> Language bindings supported - <b>TBD</b> (C and C++?)

	<p> Header locations - <b>TBD</b> (/usr/include/ML? check w/Cary)

	<p> Header contents - <b>TBD</b> (MLdc 1.0)

	<h3> 5.3. OpenGL Header Files </h3>

	<p> 5.3.1 <b>Linux</b> - the OpenGL header file requirements are as
	defined by the <a
	href="http://oss.sgi.com/projects/ogl-sample/ABI/">OpenGL ABI for
	Linux</a>. In addition, <tt>glext.h</tt> and <tt>glxext.h</tt> must
	define interfaces for the OpenGL and GLX extensions, respectively,
	required by OpenML 1.0.

	<p> 5.3.2. <b>Windows</b> - the following header files
	are required:

	<ul>
	<li> <tt><GL/gl.h></tt> - OpenGL
	<li> <tt><GL/wgl.h></tt> - WGL
	<li> <tt><GL/glu.h></tt> - GLU
	<li> <tt><GL/glext.h></tt> - OpenGL Extensions
	<li> <tt><GL/wglext.h></tt> - WGL Extensions
	</ul>

	<p> gl.h, glu.h, and wgl.h are typically supplied by Microsoft,
	while <tt>glext.h</tt> and <tt>wglext.h</tt> should be obtained from
	the OpenGL extension registry. <tt>glext.h</tt> and
	<tt>wglext.h</tt> must define interfaces for the OpenGL and WGL
	extensions, respectively, required by OpenML 1.0.

	<p> Header locations - <b>TBD</b> (check existing practice for
	MS-supplied headers; define a location for others).

	<p> 5.3.3. <b>Other Platforms</b> - follow existing conventions on those
	platforms (typically header files are placed in
	<tt>/usr/include/GL</tt>). However, all implementations must provide
	<tt>glext.h</tt> and, for implementations on the X Window System and
	GLX, <tt>glxext.h</tt>, and all OpenML 1.0 extensions must be
	defined in those headers.

	<p> New platforms without existing conventions should follow the Linux
	conventions insofar as possible.

	<h3> 5.4. General Issues </h3>

	<p> 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.

	<p> Vendor-specific shortcuts, such as macros for higher performance GL
	entry points, are intrinsically unportable. These should <b>not</b>
	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.</p>

	<!-- <font face="Arial" size="2">yadda yadda</font> -->

	<a name="6">
	<h2> 6. Extension Mechanism and Extension Headers </h2>

	<h3> 6.1. General Requirements </h3>

	<p> 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.

	<p> 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.

	<p> To deal with this, each API provides an <i>extension mechanism</i>
	which lets applications obtain new entry points (pointers to
	functions within driver modules) dynamically at runtime.

	<p> 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 <i>extension header</i> which defines
	interfaces for all known extensions and can be maintained at a
	central source.

	<h3> 6.2. ML Extensions </h3>

	<p> 6.2.1. The ML extension mechanism and extension headers
	are not defined yet; this will be done for OpenML 1.1.

	<h3> 6.3. MLdc Extensions </h3>

	<p> 6.3.1. <i>Need to insert MLdc extension mechanism</i>.

	<h3> 6.4. OpenGL Extensions </h3>

	<p> 6.4.1. <b>Linux</b> - The OpenGL ABI for Linux defines the required
	extension functionality, including the <b>glXGetProcAddressARB</b>
	function (provided by the <tt>GLX_ARB_get_proc_address</tt>
	extension) used to query extension interfaces. The <tt>glext.h</tt>
	and <tt>glxext.h</tt> headers from the OpenGL extension registry
	define interfaces to known OpenGL and GLX extensions.

	<p> 6.4.2. <b>Windows</b> - WGL provides the <b>wglGetProcAddress</b>
	function used to query extension interfaces (unlike the GLX
	equivalent, returned function pointers are <i>context dependent</i>;
	portable code must be aware of this difference). <tt>glext.h</tt>
	(identical to the Linux version) and <tt>wglext.h</tt> headers from
	the OpenGL extension registry define interfaces to known OpenGL and
	WGL extensions.

	<p> 6.4.3. <b>Other Platforms</b> - Unix platforms should follow the
	Linux conventions, providing the <tt>GLX_ARB_get_proc_address</tt>
	extension as well as <tt>glext.h</tt> and <tt>glxext.h</tt>. Other
	platforms should define an extension with similar functionality and
	provide <tt>glext.h</tt>; a companion extension header for window
	system interface extensions may also need to be provided. </p>

	<a name="7">
	<h2> 7. Device Driver Interfaces </h2>

	<p> <b>TBD</b> - waiting on dmSDK DDI.


	<p><hr></p>

	<a name="app">
	<h2> Appendix: Open Issues </h2>

	<p> <b>TBD</b>

	<!-- <p><a name="issue2.1">
	<b>Section 2.1</b>:
	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 <tt>GLlong</tt> and
	<tt>GLulong</tt> as 64-bit datatypes for future OpenGL revisions.
	-->


	<a name="log">
	<h2> Change Log </h2>

	<ul>
	<li> 2001/07/19 - Added extension mechanism section.
	<li> 2001/04/17 - Initial version.
	</ul>

	</body>
	</html>