documentation/opengl.sgml

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