directx8_docs_readme.txt

VC下DirectX8的开发手册

_______________________________________________________________________

DirectX 8.0 SDK Documentation Errata:

This section contains corrections to the following components of the DirectX SDK documentation:

  DirectX Audio (DirectMusic and DirectSound)
  DirectMusic Producer
  DirectX Graphics (C++)
  DirectX Graphics (Visual Basic)
  DirectX Input (C++)
  DirectPlay
  DirectShow

General
=======

Refer to the Accessibility documentation in the Platform SDK for
information on how to make your application accessible.


DirectX Audio (DirectMusic and DirectSound)
===========================================

-------------------
Sample Descriptions
-------------------
The path given for the C++ and Visual Basic samples is 
incorrect. All paths on the sample description pages should 
begin with "(SDK Root)\Samples", not "(SDK Root)\Sample".
 

DirectMusic Producer
=====================

Songs
------
Some of the descriptions of script methods make reference 
to segments and songs. Songs are not supported in this release.

Send Effects Topic
------------------
The following statement in the Send Effects topic is incorrect:

"You can place a Send effect at the end of an audiopath 
to route its audio output back to the beginning of any 
other audiopath."

This should read as follows:

"You can place a Send effect in a buffer's effects chain 
to route its audio output to any other buffer."


DirectX Graphics (C++)
======================

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

Topic: Architectural Overview for Direct3D
----------------------------
The diagram for this topic is mislabeled. The texture values listed in the 
"Pixel Operations" section on the bottom left hand corner should be listed
as Tex0, Tex1, and Tex 2 instead of Tex0, Tex0, Tex0.


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

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


Topic: Effect File Components
-----------------------------
The second technique in this topic is incorrect. The correct code is:

technique t1
{
    pass p0
    {
        Texture[0] = <tex0>;
        
        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;
        ColorOp[1] = Disable;  
    }
    
    pass p1
    {
        AlphaBlendEnable = True;
        SrcBlend = One;
        DestBlend = One;

        Texture[1] = <tex1>;
               
        ColorOp[1] = SelectArg1;
        ColorArg1[1] = Texture;
        ColorOp[1] = Disable;  
    }
}


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


Topic: Performance Optimizations
--------------------------------
Add the following tips:

  *  Minimize vertex buffer switches.
  *  Use static vertex buffers where possible.
  *  Use one big static vertex buffer per FVF for static 
     objects, rather than one per object.
  *  Do not copy to output registers unless necessary in 
     shaders. For example:

       mad oD0, r1, c[2], c[3] 

     rather than:

       mad r1,c[2],c[3]
       mov oD0, r1


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.0f;
mat.Emissive.g = 0.0f;
mat.Emissive.b = 0.0f;
mat.Emissive.a = 0.0f;


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
    }
}


Topic: Vertex Shader Architecture
---------------------------------------------
The diagram for this topic is missing the homogenuous position as an output.



---------------------
Reference Section
---------------------

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


Topic: D3DFVF_TEXCOORDSIZEn
----------------------------
The FVF declared in this section is invalid. The invalid 
FVF need the flag D3DFVF_TEX2 added in order to be correct.

The correct FVF declaration would be:

DWORD dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE |
              D3DFVF_SPECULAR | D3DFVF_TEX2 |
              D3DFVF_TEXCOORDSIZE1(0) |  \\ Uses 1-D texture coordinates for
                                         \\ texture coordinate set 1 (index 0).
              D3DFVF_TEXCOORDSIZE2(1);   \\ And 2-D texture coordinates for 
                                         \\ texture coordinate set 2 (index 1).


Topic: D3DRENDERSTATETYPE
--------------------------
The code sample for D3DRS_TWEENFACTOR should be:
pd3dDevice8->SetRenderState(D3DRS_TWEENFACTOR, *((DWORD*)&TweenFactor));

The last sentence for the description of D3DRS_ALPHABLENDENABLE 
is incorrect and can be ignored.


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


Topic: D3DXLoadSurfaceFromFileA
-------------------------------
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 D3DXLoadSurfaceFromFileA is called and the surface was not already 
dirty (this is unlikely under normal usage scenarios), the application needs to 
explicitly call IDirect3DTexture8::AddDirtyRect on the surface.


Topic: D3DXLoadSurfaceFromFileInMemory
--------------------------------------
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 D3DXLoadSurfaceFromFileInMemory is called and the surface was not 
already dirty (this is unlikely under normal usage scenarios), the application 
needs to explicitly call IDirect3DTexture8::AddDirtyRect on the surface.


Topic: D3DXLoadSurfaceFromFileW
-------------------------------
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 D3DXLoadSurfaceFromFileW is called and the surface was not already 
dirty (this is unlikely under normal usage scenarios), the application needs to 
explicitly call IDirect3DSurface8::AddDirtyRect on the surface.


Topic: D3DXLoadSurfaceFromMemory
--------------------------------
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 IDirect3DTexture8::AddDirtyRect on the surface.


Topic: D3DXLoadSurfaceFromResourceA
-----------------------------------
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 D3DXLoadSurfaceFromResourceA is called and the surface was not 
already dirty (this is unlikely under normal usage scenarios), the application 
needs to explicitly call IDirect3DTexture8::AddDirtyRect on the surface.


Topic: D3DXLoadSurfaceFromResourceW
-----------------------------------
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 D3DXLoadSurfaceFromResourceW is called and the surface was not 
already dirty (this is unlikely under normal usage scenarios), the application 
needs to explicitly call IDirect3DTexture8.AddDirtyRect on the surface.


Topic: D3DXLoadSurfaceFromSurface
---------------------------------
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 D3DXLoadSurfaceFromSurface is called and the surface was not already
dirty (this is unlikely under normal usage scenarios), the application needs to 
explicitly call IDirect3DTexture8::AddDirtyRect on the surface.


Topic: D3DXLoadVolumeFromMemory
-------------------------------
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 D3DXLoadVolumeFromMemory is called and the 
texture was not already dirty (this is unlikely under normal usage scenarios), 
the application needs to explicitly call IDirect3DVolumeTexture8::AddDirtyBox on
the volume texture.


Topic: D3DXLoadVolumeFromVolume
-------------------------------
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 D3DXLoadVolumeFromVolume is called and the 
surface was not already dirty (this is unlikely under normal usage scenarios), 
the application needs to explicitly call IDirect3DVolumeTexture8::AddDirtyBox on
the surface.


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


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


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


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


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