[zguo] 31552: Finish editing all the documentation in ntddraw.

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