Author: zguo
Date: Wed Jan 2 08:26:00 2008
New Revision: 31552
URL: http://svn.reactos.org/svn/reactos?rev=31552&view=rev
Log:
Finish editing all the documentation in ntddraw.
Modified:
trunk/reactos/subsystems/win32/win32k/ntddraw/d3d.c
trunk/reactos/subsystems/win32/win32k/ntddraw/ddraw.c
trunk/reactos/subsystems/win32/win32k/ntddraw/eng.c
Modified: trunk/reactos/subsystems/win32/win32k/ntddraw/d3d.c
URL: http://svn.reactos.org/svn/reactos/trunk/reactos/subsystems/win32/win32k/nt…
==============================================================================
--- trunk/reactos/subsystems/win32/win32k/ntddraw/d3d.c (original)
+++ trunk/reactos/subsystems/win32/win32k/ntddraw/d3d.c Wed Jan 2 08:26:00 2008
@@ -9,8 +9,8 @@
*/
/* Comment
- * NtGdiDdLock and NtGdiDdLockD3D at end calls to same api in the dxg.sys
- * NtGdiDdUnlock and NtGdiDdUnlockD3D at end calls to same api in the dxg.sys
+ * NtGdiDdLock and NtGdiDdLockD3D ultimately call the same function in dxg.sys
+ * NtGdiDdUnlock and NtGdiDdUnlockD3D ultimately call the same function in dxg.sys
*/
#include <w32k.h>
@@ -33,22 +33,22 @@
*
* @return
-* Depending on if the driver supports this API or not, DDHAL_DRIVER_HANDLED
+* Depending on if the driver supports this function or not, DDHAL_DRIVER_HANDLED
* or DDHAL_DRIVER_NOTHANDLED is returned.
* To check if the function has been successful, do a full check.
* A full check is done by checking if the return value is DDHAL_DRIVER_HANDLED
* and puCanCreateSurfaceData->ddRVal is set to DD_OK.
*
* @remarks.
-* dxg.sys NtGdiDdCanCreateD3DBuffer and NtGdiDdCanCreateSurface call are redirect to dxg.sys
-* inside the dxg.sys they ar redirect to same functions. examine the driver list functions
-* table, the memory address you will see they are pointed to same memory address.
-*
-* Before call to this api please set the puCanCreateSurfaceData->ddRVal to a error value example DDERR_NOTUSPORTED.
-* for the ddRVal will other wise be unchange if some error happen inside the driver.
-* puCanCreateSurfaceData->lpDD is pointer to DDRAWI_DIRECTDRAW_GBL, MSDN say it is PDD_DIRECTDRAW_GLOBAL it is not.
-* puCanCreateSurfaceData->lpDD->hDD need also be fill in with the handle we got from NtGdiDdCreateDirectDrawObject
-* puCreateSurfaceData->CanCreateSurface pointer to the real functions the HAL or HEL, that u need fill in
+* dxg.sys NtGdiDdCanCreateD3DBuffer and NtGdiDdCanCreateSurface calls are redirected to dxg.sys.
+* Inside the dxg.sys they are redirected to the same function. Examine the memory addresses on the driver list functions
+* table and you will see they are pointed to the same memory address.
+*
+* Before calling this function please set the puCanCreateSurfaceData->ddRVal to an error value such as DDERR_NOTUSPORTED,
+* for the ddRVal will otherwise be unchanged even if an error occurs inside the driver.
+* puCanCreateSurfaceData->lpDD is a pointer to DDRAWI_DIRECTDRAW_GBL, not PDD_DIRECTDRAW_GLOBAL as MSDN claims.
+* puCanCreateSurfaceData->lpDD->hDD also needs be filled in with the handle we got from NtGdiDdCreateDirectDrawObject.
+* puCreateSurfaceData->CanCreateSurface is a pointer to the real functions in the HAL or HEL, that you need fill in.
*
*--*/
@@ -73,35 +73,33 @@
* @name NtGdiD3dContextCreate
* @implemented
*
-* The Function NtGdiDdCanCreateD3DBuffer check if you can create a
-* surface for directx it redirect the call to dxg.sys.
+* The Function NtGdiDdCanCreateD3DBuffer checks if you can create a
+* surface for Directx. It redirects the call to dxg.sys.
*
* @param HANDLE hDirectDrawLocal
* The handle we got from NtGdiDdCreateDirectDrawObject
*
* @param HANDLE hSurfColor
-* Handle to DD_SURFACE_LOCAL to be use as target rendring
+* Handle to DD_SURFACE_LOCAL to be used for the rendering target
*
* @param HANDLE hSurfZ
-* Handle to a DD_SURFACE_LOCAL it is the Z deep buffer, accdoing MSDN if it set to NULL nothing should happen.
+* Handle to a DD_SURFACE_LOCAL. It is the Z deep buffer. According MSDN if it is set to NULL nothing should happen.
*
* @param D3DNTHAL_CONTEXTCREATEDATA* hSurfZ
-* the buffer to create the context data
+* The buffer to create the context data
*
* @return
-* DDHAL_DRIVER_HANDLED or DDHAL_DRIVER_NOTHANDLED if the driver support this api.
-* Todo full check if we sussess is to check the return value DDHAL_DRIVER_HANDLED
-* puCanCreateSurfaceData->ddRVal are set to DD_OK.
-*
-*
-* @remarks.
-* dxg.sys NtGdiD3dContextCreate call are redirect to
-* same functions in the dxg.sys. So they are working exacly same. everthing else is lying if they
-* are diffent.
-*
-* Before call to this api please set the hSurfZ->ddRVal to a error value example DDERR_NOTUSPORTED.
-* for the ddRVal will other wise be unchange if some error happen inside the driver.
-* hSurfZ->dwhContext need also be fill in with the handle we got from NtGdiDdCreateDirectDrawObject
+* DDHAL_DRIVER_HANDLED or DDHAL_DRIVER_NOTHANDLED if the driver supports this function.
+* A full check is done by checking if the return value is DDHAL_DRIVER_HANDLED
+* and puCanCreateSurfaceData->ddRVal is set to DD_OK.
+*
+*
+* @remarks.
+* dxg.sys NtGdiD3dContextCreate calls are redirected to the same function in the dxg.sys. As such they all work the same way.
+*
+* Before calling this function please set the hSurfZ->ddRVal to an error value such as DDERR_NOTUSPORTED,
+* for the ddRVal will otherwise be unchanged even if an error occurs inside the driver.
+* hSurfZ->dwhContext also needs to be filled in with the handle we got from NtGdiDdCreateDirectDrawObject
*
*--*/
BOOL
@@ -127,19 +125,17 @@
* @name NtGdiD3dContextDestroy
* @implemented
*
-* The Function NtGdiD3dContextDestroy Destory the context data we got from NtGdiD3dContextCreate
+* The Function NtGdiD3dContextDestroy destorys the context data we got from NtGdiD3dContextCreate
*
* @param LPD3DNTHAL_CONTEXTDESTROYDATA pContextDestroyData
-* The context data we want to destory
-*
-* @remarks.
-* dxg.sys NtGdiD3dContextDestroy call are redirect to
-* same functions in the dxg.sys. So they are working exacly same. everthing else is lying if they
-* are diffent.
-*
-* Before call to this api please set the pContextDestroyData->ddRVal to a error value example DDERR_NOTUSPORTED.
-* for the ddRVal will other wise be unchange if some error happen inside the driver.
-* pContextDestroyData->dwhContext need also be fill in with the handle we got from NtGdiDdCreateDirectDrawObject
+* The context data we want to destroy
+*
+* @remarks.
+* dxg.sys NtGdiD3dContextDestroy calls are redirected to the same functions in the dxg.sys. As such they all work the same way.
+*
+* Before calling this function please set the pContextDestroyData->ddRVal to an error value such DDERR_NOTUSPORTED,
+* for the ddRVal will otherwise be unchanged even if an error occurs inside the driver.
+* pContextDestroyData->dwhContext also needs to be filled in with the handle we got from NtGdiDdCreateDirectDrawObject
*
*--*/
DWORD
@@ -162,23 +158,21 @@
* @name NtGdiD3dContextDestroyAll
* @implemented
*
-* The Function NtGdiD3dContextDestroyAll Destory the all context data we got in a process
-* The data have been alloc with NtGdiD3dContextCreate
+* The Function NtGdiD3dContextDestroyAll destroys all the context data in a process
+* The data having been allocated with NtGdiD3dContextCreate
*
* @param LPD3DNTHAL_CONTEXTDESTROYALLDATA pdcad
* The context data we want to destory
*
* @remarks.
-* dxg.sys NtGdiD3dContextDestroyAll call are redirect to
-* same functions in the dxg.sys. So they are working exacly same. everthing else is lying if they
-* are diffent.
-*
-* Before call to this api please set the pdcad->ddRVal to a error value example DDERR_NOTUSPORTED.
-* for the ddRVal will other wise be unchange if some error happen inside the driver.
-* pdcad->dwPID need also be fill in with the Process ID we need destore the data for
-*
-* Waring MSDN is wrong about this api. it say it queare free memory and it does not accpect
-* any parama, last time checked in msdn 19/10-2007
+* dxg.sys NtGdiD3dContextDestroy calls are redirected to the same function in the dxg.sys. As such they all work the same way.
+*
+* Before calling this function please set the pdcad->ddRVal to an error value such as DDERR_NOTUSPORTED,
+* for the ddRVal will otherwise be unchanged even if an error occurs inside the driver.
+* pdcad->dwPID also needs to be filled in with the ID of the process that needs its context data destroyed.
+*
+* Warning: MSDN is wrong about this function. It claims the function queries free memory and does not accept
+* any parameters. Last time MSDN checked: 19/10-2007
*--*/
DWORD
STDCALL
@@ -200,51 +194,51 @@
* @name NtGdiDdCreateD3DBuffer
* @implemented
*
-* The function NtGdiDdCreateD3DBuffer create a
+* The function NtGdiDdCreateD3DBuffer creates a
* surface for DirectX. It is redirected to dxg.sys.
*
* @param HANDLE hDirectDraw
* The handle we got from NtGdiDdCreateDirectDrawObject
*
* @param HANDLE *hSurface
-* <FILMEIN>
+* <FILLMEIN>
*
* @param DDSURFACEDESC puSurfaceDescription
-* surface desc what kind of surface it should be, example rgb, compress, deep, and more,
-* see DDSURFACEDESC for more infomations
+* Surface description: what kind of surface it should be. Examples: RGB, compress, deep, and etc
+* See DDSURFACEDESC for more information
*
* @param DD_SURFACE_GLOBAL *puSurfaceGlobalData
-* <FILMEIN>
+* <FILLMEIN>
*
* @param DD_SURFACE_LOCAL *puSurfaceLocalData
-* <FILMEIN>
+* <FILLMEIN>
*
* @param DD_SURFACE_MORE *puSurfaceMoreData
-* <FILMEIN>
+* <FILLMEIN>
*
* @param PDD_CREATESURFACEDATA puCreateSurfaceData
-* <FILMEIN>
+* <FILLMEIN>
*
* @param HANDLE *puhSurface
-* <FILMEIN>
+* <FILLMEIN>
*
* @return
-* Depending on if the driver supports this API or not, DDHAL_DRIVER_HANDLED
+* Depending on if the driver supports this function or not, DDHAL_DRIVER_HANDLED
* or DDHAL_DRIVER_NOTHANDLED is returned.
-* To check if the function has been successful, do a full check.
+* To check if the function was successful, do a full check.
* A full check is done by checking if the return value is DDHAL_DRIVER_HANDLED
* and puCanCreateSurfaceData->ddRVal is set to DD_OK.
*
* @remarks.
-* dxg.sys NtGdiDdCreateD3DBuffer and NtGdiDdCreateSurface call are redirect to dxg.sys
-* inside the dxg.sys they ar redirect to same functions. examine the driver list functions
-* table, the memory address you will see they are pointed to same memory address.
-*
-* Before call to this api please set the puCreateSurfaceData->ddRVal to a error value example DDERR_NOTUSPORTED.
-* for the ddRVal will other wise be unchange if some error happen inside the driver.
-* puCreateSurfaceData->lpDD is pointer to DDRAWI_DIRECTDRAW_GBL, MSDN say it is PDD_DIRECTDRAW_GLOBAL it is not.
-* puCreateSurfaceData->lpDD->hDD need also be fill in with the handle we got from NtGdiDdCreateDirectDrawObject
-* puCreateSurfaceData->CreateSurface pointer to the real functions the HAL or HEL, that u need fill in
+* dxg.sys NtGdiDdCreateD3DBuffer and NtGdiDdCreateSurface calls are redirected to dxg.sys.
+* Inside the dxg.sys they are redirected to the same function. Examine the memory addresses on the driver list functions
+* table and you will see they are pointed to the same memory address.
+*
+* Before calling this function please set the puCreateSurfaceData->ddRVal to an error value such as DDERR_NOTUSPORTED,
+* for the ddRVal will otherwise be unchanged even if an error occurs inside the driver.
+* puCreateSurfaceData->lpDD is a pointer to DDRAWI_DIRECTDRAW_GBL. MSDN claims it is PDD_DIRECTDRAW_GLOBAL but it is not.
+* puCreateSurfaceData->lpDD->hDD also needs to be filled in with the handle we got from NtGdiDdCreateDirectDrawObject
+* puCreateSurfaceData->CreateSurface is a pointer to the real functions in the HAL or HEL, that you need fill in
*
*--*/
DWORD
Modified: trunk/reactos/subsystems/win32/win32k/ntddraw/ddraw.c
URL: http://svn.reactos.org/svn/reactos/trunk/reactos/subsystems/win32/win32k/nt…
==============================================================================
--- trunk/reactos/subsystems/win32/win32k/ntddraw/ddraw.c (original)
+++ trunk/reactos/subsystems/win32/win32k/ntddraw/ddraw.c Wed Jan 2 08:26:00 2008
@@ -157,11 +157,11 @@
* @name NtGdiDxgGenericThunk
* @implemented
*
-* The function NtGdiDxgGenericThunk redirect dx call to other thing.
-* from dxg.sys
+* The function NtGdiDxgGenericThunk redirects DirectX calls to another function.
+* Redirection is done in dxg.sys in XP or higher. If dxg.sys does not exist, redirection takes place in win32k.sys
*
* @param ULONG_PTR ulIndex
-* The functions we want redirct
+* The functions we want to redirect
*
* @param ULONG_PTR ulHandle
* Unknown
@@ -179,11 +179,11 @@
* Unknown
*
* @return
-* always return DDHAL_DRIVER_NOTHANDLED
+* Always returns DDHAL_DRIVER_NOTHANDLED
*
* @remarks.
-* dxg.sys NtGdiDxgGenericThunk call are redirect to dxg.sys
-* This api are not longer use in Windows NT 2000/XP/2003
+* dxg.sys NtGdiDxgGenericThunk calls are redirected to dxg.sys
+* This function is no longer used but is still present in Windows NT 2000/XP/2003.
*
*--*/
DWORD
Modified: trunk/reactos/subsystems/win32/win32k/ntddraw/eng.c
URL: http://svn.reactos.org/svn/reactos/trunk/reactos/subsystems/win32/win32k/nt…
==============================================================================
--- trunk/reactos/subsystems/win32/win32k/ntddraw/eng.c (original)
+++ trunk/reactos/subsystems/win32/win32k/ntddraw/eng.c Wed Jan 2 08:26:00 2008
@@ -116,8 +116,8 @@
* @name EngDxIoctl
* @implemented
*
-* The function EngDxIoctl is the ioctl call to diffent dx functions
-* to the driver dxg.sys
+* The function EngDxIoctl is the ioctl call to different DirectX functions
+* in the driver dxg.sys
*
* @param ULONG ulIoctl
* The ioctl code that we want call to
@@ -129,11 +129,11 @@
* The buffer size in bytes
*
* @return
-* always return DDERR_UNSUPPORTED
+* Always returns DDERR_UNSUPPORTED
*
* @remarks.
-* dxg.sys EngDxIoctl call are redirect to dxg.sys
-* This api are not longer use in Windows NT 2000/XP/2003
+* dxg.sys EngDxIoctl call is redirected to dxg.sys
+* This function is no longer used in Windows NT 2000/XP/2003
*
*--*/
DWORD
@@ -159,13 +159,13 @@
* @name EngLockDirectDrawSurface
* @implemented
*
-* The function EngUnlockDirectDrawSurface locking the dx surface
+* The function EngUnlockDirectDrawSurface locks the DirectX surface.
* @param HANDLE hSurface
* The handle of a surface
*
* @return
-* This return vaild or NULL pointer to PDD_SURFACE_LOCAL object
+* This return a vaild or NULL pointer to a PDD_SURFACE_LOCAL object
*
* @remarks.
* None
@@ -193,13 +193,13 @@
* @name EngUnlockDirectDrawSurface
* @implemented
*
-* The function EngUnlockDirectDrawSurface locking the dx surface
+* The function EngUnlockDirectDrawSurface unlocks the DirectX surface
* @param PDD_SURFACE_LOCAL pSurface
-* The Surface we whant lock
+* The Surface we want to unlock
*
* @return
-* This return FALSE or TRUE, FALSE for fail, TRUE for success
+* This return TRUE for success, FALSE for failure
*
* @remarks.
* None
Author: zguo
Date: Wed Jan 2 04:28:58 2008
New Revision: 31551
URL: http://svn.reactos.org/svn/reactos?rev=31551&view=rev
Log:
Grammar and spelling corrections for the documentation and comments.
Modified:
trunk/reactos/subsystems/win32/win32k/ntddraw/dxeng.c
Modified: trunk/reactos/subsystems/win32/win32k/ntddraw/dxeng.c
URL: http://svn.reactos.org/svn/reactos/trunk/reactos/subsystems/win32/win32k/nt…
==============================================================================
--- trunk/reactos/subsystems/win32/win32k/ntddraw/dxeng.c (original)
+++ trunk/reactos/subsystems/win32/win32k/ntddraw/dxeng.c Wed Jan 2 04:28:58 2008
@@ -99,7 +99,7 @@
return GdiHandleTable->flDeviceUniq;
}
-ULONG gulVisRgnUniqueness; // Inc count everytime client region is updated.
+ULONG gulVisRgnUniqueness; // Increase count everytime client region is updated.
/************************************************************************/
/* DxEngVisRgnUniq */
@@ -114,11 +114,11 @@
/************************************************************************/
/* DxEngEnumerateHdev */
/************************************************************************/
-/* Enumate all drivers in win32k */
+/* Enumerate all drivers in win32k */
HDEV *
DxEngEnumerateHdev(HDEV *hdev)
{
- /* FIXME Enumate all drivers in win32k */
+ /* FIXME Enumerate all drivers in win32k */
UNIMPLEMENTED;
return FALSE;
}
@@ -133,13 +133,13 @@
* The hdev
*
* @param PGAMMARAMP Ramp
-* to fill in our gama ramp
+* to fill in our gamma ramp
*
* @return
-* This return FALSE or TRUE, FALSE for fail, TRUE for success
+*Returns TRUE for success, FALSE for failure
*
* @remarks.
-* ReactOS does not loop it, only set the gamma once.
+* ReactOS does not loop it, only sets the gamma once.
*
*--*/
BOOL
@@ -153,13 +153,13 @@
* @name DxEngLockDC
* @implemented
*
-* The function DxEngLockDC lock a hdc from dxg.sys
+* The function DxEngLockDC locks a hdc from dxg.sys
*
* @param HDC hDC
-* The handle we need want lock
+* The handle we want to lock
*
* @return
-* This api return PDC or NULL depns if it sussess lock the hdc or not
+* Returns PDC if lock succeeded or NULL depns if it failed
*
* @remarks.
* none
@@ -176,13 +176,13 @@
* @name DxEngUnlockDC
* @implemented
*
-* The function DxEngUnlockDC Unlock a pDC (hdc) from dxg.sys
+* The function DxEngUnlockDC unlocks a pDC (hdc) from dxg.sys
* @param PDC pDC
-* The handle we need unlock
+* The handle we want to unlock
*
* @return
-* This api always return TRUE if it sussess or not
+* This function returns TRUE no matter what
*
* @remarks.
* none
@@ -283,22 +283,22 @@
* @name DxEngSetDeviceGammaRamp
* @implemented
*
-* The function DxEngSetDeviceGammaRamp Set Gamma ramp from from dxg.sys
+* The function DxEngSetDeviceGammaRamp sets gamma ramp from dxg.sys
* @param HDEV hPDev
* The hdev
*
* @param PGAMMARAMP Ramp
-* to set in our gama ramp
+* Value to change gamma ramp to
*
* @param BOOL Test
-* Testing the gama or not. FALSE for no test, TRUE for testing
+* Whether gamma should be tested. TRUE to test, FALSE to not test
*
* @return
-* This return FALSE or TRUE, FALSE for fail, TRUE for success
+*Returns TRUE for success, FALSE for failure
*
* @remarks.
-* ReactOS does not loop it, only set the gamma once.
+* ReactOS does not loop and only sets the gamma once.
*
*--*/
BOOL
@@ -405,23 +405,25 @@
* @name DxEngGetDCState
* @implemented
*
-* The function DxEngGetDCState getting sate
-* if it DC full screen / Get Complexity of visiable region or
-* Get Driver hdev, which is pPDev
+* The function DxEngGetDCState is capable of returning three
+* DC states depending on what value is passed in its second parameter:
+* 1. If the DC is full screen
+* 2. Get Complexity of visible region
+* 3. Get Driver hdev, which is pPDev
*
* @param HDC hdc
-* The hdc
+* The DC handle
*
* @param DWORD type
-* value 1 = Is DC full screen
-* value 2 = Get Complexity of visiable region.
-* value 3 = Get Driver hdev, which is pPDev.
+* value 1 = Is DC fullscreen
+* value 2 = Get Complexity of visible region.
+* value 3 = Get Driver hdev, which is a pPDev.
*
* @return
-* return one of the type value
+* Return one of the type values
*
* @remarks.
-* we do not have type 2 implement yet
+* We do not have type 2 implement yet
*
*--*/
DWORD
@@ -443,13 +445,13 @@
break;
case 3:
{
- /* Return HDEV of this DC. */
+ /* Return the HDEV of this DC. */
retVal = (DWORD) pDC->pPDev;
break;
}
default:
- /* if it does not found a type it wanted we return 0 as value */
- DPRINT1("warning did not found type %d\n",type);
+ /* if a valid type is not found, zero is returned */
+ DPRINT1("Warning did not find type %d\n",type);
break;
}
DC_UnlockDc(pDC);