d3d8: Fix GetDesc and GetLevelDesc for surfaces and textures.
[wine] / DEVELOPERS-HINTS
1 This document should help new developers get started. Like all of Wine, it
2 is a work in progress.
3
4
5 SOURCE TREE STRUCTURE
6 =====================
7
8 The Wine source tree is loosely based on the original Windows modules. 
9 Most of the source is concerned with implementing the Wine API, although
10 there are also various tools, documentation, sample Winelib code, and
11 code specific to the binary loader.  Note that several of the libraries
12 listed here are "stubbed out", meaning they still need to be implemented.
13
14 DLLs (under dlls/):
15 -------------------
16
17         activeds/               - Active Directory Service Interface
18         advapi32/               - Crypto, systeminfo, security, eventlogging
19         advpack/                - Reads and verifies .INF files
20         amstream/               - MultiMedia Streams
21         atl/                    - Active Template Library
22         avicap32/               - AVI capture window class
23         avifil32/               - COM object to play AVI files
24         cabinet/                - Cabinet file interface
25         capi2032/               - Wrapper library for CAPI4Linux access
26         cards/                  - Card graphics
27         cfgmgr32/               - Config manager
28         comcat/                 - Component category manager
29         comctl32/               - Common controls
30         commdlg/                - Common dialog boxes (both 16 & 32 bit)
31         crtdll/                 - Old C runtime library
32         crypt32/                - Cryptography
33         cryptdll/               - Cryptography Manager
34         ctl3d32/                - 3D Effects for Common GUI Components
35         d3d8/                   - Direct3D (3D graphics)
36         d3d9/                   - Direct3D (3D graphics)
37         d3dim/                  - Direct3D Immediate Mode
38         d3drm/                  - Direct3D Retained Mode
39         d3dx8/                  - Direct3D (3D graphics)
40         d3dxof/                 - DirectX Files Functions
41         dbghelp/                - Engine for symbol and module enumeration
42         dciman32/               - DCI Manager (graphics)
43         ddraw/                  - DirectDraw (graphics)
44         devenum/                - Device enumeration (part of DirectShow)
45         dinput/                 - DirectInput (device input)
46         dinput8/                - DirectInput (device input)
47         dmband/                 - DirectMusic Band
48         dmcompos/               - DirectMusic Composer
49         dmime/                  - DirectMusic Interactive Engine
50         dmloader/               - DirectMusic Loader
51         dmscript/               - DirectMusic Scripting
52         dmstyle/                - DirectMusic Style Engine
53         dmsynth/                - DirectMusic Software Synthesizer
54         dmusic/                 - DirectMusic Core Services
55         dmusic32/               - DirectMusic Legacy Port
56         dnsapi/                 - DNS support
57         dplay/                  - DirectPlay (networking)
58         dplayx/                 - DirectPlay (networking)
59         dpnet/                  - DirectPlay (networking)
60         dpnhpast/               - DirectPlay NAT Helper PAST
61         dsound/                 - DirectSound (audio)
62         dswave/                 - DirectMusic Wave
63         dxdiagn/                - DirectX Diagnostic Tool 
64         gdi/                    - GDI (graphics)
65         glu32/                  - OpenGL Utility library (graphics)
66         glut32/                 - OpenGL Utility Toolkit
67         gphoto2.ds/             - Contains libgphoto2 based TWAIN datasource driver
68         hhctrl.ocx/             - HHCTRL OCX implementation
69         iccvid/                 - Radius Cinepak Video Decoder
70         icmp/                   - ICMP protocol (networking)
71         ifsmgr.vxd/             - IFSMGR VxD implementation
72         imaadp32.acm/           - IMA ADPCM Audio Codec
73         imagehlp/               - PE (Portable Executable) Image Helper lib
74         imm32/                  - Input Method Manager
75         iphlpapi/               - IP Helper API
76         itss/                   - Infotech Structured Storage (HTML Help)
77         kernel/                 - The Windows kernel
78         lz32/                   - Lempel-Ziv compression/decompression
79         mapi32/                 - Mail interface
80         mciavi32/               - MCI video driver
81         mcicda/                 - MCI audio CD driver
82         mciseq/                 - MCI MIDI driver
83         midimap/                - MIDI mapper
84         mlang/                  - Multi Language Support
85         mmdevldr.vxd/           - MMDEVLDR VxD implementation
86         monodebg.vxd/           - MONODEBG VxD implementation
87         mpr/                    - Multi-Protocol Router (networking)
88         msacm/                  - Audio Compression Manager (multimedia)
89         msadp32.acm/            - MS ADPCM Audio Codec
90         mscms/                  - Color Management System
91         msdmo/                  - DirectX Media Objects
92         msftedit/               - Rich text editing control (Version 4.1)
93         msg711.acm/             - MS G711 Audio Codec (includes A-Law & MU-Law)
94         mshtml/                 - MS HTML component
95         msi/                    - Microsoft Installer
96         msimg32/                - Gradient and transparency (graphics)
97         msisys/                 - System information
98         msnet32/                - Network interface
99         msrle32/                - Video codecs
100         msvcrt/                 - C runtime library 
101         msvcrt20/               - C runtime library version 2.0
102         msvcrt40/               - C runtime library version 4.0
103         msvcrtd/                - C runtime library debugging
104         msvfw32/                - 16 bit video manager
105         msvidc32/               - Microsoft Video-1 Decoder
106         mswsock/                - Misc networking
107         msxml3/                 - MSXML Class Factory
108         netapi32/               - Network interface
109         newdev/                 - New Hardware Device Library
110         ntdll/                  - NT implementation of kernel calls
111         objsel/                 - Object Picker Dialog
112         odbc32/                 - Open DataBase Connectivity driver manager
113         odbccp32/               - Open DataBase Connectivity driver installer
114         ole32/                  - 32 bit OLE 2.0 libraries
115         oleacc/                 - OLE accessibility support
116         oleaut32/               - 32 bit OLE 2.0 automation
117         olecli32/               - 16 bit OLE client
118         oledlg/                 - OLE 2.0 user interface support
119         olepro32/               - 32 bit OLE 2.0 automation
120         olesvr32/               - 16 bit OLE server
121         opengl32/               - OpenGL implementation (graphics)
122         powrprof/               - Power Management and Profiling
123         psapi/                  - Process Status interface
124         qcap/                   - DirectShow runtime
125         quartz/                 - DirectShow runtime
126         rasapi32/               - Remote Access Server interface
127         riched20/               - Rich text editing control (Version 2.0 and 3.0)
128         richedit/               - Rich text editing control
129         rpcrt4/                 - Remote Procedure Call runtime
130         rsabase/                - RSA encryption
131         rsaenh/                 - Crypto API (DES, 3DES, RSA, etc.)
132         sane.ds/                - Contains sane based TWAIN datasource driver
133         secur32/                - Contains Windows Security functions
134         security/               - Security Support Provider Interface
135         sensapi/                - System Event Notification Service
136         serialui/               - Serial port property pages
137         setupapi/               - Setup interface
138         sfc/                    - System File Checker (Windows File Protection)
139         shdocvw/                - Shell document object and control
140         shell32/                - COM object implementing shell views
141         shfolder/               - Shell folder service
142         shlwapi/                - Shell Light-Weight interface
143         snmpapi/                - SNMP protocol interface (networking)
144         spoolss/                - Spooler Subsystem Library ("spooler" - Service)
145         stdole2.tlb/            - OLE Automation typelib
146         stdole32.tlb/           - Standard OLE typelib
147         sti/                    - Still Image service
148         tapi32/                 - Telephone interface
149         twain_32/               - TWAIN Imaging device communications
150         unicows/                - Unicows replacement (Unicode layer for Win9x)
151         url/                    - Internet shortcut shell extension
152         urlmon/                 - URL Moniker allows binding to a URL
153         user/                   - Window management, standard controls, etc.
154         usp10/                  - Uniscribe Script Processor
155         uxtheme/                - Theme library
156         vdhcp.vxd/              - VDHCP VxD implementation
157         vdmdbg/                 - Virtual DOS machine debug library
158         version/                - File installation library
159         vmm.vxd/                - VMM VxD implementation
160         vnbt.vxd/               - VNBT VxD implementation
161         vnetbios.vxd/           - VNETBIOS VxD implementation
162         vtdapi.vxd/             - VTDAPI VxD implementation
163         vwin32.vxd/             - VWIN32 VxD implementation
164         win32skrnl/             - 32-bit function access for 16-bit systems
165         wined3d/                - Wine internal Direct3D helper
166         winedos/                - DOS features and BIOS calls (Wine specific)
167         winemp3.acm/            - Mpeg Layer 3 Audio Codec
168         wineps/                 - Postscript driver (Wine specific)
169         wininet/                - Internet extensions
170         winmm/                  - Multimedia (16 & 32 bit)
171         winmm/joystick/         - Joystick driver
172         winmm/mciwave/          - MCI wave driver
173         winmm/wavemap/          - Audio mapper
174         winmm/winealsa/         - ALSA audio driver
175         winmm/winearts/         - aRts audio driver
176         winmm/wineaudioio/      - audioio audio driver
177         winmm/winejack/         - JACK audio server driver
178         winmm/winenas/          - NAS audio driver
179         winmm/wineoss/          - OSS audio driver
180         winnls32/               - National Language Support
181         winspool/               - Printing & Print Spooler
182         wintab32/               - Tablet device interface
183         wintrust/               - Trust verification interface
184         wldap32/                - LDAP support
185         wnaspi32/               - 16 bit Advanced SCSI Peripheral Interface
186         wow32/                  - WOW subsystem
187         ws2_32/                 - Sockets 2.0 (networking)
188         wsock32/                - Sockets 1.1 (networking)
189         wtsapi32/               - Terminal Services
190         x11drv/                 - X11 display driver (Wine specific)
191
192 Winelib programs (under programs/):
193 -----------------------------------
194
195         avitools/               - AVI information viewer and player
196         clock/                  - Graphical clock
197         cmdlgtst/               - Common dialog tests
198         control/                - Control panel
199         expand/                 - Decompress Lempel-Ziv compressed archive
200         msiexec/                - Microsoft Installer frontend
201         notepad/                - Notepad replacement 
202         progman/                - Program manager
203         regedit/                - Registry editor
204         regsvr32/               - Register COM server
205         rpcss/                  - RPC services
206         rundll32/               - Execute DLL functions directly
207         start/                  - Replacement for start.exe
208         taskmgr/                - Manage running Windows/Winelib applications
209         uninstaller/            - Remove installed programs
210         view/                   - Metafile viewer
211         wcmd/                   - Command line interface
212         wineboot/               - Wine bootstrap process
213         winecfg/                - Wine configuration utility
214         wineconsole/            - Console
215         winedbg/                - Debugger
216         winefile/               - File manager
217         winemenubuilder/        - Helper program for building Unix menu entries
218         winemine/               - Mine game
219         winepath/               - Translate between Wine and Unix paths
220         winetest/               - Wine testing shell
221         winevdm/                - Wine virtual DOS machine
222         winhelp/                - Help viewer
223         winver/                 - Windows Version Program
224
225
226 Support programs, libraries, etc:
227 ---------------------------------
228
229         dlls/dxerr8/            - DirectX 8 error import lib
230         dlls/dxerr9/            - DirectX 9 error import lib
231         dlls/dxguid/            - DirectX UUID import lib
232         dlls/strmiids/          - Exports class CLSIDs and interface IIDs
233         dlls/uuid/              - Windows-compatible UUID import lib
234         documentation/          - some documentation
235         include/                - Windows standard includes
236         include/msvcrt/         - MSVC compatible libc headers
237         include/wine/           - Wine specific headers
238         libs/                   - the Wine libraries
239         libs/port/              - portability library
240         libs/unicode/           - Unicode support shared
241         libs/wine/              - Wine bootstrap library
242         libs/wpp/               - C preprocessor
243         loader/                 - the main Wine loader
244         server/                 - the Wine server
245         tools/                  - various tools used to build/check Wine
246         tools/widl/             - the IDL compiler
247         tools/winapi/   - A Win32 API checker
248         tools/winebuild/        - Wine build tool
249         tools/winedump/         - a .DLL dump utility
250         tools/winegcc/          - a MinGW command line compatible gcc wrapper
251         tools/wmc/              - the message compiler
252         tools/wpp/              - the C pre-processor library
253         tools/wrc/              - the resource compiler
254
255
256
257 IMPLEMENTING NEW API CALLS
258 ==========================
259
260 This is the simple version, and covers only Win32. Win16 is slightly
261 uglier, because of the Pascal heritage and the segmented memory model.
262
263 All of the Win32 APIs known to Wine are listed in the .spec file of
264 their corresponding dll. An unimplemented call will look like (from
265 gdi32.spec)
266   269 stub PolyBezierTo
267 To implement this call, you need to do the following four things.
268
269 1. Find the appropriate parameters for the call, and add a prototype to
270 the correct header file. In this case, that means [include/wingdi.h],
271 and it might look like
272   BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD);
273 If the function has both an ASCII and a Unicode version, you need to
274 define both and add a #define WINELIB_NAME_AW declaration. See below
275 for discussion of function naming conventions.
276   
277 2. Modify the .spec file to tell Wine that the function has an
278 implementation, what the parameters look like and what Wine function
279 to use for the implementation. In Win32, things are simple--everything
280 is 32-bits. However, the relay code handles pointers and pointers to
281 strings slightly differently, so you should use 'str' and 'wstr' for
282 strings, 'ptr' for other pointer types, and 'long' for everything else.
283   269 stdcall PolyBezierTo(long ptr long) PolyBezierTo
284 The 'PolyBezierTo' at the end of the line is which Wine function to use
285 for the implementation.
286
287 3. Implement the function as a stub. Once you add the function to the .spec
288 file, you must add the function to the Wine source before it will link.
289 Add a function called 'PolyBezierTo' somewhere. Good things to put
290 into a stub:
291   o a correct prototype, including the WINAPI
292   o header comments, including full documentation for the function and
293     arguments (see documentation/README.documentation)
294   o A FIXME message and an appropriate return value are good things to
295     put in a stub.
296
297   /************************************************************
298    *                    PolyBezierTo   (GDI32.269)  
299    *  
300    * Draw many Bezier curves.
301    *
302    * PARAMS
303    *   hdc   [I] Device context to draw to
304    *   p     [I] Array of POINT structs
305    *   count [I] Number of points in p
306    *
307    * RETURNS
308    *   Success: Non-zero.
309    *   Failure: FALSE. Use GetLastError() to find the error cause.
310    *
311    * BUGS
312    *   Unimplemented
313    */
314    BOOL WINAPI PolyBezierTo(HDC hdc, LPCVOID p, DWORD count) 
315    {
316        /* tell the user they've got a substandard implementation */
317        FIXME("(%x,%p,%d): stub\n", hdc, p, count);
318
319        /* some programs may be able to compensate, 
320         * if they know what happened 
321         */
322        SetLastError(ERROR_CALL_NOT_IMPLEMENTED);  
323        return FALSE;    /* error value */
324    }
325
326 4. Implement and test the rest of the function.
327
328
329 IMPLEMENTING A NEW DLL
330 ======================
331
332 Generic directions
333 ------------------
334
335 Apart from writing the set of needed .c files, you also need to do the 
336 following:
337
338 1.  Create a directory <MyDll> where to store the implementation of
339     the DLL. This directory has to be put under the dlls/ directory.
340     If the DLL exists under Windows as both 16 and 32 bit DLL, you
341     should have a single directory with both implementations.
342
343 2.  Create the Makefile.in in the ./dlls/<MyDll>/ directory. You can
344     copy an existing Makefile.in from another ./dlls/ subdirectory.
345     You need at least to change the MODULE and C_SRCS macros. 
346
347 3.  Add the directory in ./configure.ac (in AC_OUTPUT macro at the end
348     of the file to trigger the Makefile generation)
349
350 4.  Run ./make_dlls in the dlls directory to update Makefile.in in
351     that directory.
352
353 5.  You can now regenerate ./configure file (with 'autoconf')
354     and the various Makefiles (with 'configure; make depend') (run
355     from the top of Wine's tree).
356     You should now have a Makefile file in ./dlls/<MyDll>/
357
358 6.  Create the .spec file for the DLL exported functions in your
359     directory. Refer to 'Implementation of new API calls' earlier in
360     this document for more information on this part.
361
362 7.  You can now start adding .c files. For the .h files, if they are
363     standard Windows one, put them in include/. If they are linked to
364     *your* implementation of the dll, put them in your newly created
365     directory.
366
367 Debug channels
368 --------------
369
370 If you need to create a new debug channel, just add the
371 WINE_DEFAULT_DEBUG_CHANNEL to your .c file(s), and use them. 
372 All the housekeeping will happen automatically.
373
374 Resources
375 ---------
376
377 If you also need to add resources to your DLL, then create the .rc
378 file. Add to your ./dlls/<MyDll>/Makefile.in, in the RC_SRCS macro,
379 the list of .rc files to add to the DLL. See dlls/comctl32/ for an
380 example of this.
381
382 Thunking
383 --------
384
385 If you're building a 16 & 32 bit DLLs pair, then from the 32 bit code
386 you might need to call 16 bit routine. The way to do it to add in the
387 code, fragments like:
388 /* ### Start build ### */
389 extern WORD CALLBACK <PREFIX>_CallTo16_word_wwlll(FARPROC16,WORD,WORD,LONG,LONG,LONG);
390 /* ### stop build ### */
391 Where <PREFIX>_ is an internal prefix for your module. The first
392 parameter is always of type FARPROC16. Then, you can get the regular
393 list of parameters. The _word_wwlll indicates the type of return (long
394 or word) and the size of the parameters (here l=>long, w=>word; which
395 maps to WORD,WORD,LONG,LONG,LONG.
396 You can put several functions between the Start/Stop build pair.
397
398 You can also read the winebuild manpage for more details on this.
399
400 Then, add to ./dlls/<MyDll>/Makefile.in a line like:
401
402 EXTRA_OBJS = $(MODULE).glue.o
403
404 See dlls/winmm/ for an example of this.
405
406 MEMORY AND SEGMENTS
407 ===================
408
409 NE (Win16) executables consist of multiple segments.  The Wine loader
410 loads each segment into a unique location in the Wine processes memory
411 and assigns a selector to that segment.  Because of this, it's not
412 possible to exchange addresses freely between 16-bit and 32-bit code.
413 Addresses used by 16-bit code are segmented addresses (16:16), formed
414 by a 16-bit selector and a 16-bit offset.  Those used by the Wine code
415 are regular 32-bit linear addresses.
416
417 There are four ways to obtain a segmented pointer:
418   - Using the MapLS function (recommended).
419   - Allocate a block of memory from the global heap and use
420     WIN16_GlobalLock to get its segmented address.
421   - Declare the argument as 'segptr' instead of 'ptr' in the spec file
422     for a given API function.
423
424 Once you have a segmented pointer, it must be converted to a linear
425 pointer before you can use it from 32-bit code.  This can be done with
426 the MapSL function.  The linear pointer can then be used freely with
427 standard Unix functions like memcpy() etc. without worrying about 64k
428 boundaries.  Note: there's no easy way to convert back from a linear
429 to a segmented address.
430
431 In most cases, you don't need to worry about segmented address, as the
432 conversion is made automatically by the callback code and the API
433 functions only see linear addresses. However, in some cases it is
434 necessary to manipulate segmented addresses; the most frequent cases
435 are:
436   - API functions that return a pointer
437   - lParam of Windows messages that point to a structure
438   - Pointers contained inside structures accessed by 16-bit code.
439
440 It is usually a good practice to used the type 'SEGPTR' for segmented
441 pointers, instead of something like 'LPSTR' or 'char *'.  As SEGPTR is
442 defined as a DWORD, you'll get a compilation warning if you mistakenly
443 use it as a regular 32-bit pointer.
444
445
446 STRUCTURE PACKING
447 =================
448
449 Under Windows, data structures are tightly packed, i.e. there is no
450 padding between structure members. On the other hand, by default gcc
451 aligns structure members (e.g. WORDs are on a WORD boundary, etc.).
452 This means that a structure like
453
454 struct { BYTE x; WORD y; };
455
456 will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
457 dummy byte between x and y. To have the correct layout for structures
458 used by Windows code, you need to embed the struct within two special
459 #include's which will take care of the packing for you:
460
461 #include "pshpack1.h"
462 struct { BYTE x; WORD y; };
463 #include "poppack1.h"
464
465 For alignment on a 2-byte boundary, there is a "pshpack2.h", etc.
466
467
468 NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
469 ==============================================
470
471 In order to support both Win16 and Win32 APIs within the same source
472 code, the following convention must be used in naming all API
473 functions and types. If the Windows API uses the name 'xxx', the Wine
474 code must use:
475
476  - 'xxx16' for the Win16 version,
477  - 'xxx'   for the Win32 version when no strings are involved,
478  - 'xxxA'  for the Win32 version with ASCII strings,
479  - 'xxxW'  for the Win32 version with Unicode strings.
480
481 If the function has both ASCII and Unicode version, you should then
482 use the macros WINELIB_NAME_AW(xxx) or DECL_WINELIB_TYPE_AW(xxx)
483 (defined in include/windef.h) to define the correct 'xxx' function
484 or type for Winelib. When compiling Wine itself, 'xxx' is _not_
485 defined, meaning that code inside of Wine must always specify
486 explicitly the ASCII or Unicode version.
487
488 If 'xxx' is the same in Win16 and Win32, you can simply use the same
489 name as Windows, i.e. just 'xxx'.  If 'xxx' is Win16 only, you could
490 use the name as is, but it's preferable to use 'xxx16' to make it
491 clear it is a Win16 function.
492
493 Examples:
494
495 typedef struct { /* Win32 ASCII data structure */ } WNDCLASSA;
496 typedef struct { /* Win32 Unicode data structure */ } WNDCLASSW;
497 typedef struct { /* Win16 data structure */ } WNDCLASS16;
498 DECL_WINELIB_TYPE_AW(WNDCLASS);
499
500 ATOM RegisterClass16( WNDCLASS16 * );
501 ATOM RegisterClassA( WNDCLASSA * );
502 ATOM RegisterClassW( WNDCLASSW * );
503 #define RegisterClass WINELIB_NAME_AW(RegisterClass)
504
505 The Winelib user can then say:
506
507     WNDCLASS wc = { ... };
508     RegisterClass( &wc );
509
510 and this will use the correct declaration depending on the definition
511 of the UNICODE symbol.
512
513
514 DEBUG MESSAGES
515 ==============
516
517 To display a message only during debugging, you normally write something
518 like this:
519
520         TRACE("abc...");  or
521         FIXME("abc...");  or
522         WARN("abc...");   or
523         ERR("abc...");
524
525 depending on the seriousness of the problem. (documentation/debugging.sgml
526 explains when it is appropriate to use each of them). You need to declare
527 the debug channel name at the top of the file (after the includes) using
528 the WINE_DEFAULT_DEBUG_CHANNEL macro, like so:
529
530         WINE_DEFAULT_DEBUG_CHANNEL(win);
531
532 If your debugging code is more complex than just printf, you can use 
533 the macros:
534
535         TRACE_ON(xxx), WARN_ON(xxx), ERR_ON(xxx) and FIXME_ON(xxx) 
536
537 to test if the given channel is enabled. Thus, you can write:
538
539         if (TRACE_ON(win)) DumpSomeStructure(&str);
540
541 Don't worry about the inefficiency of the test. If it is permanently 
542 disabled (that is TRACE_ON(win) is 0 at compile time), the compiler will 
543 eliminate the dead code.
544
545 For more info about debugging messages, read:
546
547 http://www.winehq.org/site/docs/wine-devel/debugging
548
549
550 MORE INFO
551 =========
552
553 1. There is a FREE online version of the MSDN library (including
554    documentation for the Win32 API) on http://msdn.microsoft.com/
555    or http://www.msdn.com/
556
557 2. Windows apilist:  http://www.mentalis.org/apilist/apilist.php
558
559 3. http://www.sonic.net/~undoc/bookstore.html
560
561 4. In 1993 Dr. Dobbs Journal published a column called "Undocumented Corner".
562
563 5. www.geocities.com/SiliconValley/4942/