DXGL r148 - Code Review

Jump to navigation Jump to search
Repository:DXGL
Revision:< r147‎ | r148 | r149 >
Date:17:06, 12 May 2012
Author:admin
Status:new
Tags:
Comment:
Add documentation to ddraw.dll functions.
Update Doxyfile.debug and Doxyfile
Modified paths:
  • /Help/Doxyfile (modified) (history)
  • /Help/Doxyfile.debug (modified) (history)
  • /ddraw/ddraw.cpp (modified) (history)

Diff [purge]

Index: Help/Doxyfile
——@@ -693,7 +693,7 @@
694694 # should be searched for input files as well. Possible values are YES and NO.
695695 # If left blank NO is used.
696696
697 -RECURSIVE = NO
 697+RECURSIVE = YES
698698
699699 # The EXCLUDE tag can be used to specify files and/or directories that should
700700 # excluded from the INPUT source files. This way you can easily exclude a
——@@ -700,7 +700,7 @@
701701 # subdirectory from a directory tree whose root is specified with the INPUT tag.
702702 # Note that relative paths are relative to directory from which doxygen is run.
703703
704 -EXCLUDE =
 704+EXCLUDE = ../.svn
705705
706706 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or
707707 # directories that are symbolic links (a Unix file system feature) are excluded
Index: Help/Doxyfile.debug
——@@ -45,7 +45,7 @@
4646 # exceed 55 pixels and the maximum width should not exceed 200 pixels.
4747 # Doxygen will copy the logo to the output directory.
4848
49 -PROJECT_LOGO = C:/Programming/Projects/dxgl/common/dxgl.png
 49+PROJECT_LOGO = ../common/dxgl.png
5050
5151 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
5252 # base path where the generated documentation will be put.
——@@ -693,7 +693,7 @@
694694 # should be searched for input files as well. Possible values are YES and NO.
695695 # If left blank NO is used.
696696
697 -RECURSIVE = NO
 697+RECURSIVE = YES
698698
699699 # The EXCLUDE tag can be used to specify files and/or directories that should
700700 # excluded from the INPUT source files. This way you can easily exclude a
——@@ -700,7 +700,7 @@
701701 # subdirectory from a directory tree whose root is specified with the INPUT tag.
702702 # Note that relative paths are relative to directory from which doxygen is run.
703703
704 -EXCLUDE =
 704+EXCLUDE = ../.svn
705705
706706 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or
707707 # directories that are symbolic links (a Unix file system feature) are excluded
Index: ddraw/ddraw.cpp
——@@ -35,6 +35,15 @@
3636 int vsyncstatus;
3737 bool ddenabled = false;
3838
 39+/**
 40+ * Tests if a pointer is valid for reading from. Compile ion Visual C++ with /EHa
 41+ * enabled Structed Exception Handling in C++ code, to prevent crashes on invalid
 42+ * pointers.
 43+ * @param ptr
 44+ * Pointer to test for validity.
 45+ * @return
 46+ * Returns false if the pointer is valid, or true if an error occurs.
 47+ */
3948 bool IsBadReadPointer(void *ptr)
4049 {
4150 char a;
——@@ -50,37 +59,62 @@
5160 }
5261 }
5362
 63+/// Stub for function found in system ddraw.dll
5464 DDRAW_API void WINAPI AcquireDDThreadLock()
5565 {
5666 // FIXME: Add thread lock
5767 FIXME("AcquireDDThreadLock: stub\n");
5868 }
 69+
 70+/// Stub for function found in system ddraw.dll
5971 DDRAW_API void WINAPI CompleteCreateSystemSurface()
6072 {
6173 FIXME("CompleteCreateSystemSurface: stub\n");
6274 }
 75+
 76+/// Stub for function found in system ddraw.dll
6377 DDRAW_API void WINAPI D3DParseUnknownCommand()
6478 {
6579 FIXME("D3DParseUnknownCommand: stub\n");
6680 }
 81+
 82+/// Stub for function found in system ddraw.dll
6783 DDRAW_API void WINAPI DDGetAttachedSurfaceLcl()
6884 {
6985 FIXME("DDGetAttachedSurfaceLcl: stub\n");
7086 }
 87+
 88+/// Stub for function found in system ddraw.dll
7189 DDRAW_API void WINAPI DDInternalLock()
7290 {
7391 //FIXME: Add locking code
7492 FIXME("DDInternalLock: stub\n");
7593 }
 94+
 95+/// Stub for function found in system ddraw.dll
7696 DDRAW_API void WINAPI DDInternalUnlock()
7797 {
7898 //FIXME: Add unlocking code
7999 FIXME("DDInternalUnlock: stub\n");
80100 }
 101+
 102+/// Stub for function found in system ddraw.dll
81103 DDRAW_API void WINAPI DSoundHelp()
82104 {
83105 FIXME("DSoundHelp: stub\n");
84106 }
 107+
 108+/**
 109+ * This function is used by DirectDrawCreate to test if opengl32.dll is calling
 110+ * these functions. If so, DirectDrawCreate will load the system ddraw.dll and
 111+ * call its DirectDrawCreate function.
 112+ * @param returnaddress
 113+ * The address to evaluate whether it is from opengl32.dll or not.
 114+ * The return address of the calling function may be obtained with the
 115+ * _ReturnAddress() function.
 116+ * @return
 117+ * Returns nonzero if the address points to opengl32.dll, otherwise returns zero.
 118+ */
85119 int IsCallerOpenGL(void *returnaddress)
86120 {
87121 int isgl = 0;
——@@ -100,6 +134,22 @@
101135 CloseHandle(hSnapshot);
102136 return isgl;
103137 }
 138+
 139+/**
 140+ * Creates an IDirectDraw compatible interface to the DXGL graphics library.
 141+ * @param lpGUID
 142+ * Address to the GUID of the device to be created, or NULL for the current
 143+ * display. Currently, only NULL is supported.
 144+ * @param lplpDD
 145+ * Pointer to an address to be filled with an IDirectDraw compatible interface.
 146+ * To retreive a pointer to a later DirectDraw or Direct3D interface, call the
 147+ * QueryInterface method in the returned object.
 148+ * @param pUnkOuter
 149+ * Unused, should be NULL.
 150+ * @return
 151+ * Returns DD_OK if lplpDD points to an IDirectDraw pointer, or an error code
 152+ * otherwise.
 153+ */
104154 HRESULT WINAPI DirectDrawCreate(GUID FAR *lpGUID, LPDIRECTDRAW FAR *lplpDD, IUnknown FAR *pUnkOuter)
105155 {
106156 if(gllock || IsCallerOpenGL(_ReturnAddress()))
——@@ -137,11 +187,43 @@
138188 *lplpDD = (LPDIRECTDRAW)myddraw;
139189 return error;
140190 }
 191+
 192+/**
 193+ * Creates an IDirectDrawClipper compatible interface.
 194+ * @param dwFlags
 195+ * Unused, set to 0.
 196+ * @param lplpDD
 197+ * Pointer to an address to be filled with an IDirectDrawClipper compatible
 198+ * interface.
 199+ * @param pUnkOuter
 200+ * Unused, should be NULL.
 201+ * @return
 202+ * Returns DD_OK if lplpDD points to an IDirectDrawClipper pointer, or an error
 203+ * code otherwise.
 204+ */
141205 HRESULT WINAPI DirectDrawCreateClipper(DWORD dwFlags, LPDIRECTDRAWCLIPPER FAR *lplpDDClipper, IUnknown FAR *pUnkOuter)
142206 {
143207 *lplpDDClipper = new glDirectDrawClipper(dwFlags,NULL);
144208 return DD_OK;
145209 }
 210+
 211+/**
 212+ * Creates an IDirectDraw7 compatible interface to the DXGL graphics library.
 213+ * @param lpGUID
 214+ * Address to the GUID of the device to be created, or NULL for the current
 215+ * display. Currently, only NULL is supported.
 216+ * @param lplpDD
 217+ * Pointer to an address to be filled with an IDirectDraw7 compatible interface.
 218+ * To retreive a pointer to a later DirectDraw or Direct3D interface, call the
 219+ * QueryInterface method in the returned object.
 220+ * @param iid
 221+ * Must be set to IID_IDirectDraw7
 222+ * @param pUnkOuter
 223+ * Unused, should be NULL.
 224+ * @return
 225+ * Returns DD_OK if lplpDD points to an IDirectDraw7 pointer, or an error code
 226+ * otherwise.
 227+ */
146228 HRESULT WINAPI DirectDrawCreateEx(GUID FAR *lpGUID, LPVOID *lplpDD, REFIID iid, IUnknown FAR *pUnkOuter)
147229 {
148230 if(ddenabled) return DDERR_DIRECTDRAWALREADYCREATED;
——@@ -148,7 +230,7 @@
149231 GetCurrentConfig(&dxglcfg);
150232 glDirectDraw7 *myddraw;
151233 HRESULT error;
152 - if(iid != IID_IDirectDraw7) ERR(DDERR_UNSUPPORTED);
 234+ if(iid != IID_IDirectDraw7) ERR(DDERR_INVALIDPARAMS);
153235 myddraw = new glDirectDraw7(lpGUID,pUnkOuter);
154236 error = myddraw->err();
155237 if(error != DD_OK)
——@@ -161,6 +243,7 @@
162244 return error;
163245 }
164246
 247+/// Callback wrapper for DirectDrawEnumerateA
165248 BOOL WINAPI DDEnumA(GUID FAR *guid, LPSTR lpDriverDescription, LPSTR lpDriverName, LPVOID lpContext, HMONITOR hMonitor)
166249 {
167250 int *context = (int *)lpContext;
——@@ -168,6 +251,17 @@
169252 return callback(guid,lpDriverDescription,lpDriverName,(LPVOID)context[1]);
170253 }
171254
 255+/**
 256+ * Enumerates the available device GUIDs for DXGL, ANSI character format.
 257+ * Legacy call, uses DirectDrawEnumerateExA
 258+ * @param lpCallback
 259+ * Address of the function to call for each enumerated object.
 260+ * @param lpContext
 261+ * Pointer to be passed to the callback function.
 262+ * @return
 263+ * Returns DD_OK if the call succeeds, or DDERR_INVALIDPARAMS if lpCallback
 264+ * is invalid.
 265+ */
172266 HRESULT WINAPI DirectDrawEnumerateA(LPDDENUMCALLBACKA lpCallback, LPVOID lpContext)
173267 {
174268 if(IsBadReadPointer(lpCallback)) return DDERR_INVALIDPARAMS;
——@@ -177,6 +271,7 @@
178272 return DirectDrawEnumerateExA(DDEnumA,&context,0);
179273 }
180274
 275+/// Callback wrapper for DirectDrawEnumerateW
181276 BOOL WINAPI DDEnumW(GUID FAR *guid, LPWSTR lpDriverDescription, LPWSTR lpDriverName, LPVOID lpContext, HMONITOR hMonitor)
182277 {
183278 int *context = (int *)lpContext;
——@@ -184,6 +279,17 @@
185280 return callback(guid,lpDriverDescription,lpDriverName,(LPVOID)context[1]);
186281 }
187282
 283+/**
 284+ * Enumerates the available device GUIDs for DXGL, Unicode character format.
 285+ * Legacy call, uses DirectDrawEnumerateExW
 286+ * @param lpCallback
 287+ * Address of the function to call for each enumerated object.
 288+ * @param lpContext
 289+ * Pointer to be passed to the callback function.
 290+ * @return
 291+ * Returns DD_OK if the call succeeds, or DDERR_INVALIDPARAMS if lpCallback
 292+ * is invalid.
 293+ */
188294 HRESULT WINAPI DirectDrawEnumerateW(LPDDENUMCALLBACKW lpCallback, LPVOID lpContext)
189295 {
190296 if(IsBadReadPointer(lpCallback)) return DDERR_INVALIDPARAMS;
——@@ -193,6 +299,8 @@
194300 return DirectDrawEnumerateExW(DDEnumW,&context,0);
195301 }
196302
 303+/// Callback wrapper for DirectDrawEnumerateExA
 304+/// Converts Unicode strings to ANSI.
197305 BOOL WINAPI DDEnumExA(GUID FAR *guid, LPWSTR lpDriverDescription, LPWSTR lpDriverName, LPVOID lpContext, HMONITOR hMonitor)
198306 {
199307 int *context = (int *)lpContext;
——@@ -204,6 +312,20 @@
205313 return callback(guid,desc,driver,(LPVOID)context[1],hMonitor);
206314 }
207315
 316+/**
 317+ * Enumerates the available device GUIDs for DXGL, ANSI character format.
 318+ * Uses DirectDrawEnumerateExW
 319+ * @param lpCallback
 320+ * Address of the function to call for each enumerated object.
 321+ * @param lpContext
 322+ * Pointer to be passed to the callback function.
 323+ * @param dwFlags
 324+ * Use DDENUM_ATTACHEDSECONDARYDEVICES to enumerate display devices attached
 325+ * to the system.
 326+ * @return
 327+ * Returns DD_OK if the call succeeds, or DDERR_INVALIDPARAMS if lpCallback
 328+ * is invalid.
 329+ */
208330 HRESULT WINAPI DirectDrawEnumerateExA(LPDDENUMCALLBACKEXA lpCallback, LPVOID lpContext, DWORD dwFlags)
209331 {
210332 if(IsBadReadPointer(lpCallback)) return DDERR_INVALIDPARAMS;
——@@ -213,6 +335,14 @@
214336 return DirectDrawEnumerateExW(DDEnumExA,&context,dwFlags);
215337 }
216338
 339+/**
 340+ * Callback for EnumDisplayMonitors.
 341+ * @param hMonitor
 342+ * Handle to display device found by EnumDisplayMonitors.
 343+ * @param ptr
 344+ * Pointer to list of display devices. First value is the number of devices
 345+ * found so far. Subsequent values are stored display device handles.
 346+ */
217347 BOOL CALLBACK MonitorEnum(HMONITOR hMonitor, HDC unused, LPRECT unused2, LPARAM ptr)
218348 {
219349 int * monitors = *(int**)ptr;
——@@ -228,6 +358,19 @@
229359 return TRUE;
230360 }
231361
 362+/**
 363+ * Enumerates the available device GUIDs for DXGL, Unicode character format.
 364+ * @param lpCallback
 365+ * Address of the function to call for each enumerated object.
 366+ * @param lpContext
 367+ * Pointer to be passed to the callback function.
 368+ * @param dwFlags
 369+ * Use DDENUM_ATTACHEDSECONDARYDEVICES to enumerate display devices attached
 370+ * to the system.
 371+ * @return
 372+ * Returns DD_OK if the call succeeds, or DDERR_INVALIDPARAMS if lpCallback
 373+ * is invalid.
 374+ */
232375 HRESULT WINAPI DirectDrawEnumerateExW(LPDDENUMCALLBACKEXW lpCallback, LPVOID lpContext, DWORD dwFlags)
233376 {
234377 if(IsBadReadPointer(lpCallback)) return DDERR_INVALIDPARAMS;
——@@ -253,10 +396,30 @@
254397 }
255398 return DD_OK;
256399 }
 400+
 401+/**
 402+ * Tells the operating system whether it can unload the DLL.
 403+ * @return
 404+ * Currently returns S_FALSE, preventing the operating system from unloading
 405+ * the DLL until the application terminates.
 406+ */
257407 HRESULT WINAPI DllCanUnloadNow()
258408 {
259409 return S_FALSE;
260410 }
 411+
 412+/**
 413+ * Creates an IClassFactory object to retrieve a DirectDraw object using COM.
 414+ * @param rclsid
 415+ * Must be one of the following: CLSID_DirectDraw, CLSID_DirectDraw7, or
 416+ * CLSID_DirectDrawClipper
 417+ * @param riid
 418+ * Must be IID_IUnknown or IID_IClassFactory.
 419+ * @param ppv
 420+ * Pointer to an address to the IClassFactory object created by this call.
 421+ * @return
 422+ * Returns S_OK if the call succeeds, or an error otherwise.
 423+ */
261424 HRESULT WINAPI DllGetClassObject(REFCLSID rclsid, REFIID riid, LPVOID *ppv)
262425 {
263426 if((rclsid != CLSID_DirectDraw) && (rclsid != CLSID_DirectDraw7) &&
——@@ -268,32 +431,48 @@
269432 factory->Release();
270433 return result;
271434 }
 435+
 436+/// Stub for function found in system ddraw.dll
272437 DDRAW_API void WINAPI GetDDSurfaceLocal()
273438 {
274439 FIXME("GetDDSurfaceLocal: stub\n");
275440 }
 441+
 442+/// Stub for function found in system ddraw.dll
 443+/// This function gets called by the fnddraw.exe test application.
276444 DDRAW_API HANDLE WINAPI GetOLEThunkData(int i1)
277445 {
278446 DEBUG("GetOleThunkData: stub\n");
279447 return 0;
280448 }
 449+
 450+/// Stub for function found in system ddraw.dll
 451+/// Function import is GetSurfaceFromDC
281452 DDRAW_API HRESULT WINAPI GlobalGetSurfaceFromDC(LPDIRECTDRAW7 lpDD, HDC hdc, LPDIRECTDRAWSURFACE7 *lpDDS)
282453 {
283454 FIXME("GetSurfaceFromDC: Verify proper referencing for LPDIRECTDRAW7\n");
284455 return lpDD->GetSurfaceFromDC(hdc,lpDDS);
285456 }
 457+
 458+/// Stub for function found in system ddraw.dll
286459 DDRAW_API void WINAPI RegisterSpecialCase()
287460 {
288461 FIXME("RegisterSpecialCase: stub\n");
289462 }
 463+
 464+/// Stub for function found in system ddraw.dll
290465 DDRAW_API void WINAPI ReleaseDDThreadLock()
291466 {
292467 FIXME("ReleaseDDThreadLock: stub\n");
293468 }
 469+
 470+/// Stub for function found in system ddraw.dll
294471 DDRAW_API void WINAPI SetAppCompatData()
295472 {
296473 FIXME("SetAppCompatData: stub\n");
297474 }
 475+
 476+/// Stub for function found in system ddraw.dll
298477 DDRAW_API BOOL IsDXGLDDraw()
299478 {
300479 return TRUE;
Retrieved from "https://dxgl.org/wiki/Special:Code/DXGL/148"