documentation/opengl.sgml

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