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 thread-safety</title>
  70
  71         <para>
  72           After that, the script checks if the OpenGL library relies
  73           or not on the pthread library to provide thread safety (most
  74           'modern' OpenGL libraries do).
  75         </para>
  76         <para>
  77           If the OpenGL library explicitly links in libpthread (you
  78           can check it with a <command>ldd libGL.so</command>), you
  79           need to force OpenGL support by starting
  80           <command>configure</command> with the
  81           <parameter>--enable-opengl</parameter> flag.
  82         </para>
  83         <para>
  84           The reason to this is that Wine contains some hacks done by
  85           Ove to cohabit with pthread that are known to work well in
  86           most of the cases (glibc 2.1.x). On the other hand, we never
  87           got Wine to work with glibc 2.0.6. Thus, I deemed preferable
  88           to play it safe : by default, I suppose that the hack won't
  89           work and that it's the user's responsibility to enable it.
  90         </para>
  91         <para>
  92           Anyway, it should be pretty safe to build with
  93           <parameter>--enable-opengl</parameter>.
  94         </para>
  95       </sect2>
  96
  97       <sect2>
  98         <title>OpenGL library itself</title>
  99
 100         <para>
 101           To check for the presence of 'libGL' on the system, the
 102           script checks if it defines the
 103           <function>glXCreateContext</function> function. There should
 104           be no problem here.
 105         </para>
 106       </sect2>
 107
 108       <sect2>
 109         <title>glXGetProcAddressARB function</title>
 110
 111         <para>
 112           The core of Wine's OpenGL implementation (at least for all
 113           extensions) is the <function>glXGetProcAddressARB</function>
 114           function. Your OpenGL library needs to have this function
 115           defined for Wine to be able to support OpenGL.
 116         </para>
 117         <para>
 118           If your library does not provide it, you are out of luck.
 119         </para>
 120         <note>
 121           <para>
 122             this is not completely true as one could rewrite a
 123             <function>glXGetProcAddressARB</function> replacement
 124             using <function>dlopen</function> and friends, but well,
 125             telling people to upgrade is easier :-).
 126           </para>
 127         </note>
 128       </sect2>
 129     </sect1>
 130
 131     <sect1 id="opengl-configure">
 132       <title>How to configure</title>
 133
 134       <para>
 135         Configuration is quite easy : once OpenGL support has been
 136         built in Wine, this internal OpenGL driver will be used each
 137         time an application tries to load
 138         <filename>opengl32.dll</filename>.
 139       </para>
 140       <para>
 141         Due to restrictions (that do not exist in Windows) on OpenGL
 142         contexts, if you want to prevent the screen to flicker when
 143         using OpenGL applications (all games are using double-buffered
 144         contexts), you need to set the following option in your
 145         <filename>~/.wine/config</filename> file
 146         in the [x11drv] section :
 147       </para>
 148       <programlisting>
 149 DesktopDoubleBuffered = Y
 150       </programlisting>
 151       <para>
 152         and to run Wine with the <parameter>--desktop</parameter>
 153         option.
 154       </para>
 155     </sect1>
 156
 157     <sect1 id="opengl-works">
 158       <title>How it all works</title>
 159
 160       <para>
 161         The core OpenGL function calls are the same between Windows
 162         and Linux. So what is the difficulty to support it in Wine ?
 163         Well, there are two different problems :
 164       </para>
 165
 166       <orderedlist>
 167         <listitem>
 168           <para>
 169             the interface to the windowing system is different for
 170             each OS. It's called 'GLX' for Linux (well, for X Window)
 171             and 'wgl' for Windows. Thus, one need first to emulate one
 172             (wgl) with the other (GLX).
 173           </para>
 174         </listitem>
 175         <listitem>
 176           <para>
 177             the calling convention between Windows (the 'Pascal'
 178             convention or 'stdcall') is different from the one used on
 179             Linux (the 'C' convention or 'cdecl'). This means that
 180             each call to an OpenGL function must be 'translated' and
 181             cannot be used directly by the Windows program.
 182           </para>
 183         </listitem>
 184       </orderedlist>
 185
 186       <para>
 187         Add to this some brain-dead programs (using GL calls without
 188         setting-up a context or deleting three time the same context)
 189         and you have still some work to do :-)
 190       </para>
 191
 192       <sect2>
 193         <title>The Windowing system integration</title>
 194
 195         <para>
 196           This integration is done at two levels :
 197         </para>
 198
 199         <orderedlist>
 200           <listitem>
 201             <para>
 202               At GDI level for all pixel format selection routines (ie
 203               choosing if one wants a depth / alpha buffer, the size
 204               of these buffers, ...) and to do the 'page flipping' in
 205               double buffer mode. This is implemented in
 206               <filename>graphics/x11drv/opengl.c</filename> (all these
 207               functions are part of Wine's graphic driver function
 208               pointer table and thus could be reimplemented if ever Wine
 209               works on another Windowing system than X).
 210             </para>
 211           </listitem>
 212           <listitem>
 213             <para>
 214               In the <filename>OpenGL32.DLL</filename> itself for all
 215               other functionalities (context creation / deletion,
 216               querying of extension functions, ...). This is done in
 217               <filename>dlls/opengl32/wgl.c</filename>.
 218             </para>
 219           </listitem>
 220         </orderedlist>
 221       </sect2>
 222
 223       <sect2>
 224         <title>The thunks</title>
 225
 226         <para>
 227           The thunks are the Wine code that does the calling
 228           convention translation and they are auto-generated by a Perl
 229           script. In Wine's CVS tree, these thunks are already
 230           generated for you. Now, if you want to do it yourself, there
 231           is how it all works....
 232         </para>
 233         <para>
 234           The script is located in <filename>dlls/opengl32</filename>
 235           and is called <command>make_opengl</command>. It requires
 236           Perl5 to work and takes two arguments :
 237         </para>
 238
 239         <orderedlist>
 240           <listitem>
 241             <para>
 242               The first is the path to the OpenGL registry. Now, you
 243               will all ask 'but what is the OpenGL registry ?' :-)
 244               Well, it's part of the OpenGL sample implementation
 245               source tree from SGI (more informations at this URL :
 246               <ulink url="http://oss.sgi.com/projects/ogl-sample/">
 247                 http://oss.sgi.com/projects/ogl-sample/</ulink>.
 248             </para>
 249             <para>
 250               To summarize, these files contain human-readable but
 251               easily parsed information on ALL OpenGL core functions
 252               and ALL registered extensions (for example the
 253               prototype, the OpenGL version, ...).
 254             </para>
 255           </listitem>
 256           <listitem>
 257             <para>
 258               the second is the OpenGL version to 'simulate'. This
 259               fixes the list of functions that the Windows application
 260               can link directly to without having to query them from
 261               the OpenGL driver. Windows is based, for now, on OpenGL
 262               1.1, but the thunks that are in the CVS tree are
 263               generated for OpenGL 1.2.
 264             </para>
 265             <para>
 266               This option can have three values:
 267               <literal>1.0</literal>, <literal>1.1</literal> and
 268               <literal>1.2</literal>.
 269             </para>
 270           </listitem>
 271         </orderedlist>
 272
 273         <para>
 274           This script generates three files :
 275         </para>
 276
 277         <orderedlist>
 278           <listitem>
 279             <para>
 280               <filename>opengl32.spec</filename> gives Wine's linker
 281               the signature of all function in the
 282               <filename>OpenGL32.DLL</filename> library so that the
 283               application can link them. Only 'core' functions are
 284               listed here.
 285             </para>
 286           </listitem>
 287           <listitem>
 288             <para>
 289               <filename>opengl_norm.c</filename> contains all the
 290               thunks for the 'core' functions. Your OpenGL library
 291               must provide ALL the function used in this file as these
 292               are not queried at run time.
 293             </para>
 294           </listitem>
 295           <listitem>
 296             <para>
 297               <filename>opengl_ext.c</filename> contains all the
 298               functions that are not part of the 'core' functions.
 299               Contrary to the thunks in
 300               <filename>opengl_norm.c</filename>, these functions do
 301               not depend at all on what your libGL provides.
 302             </para>
 303             <para>
 304               In fact, before using one of these thunks, the Windows
 305               program first needs to 'query' the function pointer. At
 306               this point, the corresponding thunk is useless. But as
 307               we first query the same function in libGL and store the
 308               returned function pointer in the thunk, the latter
 309               becomes functional.
 310             </para>
 311           </listitem>
 312         </orderedlist>
 313       </sect2>
 314     </sect1>
 315
 316     <sect1 id="opengl-problems">
 317       <title>Known problems - shortcomings</title>
 318
 319       <sect2>
 320         <title>Missing GLU32.DLL</title>
 321
 322         <para>
 323           GLU is a library that is layered upon OpenGL. There is a
 324           100% correspondence between the
 325           <filename>libGLU.so</filename> that is used on Linux and
 326           <filename>GLU32.DLL</filename>.
 327         </para>
 328         <para>
 329           As for the moment, I did not create a set of thunks to support this
 330           library natively in Wine (it would easy to do, but I am waiting for
 331           a better solution than adding another autogenerated thunk file), you
 332           can always download anywhere on the net (it's free) a
 333           <filename>GLU32.DLL</filename> file (by browsing, for example,
 334           <ulink url="http://www.dll-files.com/dllindex/index.shtml">
 335             http://www.dll-files.com/dllindex/index.shtml</ulink>).
 336         </para>
 337       </sect2>
 338
 339       <sect2>
 340         <title>OpenGL not detected at configure time</title>
 341
 342         <para>
 343           See section (I) for a detailed explanation of the
 344           <filename>configure</filename> requirements.
 345         </para>
 346       </sect2>
 347
 348       <sect2>
 349         <title>When running an OpenGL application, the screen flickers</title>
 350
 351         <para>
 352           See section (II) for how to create the context
 353           double-buffered and thus preventing this flicker effect.
 354         </para>
 355       </sect2>
 356
 357       <sect2>
 358         <title>Wine gives me the following error message : </title>
 359
 360         <screen>
 361 Extension defined in the OpenGL library but NOT in opengl_ext.c...
 362 Please report (lionel.ulmer@free.fr) !
 363         </screen>
 364
 365         <para>
 366           This means that the extension requested by the application
 367           is found in the libGL used by Linux (ie the call to
 368           <function>glXGetProcAddressARB</function> returns a
 369           non-<constant>NULL</constant> pointer) but that this string
 370           was NOT found in Wine's extension registry.
 371         </para>
 372         <para>
 373           This can come from two causes :
 374         </para>
 375
 376         <orderedlist>
 377           <listitem>
 378             <para>
 379               The <filename>opengl_ext.c</filename> file is too old
 380               and needs to be generated again.
 381             </para>
 382           </listitem>
 383           <listitem>
 384             <para>
 385               Use of obsolete extensions that are not supported
 386               anymore by SGI or of 'private' extensions that are not
 387               registered. An example of the former are
 388               <function>glMTexCoord2fSGIS</function> and
 389               <function>glSelectTextureSGIS</function> as used by
 390               Quake 2 (and apparently also by old versions of Half
 391               Life). If documentation can be found on these functions,
 392               they can be added to Wine's extension set.
 393             </para>
 394           </listitem>
 395         </orderedlist>
 396
 397         <para>
 398           If you have this, run with <parameter>--debugmsg
 399             +opengl</parameter> and send me
 400           <email>lionel.ulmer@free.fr</email> the TRACE.
 401         </para>
 402       </sect2>
 403
 404       <sect2>
 405         <title><filename>libopengl32.so</filename> is built but it is still not working</title>
 406
 407         <para>
 408           This may be caused by some missing functions required by
 409           <filename>opengl_norm.c</filename> but that your Linux
 410           OpenGL library does not provide.
 411         </para>
 412         <para>
 413           To check for this, do the following steps :
 414         </para>
 415
 416         <orderedlist>
 417           <listitem>
 418             <para>
 419               create a dummy <filename>.c</filename> file :
 420             </para>
 421             <programlisting>
 422 int main(void) {
 423     return 0;
 424 }
 425             </programlisting>
 426           </listitem>
 427           <listitem>
 428             <para>
 429               try to compile it by linking both libwine and
 430               libopengl32 (this command line supposes that you
 431               installed the Wine libraries in
 432               <filename>/usr/local/lib</filename>, YMMV) :
 433             </para>
 434             <programlisting>
 435 gcc dummy.c -L/usr/local/lib -lwine -lopengl32
 436             </programlisting>
 437           </listitem>
 438           <listitem>
 439             <para>
 440               if it works, the problem is somewhere else (and you can
 441               send me an email). If not, you could re-generate the
 442               thunk files for OpenGL 1.1 for example (and send me your
 443               OpenGL version so that this problem can be detected at
 444               configure time).
 445             </para>
 446           </listitem>
 447         </orderedlist>
 448       </sect2>
 449     </sect1>
 450   </chapter>
 451
 452 <!-- Keep this comment at the end of the file
 453 Local variables:
 454 mode: sgml
 455 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
 456 End:
 457 -->