From: Ziliang Guo Date: Wed, 2 Jan 2008 05:26:00 +0000 (+0000) Subject: Finish editing all the documentation in ntddraw. X-Git-Tag: backups/curicon_rewrite@32816~156 X-Git-Url: https://git.reactos.org/?p=reactos.git;a=commitdiff_plain;h=9ee4137a1e3c2a8bad4911d97b4c2a238427cd25 Finish editing all the documentation in ntddraw. svn path=/trunk/; revision=31552 --- diff --git a/reactos/subsystems/win32/win32k/ntddraw/d3d.c b/reactos/subsystems/win32/win32k/ntddraw/d3d.c index 67ea6e76985..46bc625cce7 100644 --- a/reactos/subsystems/win32/win32k/ntddraw/d3d.c +++ b/reactos/subsystems/win32/win32k/ntddraw/d3d.c @@ -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 @@ -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. +* 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 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 +* 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 @@ NtGdiDdCanCreateD3DBuffer(HANDLE hDirectDraw, * @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. +* 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 call are redirect to -* same functions in the dxg.sys. So they are working exacly same. everthing else is lying if they -* are diffent. +* dxg.sys NtGdiD3dContextCreate calls are redirected to the same function in the dxg.sys. As such they all work the same way. * -* 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 +* 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 @@ NtGdiD3dContextCreate(HANDLE hDirectDrawLocal, * @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 +* The context data we want to destroy * * @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. +* dxg.sys NtGdiD3dContextDestroy calls are redirected to the same functions in the dxg.sys. As such they all work the same way. * -* 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 +* 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 @@ NtGdiD3dContextDestroy(LPD3DNTHAL_CONTEXTDESTROYDATA pContextDestroyData) * @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. +* dxg.sys NtGdiD3dContextDestroy calls are redirected to the same function in the dxg.sys. As such they all work the same way. * -* 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 +* 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. * -* 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 +* 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 @@ NtGdiD3dContextDestroyAll(LPD3DNTHAL_CONTEXTDESTROYALLDATA pdcad) * @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 -* +* * * @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 -* +* * * @param DD_SURFACE_LOCAL *puSurfaceLocalData -* +* * * @param DD_SURFACE_MORE *puSurfaceMoreData -* +* * * @param PDD_CREATESURFACEDATA puCreateSurfaceData -* +* * * @param HANDLE *puhSurface -* +* * * @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 diff --git a/reactos/subsystems/win32/win32k/ntddraw/ddraw.c b/reactos/subsystems/win32/win32k/ntddraw/ddraw.c index 2e08dc6a881..39e45544cb5 100644 --- a/reactos/subsystems/win32/win32k/ntddraw/ddraw.c +++ b/reactos/subsystems/win32/win32k/ntddraw/ddraw.c @@ -157,11 +157,11 @@ NtGdiDdCreateDirectDrawObject(HDC hdc) * @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 @@ NtGdiDdCreateDirectDrawObject(HDC hdc) * 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 diff --git a/reactos/subsystems/win32/win32k/ntddraw/eng.c b/reactos/subsystems/win32/win32k/ntddraw/eng.c index 09cac8b3596..9e32c1d8dd4 100644 --- a/reactos/subsystems/win32/win32k/ntddraw/eng.c +++ b/reactos/subsystems/win32/win32k/ntddraw/eng.c @@ -116,8 +116,8 @@ EngFreePrivateUserMem(PDD_SURFACE_LOCAL psl, * @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 @@ EngFreePrivateUserMem(PDD_SURFACE_LOCAL psl, * 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 @@ EngDxIoctl(ULONG ulIoctl, * @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 @@ EngLockDirectDrawSurface(HANDLE hSurface) * @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