documentation/opengl.sgml

   1   <chapter id="opengl">
   2     <title>Wine and OpenGL</title>
   3
   4     <sect1 id="opengl-required">
   5       <title>What is needed to have OpenGL support in Wine</title>
   6
   7       <para>
   8         Basically, if you have a Linux OpenGL ABI compliant libGL
   9         (<ulink url="http://oss.sgi.com/projects/ogl-sample/ABI/">
  10           http://oss.sgi.com/projects/ogl-sample/ABI/</ulink>)
  11         installed on your computer, you should have everything
  12         that is needed.
  13       </para>
  14       <para>
  15         To be more clear, I will detail one step after another what
  16         the <command>configure</command> script checks.
  17       </para>
  18       <para>
  19         If, after Wine compiles, OpenGL support is not compiled in,
  20         you can always check <filename>config.log</filename> to see
  21         which of the following points failed.
  22       </para>
  23
  24       <sect2>
  25         <title>Header files</title>
  26
  27         <para>
  28           The needed header files to build OpenGL support in Wine are :
  29         </para>
  30
  31         <variablelist>
  32           <varlistentry>
  33             <term><filename>gl.h:</filename></term>
  34             <listitem>
  35               <para>
  36                 the definition of all OpenGL core functions, types and enumerants
  37               </para>
  38             </listitem>
  39           </varlistentry>
  40           <varlistentry>
  41             <term><filename>glx.h:</filename></term>
  42             <listitem>
  43               <para>
  44                 how OpenGL integrates in the X Window environment
  45               </para>
  46             </listitem>
  47           </varlistentry>
  48           <varlistentry>
  49             <term><filename>glext.h:</filename></term>
  50             <listitem>
  51               <para>
  52                 the list of all registered OpenGL extensions
  53               </para>
  54             </listitem>
  55           </varlistentry>
  56         </variablelist>
  57
  58         <para>
  59           The latter file (<filename>glext.h</filename>) is, as of
  60           now, not necessary to build Wine. But as this file can be
  61           easily obtained from SGI
  62           (<ulink url="http://oss.sgi.com/projects/ogl-sample/ABI/glext.h">
  63             http://oss.sgi.com/projects/ogl-sample/ABI/glext.h</ulink>),
  64           and that all OpenGL should provide one, I decided to keep it here.
  65         </para>
  66       </sect2>
  67
  68       <sect2>
  69         <title>OpenGL library itself</title>
  70
  71         <para>
  72           To check for the presence of 'libGL' on the system, the
  73           script checks if it defines the
  74           <function>glXCreateContext</function> function.
  75         </para>
  76       </sect2>
  77
  78       <sect2>
  79         <title>glXGetProcAddressARB function</title>
  80
  81         <para>
  82           The core of Wine's OpenGL implementation (at least for all
  83           extensions) is the <function>glXGetProcAddressARB</function>
  84           function. Your OpenGL library needs to have this function
  85           defined for Wine to be able to support OpenGL.
  86         </para>
  87       </sect2>
  88     </sect1>
  89
  90     <sect1 id="opengl-works">
  91       <title>How it all works</title>
  92
  93       <para>
  94         The core OpenGL function calls are the same between Windows
  95         and Linux. So what is the difficulty to support it in Wine ?
  96         Well, there are two different problems :
  97       </para>
  98
  99       <orderedlist>
 100         <listitem>
 101           <para>
 102             the interface to the windowing system is different for
 103             each OS. It's called 'GLX' for Linux (well, for X Window)
 104             and 'wgl' for Windows. Thus, one need first to emulate one
 105             (wgl) with the other (GLX).
 106           </para>
 107         </listitem>
 108         <listitem>
 109           <para>
 110             the calling convention between Windows (the 'Pascal'
 111             convention or 'stdcall') is different from the one used on
 112             Linux (the 'C' convention or 'cdecl'). This means that
 113             each call to an OpenGL function must be 'translated' and
 114             cannot be used directly by the Windows program.
 115           </para>
 116         </listitem>
 117       </orderedlist>
 118
 119       <para>
 120         Add to this some brain-dead programs (using GL calls without
 121         setting-up a context or deleting three time the same context)
 122         and you have still some work to do :-)
 123       </para>
 124
 125       <sect2>
 126         <title>The Windowing system integration</title>
 127
 128         <para>
 129           This integration is done at two levels :
 130         </para>
 131
 132         <orderedlist>
 133           <listitem>
 134             <para>
 135               At GDI level for all pixel format selection routines (ie
 136               choosing if one wants a depth / alpha buffer, the size
 137               of these buffers, ...) and to do the 'page flipping' in
 138               double buffer mode. This is implemented in
 139               <filename>dlls/x11drv/opengl.c</filename> (all these
 140               functions are part of Wine's graphic driver function
 141               pointer table and thus could be reimplemented if ever Wine
 142               works on another Windowing system than X).
 143             </para>
 144           </listitem>
 145           <listitem>
 146             <para>
 147               In the <filename>OpenGL32.DLL</filename> itself for all
 148               other functionalities (context creation / deletion,
 149               querying of extension functions, ...). This is done in
 150               <filename>dlls/opengl32/wgl.c</filename>.
 151             </para>
 152           </listitem>
 153         </orderedlist>
 154       </sect2>
 155
 156       <sect2>
 157         <title>The thunks</title>
 158
 159         <para>
 160           The thunks are the Wine code that does the calling
 161           convention translation and they are auto-generated by a Perl
 162           script. In Wine's CVS tree, these thunks are already
 163           generated for you. Now, if you want to do it yourself, there
 164           is how it all works....
 165         </para>
 166         <para>
 167           The script is located in <filename>dlls/opengl32</filename>
 168           and is called <command>make_opengl</command>. It requires
 169           Perl5 to work and takes two arguments :
 170         </para>
 171
 172         <orderedlist>
 173           <listitem>
 174             <para>
 175               The first is the path to the OpenGL registry. Now, you
 176               will all ask 'but what is the OpenGL registry ?' :-)
 177               Well, it's part of the OpenGL sample implementation
 178               source tree from SGI (more informations at this URL :
 179               <ulink url="http://oss.sgi.com/projects/ogl-sample/">
 180                 http://oss.sgi.com/projects/ogl-sample/</ulink>.
 181             </para>
 182             <para>
 183               To summarize, these files contain human-readable but
 184               easily parsed information on ALL OpenGL core functions
 185               and ALL registered extensions (for example the
 186               prototype, the OpenGL version, ...).
 187             </para>
 188           </listitem>
 189           <listitem>
 190             <para>
 191               the second is the OpenGL version to 'simulate'. This
 192               fixes the list of functions that the Windows application
 193               can link directly to without having to query them from
 194               the OpenGL driver. Windows is based, for now, on OpenGL
 195               1.1, but the thunks that are in the CVS tree are
 196               generated for OpenGL 1.2.
 197             </para>
 198             <para>
 199               This option can have three values:
 200               <literal>1.0</literal>, <literal>1.1</literal> and
 201               <literal>1.2</literal>.
 202             </para>
 203           </listitem>
 204         </orderedlist>
 205
 206         <para>
 207           This script generates three files :
 208         </para>
 209
 210         <orderedlist>
 211           <listitem>
 212             <para>
 213               <filename>opengl32.spec</filename> gives Wine's linker
 214               the signature of all function in the
 215               <filename>OpenGL32.DLL</filename> library so that the
 216               application can link them. Only 'core' functions are
 217               listed here.
 218             </para>
 219           </listitem>
 220           <listitem>
 221             <para>
 222               <filename>opengl_norm.c</filename> contains all the
 223               thunks for the 'core' functions. Your OpenGL library
 224               must provide ALL the function used in this file as these
 225               are not queried at run time.
 226             </para>
 227           </listitem>
 228           <listitem>
 229             <para>
 230               <filename>opengl_ext.c</filename> contains all the
 231               functions that are not part of the 'core' functions.
 232               Contrary to the thunks in
 233               <filename>opengl_norm.c</filename>, these functions do
 234               not depend at all on what your libGL provides.
 235             </para>
 236             <para>
 237               In fact, before using one of these thunks, the Windows
 238               program first needs to 'query' the function pointer. At
 239               this point, the corresponding thunk is useless. But as
 240               we first query the same function in libGL and store the
 241               returned function pointer in the thunk, the latter
 242               becomes functional.
 243             </para>
 244           </listitem>
 245         </orderedlist>
 246       </sect2>
 247     </sect1>
 248
 249     <sect1 id="opengl-problems">
 250       <title>Known problems</title>
 251
 252       <sect2>
 253         <title>When running an OpenGL application, the screen flickers</title>
 254
 255         <para>
 256           Due to restrictions (that do not exist in Windows) on OpenGL
 257           contexts, if you want to prevent the screen to flicker when
 258           using OpenGL applications (all games are using double-buffered
 259           contexts), you need to set the following option in your
 260           <filename>~/.wine/config</filename> file
 261           in the <literal>[x11drv]</literal> section:
 262           <programlisting>
 263 DesktopDoubleBuffered = Y
 264           </programlisting>
 265           and to run Wine in desktop mode.
 266         </para>
 267       </sect2>
 268
 269       <sect2>
 270         <title>Unknown extension error message:</title>
 271
 272         <screen>
 273 Extension defined in the OpenGL library but NOT in opengl_ext.c...
 274 Please report (lionel.ulmer@free.fr) !
 275         </screen>
 276
 277         <para>
 278           This means that the extension requested by the application
 279           is found in the libGL used by Linux (ie the call to
 280           <function>glXGetProcAddressARB</function> returns a
 281           non-<constant>NULL</constant> pointer) but that this string
 282           was NOT found in Wine's extension registry.
 283         </para>
 284         <para>
 285           This can come from two causes:
 286         <orderedlist>
 287           <listitem>
 288             <para>
 289               The <filename>opengl_ext.c</filename> file is too old
 290               and needs to be generated again.
 291             </para>
 292           </listitem>
 293           <listitem>
 294             <para>
 295               Use of obsolete extensions that are not supported
 296               anymore by SGI or of 'private' extensions that are not
 297               registered. An example of the former are
 298               <function>glMTexCoord2fSGIS</function> and
 299               <function>glSelectTextureSGIS</function> as used by
 300               Quake 2 (and apparently also by old versions of Half
 301               Life). If documentation can be found on these functions,
 302               they can be added to Wine's extension set.
 303             </para>
 304           </listitem>
 305         </orderedlist>
 306         </para>
 307
 308         <para>
 309           If you have this, run with <parameter>WINEDEBUG=+opengl</parameter>
 310           and send me <email>lionel.ulmer@free.fr</email> the TRACE.
 311         </para>
 312       </sect2>
 313
 314       <sect2>
 315         <title><filename>libopengl32.so</filename> is built but it is still not working</title>
 316
 317         <para>
 318           This may be caused by some missing functions required by
 319           <filename>opengl_norm.c</filename> but that your Linux
 320           OpenGL library does not provide.
 321         </para>
 322         <para>
 323           To check for this, do the following steps :
 324         </para>
 325
 326         <orderedlist>
 327           <listitem>
 328             <para>
 329               create a dummy <filename>.c</filename> file :
 330             </para>
 331             <programlisting>
 332 int main(void)
 333 {
 334     return 0;
 335 }
 336             </programlisting>
 337           </listitem>
 338           <listitem>
 339             <para>
 340               try to compile it by linking both libwine and
 341               libopengl32 (this command line supposes that you
 342               installed the Wine libraries in
 343               <filename>/usr/local/lib</filename>, YMMV) :
 344             </para>
 345             <programlisting>
 346 gcc dummy.c -L/usr/local/lib -lwine -lopengl32
 347             </programlisting>
 348           </listitem>
 349           <listitem>
 350             <para>
 351               if it works, the problem is somewhere else (and you can
 352               send me an email). If not, you could re-generate the
 353               thunk files for OpenGL 1.1 for example (and send me your
 354               OpenGL version so that this problem can be detected at
 355               configure time).
 356             </para>
 357           </listitem>
 358         </orderedlist>
 359       </sect2>
 360     </sect1>
 361   </chapter>
 362
 363 <!-- Keep this comment at the end of the file
 364 Local variables:
 365 mode: sgml
 366 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
 367 End:
 368 -->