directx8_docs_readme.txt

VC下DirectX8的开发手册

  [in] Minimum z-value of the view volume.
zf
  [in] Maximum z-value of the view volume.


Topic: D3DXMatrixPerspectiveOffCenterRH
---------------------------------------
The correct description for the parameters are:
pOut
  [in, out] Pointer to the D3DXMATRIX structure that is the result of the operation.
l
  [in] Minimum x-value of view-volume.
r
  [in] Maximum x-value of view-volume.
t
  [in] Minimum y-value of view-volume.
b
  [in] Maximum y-value of view-volume.
zn
  [in] Minimum z-value of the view volume.
zf
  [in] Maximum z-value of the view volume.


Topic: D3DXPLANE Extensions
---------------------------
The correct header for this topic is: D3dx8math.h


Topic: D3DXQUATERNION Extensions
--------------------------------
The correct header for this topic is: D3dx8math.h


Topic: D3DXVECTOR2 Extensions
-----------------------------
The correct header for this topic is: D3dx8math.h


Topic: D3DXVECTOR3 Extensions
------------------------------
The correct header for this topic is: D3dx8math.h


Topic: D3DXVECTOR4 Extensions
-----------------------------
The correct header for this topic is: D3dx8math.h


Topic: IDirect3DCubeTexture8::AddDirtyRect
------------------------------------------
The following is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a 
texture. For sub-levels, it is assumed that the corresponding (scaled) rectangle
or box is also dirty. Dirty regions are automatically recorded when LockRect or
LockBox is called without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. Also, the
destination surface of a CopyRects call is marked dirty.


Topic: IDirect3DCubeTexture8::LockRect
--------------------------------------
The following is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a
texture. Dirty regions are automatically recorded when LockRect is called
without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. See 
IDirect3DDevice8::UpdateTexture for more information.


Topic: IDirect3DDevice8::CopyRects
----------------------------------
The following is missing from the remarks section:
If the destination surface is a level-zero of a texture, then it will be marked
dirty. See IDirect3DDevice8::UpdateTexture and IDirect3DTexture8::AddDirtyRect 
for more details.


Topic: IDirect3DDevice8::DrawPrimitiveUP
----------------------------------------
The following comment was added to the remarks section:
The vertex data passed to DrawPrimitiveUP does not need to persist after the
call. Direct3D completes its access to that data prior to returning from the
call.


Topic: IDirect3DDevice8::DrawIndexedPrimitiveUP
-----------------------------------------------
The following comment was added to the remarks section:
The vertex data passed to DrawIndexPrimitiveUP does not need to persist after
the call. Direct3D completes its access to that data prior to returning from the
call.


Topic: IDirect3DDevice8::SetStreamSource
----------------------------------------
Disregard the following sentence in the Remarks section:

When the texture is no longer needed, set the texture at 
the appropriate stage to NULL.


Topic: IDirect3DDevice8::UpdateTexture
--------------------------------------
Disregard the following sentence in the Remarks section:
When the texture is no longer needed, set the texture at the appropriate stage
to NULL.

The followin is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a
texture. For sub-levels, it is assumed that the corresponding (scaled) rectangle
or box is also dirty. Dirty regions are automatically recorded when LockRect or
LockBox is called without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. Also, the
destination surface of a CopyRects call is marked dirty.


Topic: IDirect3DSurface8::LockRect
----------------------------------
The following is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a
texture. Dirty regions are automatically recorded when LockRect is called
without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. See 
IDirect3DDevice8::UpdateTexture for more information.


Topic: IDirect3DTexture8::AddDirtyRect
--------------------------------------
The following is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a 
texture. For sub-levels, it is assumed that the corresponding (scaled) rectangle
or box is also dirty. Dirty regions are automatically recorded when LockRect or
LockBox is called without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. Also, the
destination surface of a CopyRects call is marked dirty.


Topic: IDirect3DTexture8::LockRect
----------------------------------
The following is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a
texture. Dirty regions are automatically recorded when LockRect is called
without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. See 
IDirect3DDevice8::UpdateTexture for more information.


Topic: IDirect3DVolume8::LockBox
--------------------------------
The following is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a
texture. Dirty regions are automatically recorded when LockBox is called
without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. See 
IDirect3DDevice8::UpdateTexture for more information.


Topic: IDirect3DVolumeTexture8::AddDirtyBox
-------------------------------------------
The following is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a 
texture. For sub-levels, it is assumed that the corresponding (scaled) rectangle
or box is also dirty. Dirty regions are automatically recorded when LockRect or
LockBox is called without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. Also, the
destination surface of a CopyRects call is marked dirty.


Topic: IDirect3DVolumeTexture8::LockBox
---------------------------------------
The following is missing from the remarks section:
For performance reasons, dirty regions are only recorded for level zero of a
texture. Dirty regions are automatically recorded when LockBox is called
without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. See 
IDirect3DDevice8::UpdateTexture for more information.


Topic: mad - Pixel Shader
-------------------------
The remarks section is incorrect. The correct remarks section is below.
This instruction performs a multiply-accumulate operation. It takes the first 
two arguments, multiplies them together, and adds them to the remaining 
input/source argument, and places that into the result register. 

This instruction performs the multiply-add based on the following formula.
tSrc0 * tSrc1 + tSrc2

The following example shows how this instruction might be used.
mad  d, s0, s1, s2;    d = s0 * s1 + s2



DirectX Graphics (Visual Basic)
===============================

---------------
Overview Topics
---------------


Topic: Constant Value Syntax
----------------------------
The example shown the pixel shader is incorrect. A valid sample is shown below:

asm
{
    ps.1.0
    tex t0
    mov r0, t0
}


Topic: Lost Devices and Retrieved Data
--------------------------------------
This topic does not apply to IDirect3DDevice8::UpdateTexture.


Topic: Setting Material Properties
----------------------------------
The code sample does not initialize the emissive properties, 
which would be undefined. The emissive property needs to 
be initalized before the material can be used. The code 
sample below can be added to the code sample in this topic to
make it complete.

' Set the RGBA for emissive color.
mat.Emissive.r = 0#
mat.Emissive.g = 0#
mat.Emissive.b = 0#
mat.Emissive.a = 0#


Topic: Using Dynamic Vertex and Index Buffers
---------------------------------------------
The second usage style is missing a call to Unlock. The correct code for usage
style 2 is below:

for loop()
{
    pVB->Lock(...D3DLOCK_DISCARD...); //Ensures that hardware doesn't 
                                      //stall by returning a new 
                                      //pointer.
    Fill data (optimally 1000s of vertices/indices, no fewer) in pBuffer.
    pBuffer->Unlock
    for loop( 100s of times )
    {
        Change State
        DrawPrimitive() or DrawIndexPrimitives() //Tens of primitives
    }
}


------------------
Reference Section
------------------
 
Topic: CONST_D3DRENDERSTATETYPE
--------------------------------
The last sentence for the description of D3DRS_ALPHABLENDENABLE 
is incorrect and can be ignored.

Topic: D3DCAPS8
---------------
The description of Presentation Intervals should read:
  Bit mask of values representing what presentation swap 
  intervals are available.


Topic: D3DX8.LoadSurfaceFromFile
--------------------------------
The following is missing from the remarks section:
Writing to a non-level-zero surface will not cause the dirty rectangle to be 
updated. If D3DX8.LoadSurfaceFromFileA is called and the surface was not already 
dirty (this is unlikely under normal usage scenarios), the application needs to 
explicitly call Direct3DTexture8.AddDirtyRect on the surface.


Topic: D3DX8.LoadSurfaceFromFileInMemory
----------------------------------------
The following is missing from the remarks section:
Writing to a non-level-zero surface will not cause the dirty rectangle to be 
updated. If D3DX8.LoadSurfaceFromFileInMemory is called and the surface was not 
already dirty (this is unlikely under normal usage scenarios), the application 
needs to explicitly call Direct3DTexture8.AddDirtyRect on the surface.


Topic: D3DX8.LoadSurfaceFromMemory
----------------------------------
The following is missing from the remarks section:
Writing to a non-level-zero surface will not cause the dirty rectangle to be
updated. If D3DXLoadSurfaceFromMemory is called and the surface was not already 
dirty (this is unlikely under normal usage scenarios), the application needs to 
explicitly call Direct3DTexture8.AddDirtyRect on the surface.


Topic: D3DXLoadSurfaceFromResource
----------------------------------
The following is missing from the remarks section:
Writing to a non-level-zero surface will not cause the dirty rectangle to be 
updated. If D3DX8.LoadSurfaceFromResource is called and the surface was not 
already dirty (this is unlikely under normal usage scenarios), the application 
needs to explicitly call Direct3DTexture8.AddDirtyRect on the surface.


Topic: D3DX8.LoadSurfaceFromSurface
-----------------------------------
The following is missing from the remarks section:
Writing to a non-level-zero surface will not cause the dirty rectangle to be 
updated. If D3DX8.LoadSurfaceFromSurface is called and the surface was not
already dirty (this is unlikely under normal usage scenarios), the application 
needs to explicitly call Direct3DTexture8.AddDirtyRect on the surface.


Topic: D3DX8.LoadVolumeFromMemory
---------------------------------
The following is missing from the remarks section:
Writing to a non-level-zero surface of the volume texture will not cause the 
dirty rectangle to be updated. If D3DX8.LoadVolumeFromMemory is called and the 
texture was not already dirty (this is unlikely under normal usage scenarios), 
the application needs to explicitly call Direct3DVolumeTexture8.AddDirtyBox on
the volume texture.


Topic: D3DX8.LoadVolumeFromVolume
---------------------------------
The following is missing from the remarks section:
Writing to a non-level-zero surface of the volume texture will not cause the 
dirty rectangle to be updated. If D3DX8.LoadVolumeFromVolume is called and the 
surface was not already dirty (this is unlikely under normal usage scenarios), 
the application needs to explicitly call Direct3DVolumeTexture8.AddDirtyBox on
the surface.


Topic: D3DXMatrixPerspectiveOffCenterLH
---------------------------------------
The correct description for the parameters are:
pOut
  [in, out] Pointer to the D3DXMATRIX structure that is the result of the operation.
l
  [in] Minimum x-value of view-volume.
r
  [in] Maximum x-value of view-volume.
t
  [in] Minimum y-value of view-volume.
b
  [in] Maximum y-value of view-volume.
zn
  [in] Minimum z-value of the view volume.
zf
  [in] Maximum z-value of the view volume.


Topic: D3DXMatrixPerspectiveOffCenterRH
---------------------------------------