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