Various registry-related PostScript driver enhancements.
[wine.git] / documentation / opengl.sgml
blob88dc083636476742d76d1087af20ce1bf3524a20
1 <chapter id="opengl">
2 <title>Wine and OpenGL</title>
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>
12 <sect1 id="opengl-required">
13 <title>What is needed to have OpenGL support in Wine</title>
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>
32 <sect2>
33 <title>Header files</title>
35 <para>
36 The needed header files to build OpenGL support in Wine are :
37 </para>
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>
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>
70 <sect2>
71 <title>OpenGL library thread-safety</title>
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>
99 <sect2>
100 <title>OpenGL library itself</title>
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>
110 <sect2>
111 <title>glXGetProcAddressARB function</title>
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>
133 <sect1 id="opengl-configure">
134 <title>How to configure</title>
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>
159 <sect1 id="opengl-works">
160 <title>How it all works</title>
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>
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>
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>
194 <sect2>
195 <title>The Windowing system integration</title>
197 <para>
198 This integration is done at two levels :
199 </para>
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>
225 <sect2>
226 <title>The thunks</title>
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>
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>
275 <para>
276 This script generates three files :
277 </para>
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>
318 <sect1 id="opengl-problems">
319 <title>Known problems - shortcomings</title>
321 <sect2>
322 <title>Missing GLU32.DLL</title>
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>
341 <sect2>
342 <title>OpenGL not detected at configure time</title>
344 <para>
345 See section (I) for a detailed explanation of the
346 <filename>configure</filename> requirements.
347 </para>
348 </sect2>
350 <sect2>
351 <title>When running an OpenGL application, the screen flickers</title>
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>
359 <sect2>
360 <title>Wine gives me the following error message : </title>
362 <screen>
363 Extension defined in the OpenGL library but NOT in opengl_ext.c...
364 Please report (&email-lionel-ulmer;) !
365 </screen>
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>
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>
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>
406 <sect2>
407 <title><filename>libopengl32.so</filename> is built but it is still not working</title>
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>
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;
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>
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: