directx8_docs_readme.txt

VC下DirectX8的开发手册

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: Direct3DCubeTexture8.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: Direct3DCubeTexture8.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 
Direct3DDevice8.UpdateTexture for more information.


Topic: Direct3DDevice8.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 Direct3DDevice8.UpdateTexture and Direct3DTexture8.AddDirtyRect for
more details.


Topic: Direct3DDevice8.SetMaterial
----------------------------------
The Error Codes section is incorrect. The correct wording for 
this section is:

If the method fails, an error is raised and Err.Number can 
be set to D3DERR_INVALIDCALL. For information on trapping 
errors, see the Microsoft(r) Visual Basic(r) Error Handling topic.


Topic: Direct3DDevice8.UpdateTexture
--------------------------------------------------------------------------------
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: Direct3DSurface8.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 
Direct3DDevice8.UpdateTexture for more information.


Topic: Direct3DTexture8.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: Direct3DTexture8.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: Direct3DTexture8.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 
Direct3DDevice8.UpdateTexture for more information.


Topic: Direct3DVolume8.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: Direct3DVolume8.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 
Direct3DDevice8.UpdateTexture for more information.


Topic: Direct3DVolumeTexture8.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: Direct3DVolumeTexture8.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 
Direct3DDevice8.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 Input (C++)
===============================

---------------
Reference Topics
---------------


Topic: IDirectInput8::EnumDevices
----------------------------------
The declared type for the lpCallback parameter is incorrectly identified as LPDIENUMCALLBACK. It should be LPDIENUMDEVICESCALLBACK.


Topic: IDirectInput8::GetProperty
----------------------------------
The following additional properties have been added.

DIPROP_VIDPID 
Read-only device property that retrieves the vendor ID and product ID of a HID device. This property is of type DIPROPDWORD and contains both values. These two WORD values are combined in the    DIPROPDWORD.dwData field so the values should be extracted as follows:

        wVendorID  = LOWORD( DIPROPDWORD.dwData );
        wProductID = HIWORD( DIPROPDWORD.dwData );

This property applies to the entire device, rather than to any particular object, so the DIPROPHEADER.dwHow field must be DIPH_DEVICE.

DIPROP_TYPENAME
A predefined property which retrieves the type name of a device. For most game controllers this is the registry key name under REGSTR_PATH_JOYOEM from which static device settings may be retrieved, but predefined joystick types have special names consisting of a "#" character followed by a character dependent upon the type. This value may not be available for all devices. 

DIPROP_CALIBRATION 
A predefined property which allows the application to access the information that DirectInput uses to manipulate axes that require calibration. This property exists primarily for control panel-type applications. Normal applications should have no need to deal with calibration information.

You can access the calibration mode property for a particular axis by setting the DIPROPHEADER.dwHow field of the DIPROPHEADER structure to DIPH_BYID or to DIPH_BYOFFSET and setting the DIPROPHEADER.dwObj field to the object id or offset (respectively).

Control panel applications that set new calibration data must also invoke the IDirectInputJoyConfig::SendNotify method to notify other applications of the change in calibration.


Topic: IDirectInput8::SetProperty
----------------------------------
The following additional property has been added.

DIPROP_CALIBRATION 
A predefined property which allows the application to access the information that DirectInput uses to manipulate axes that require calibration. This property exists primarily for control panel-type applications. Normal applications should have no need to deal with calibration information.

You can access the calibration mode property for a particular axis by setting the DIPROPHEADER.dwHow field of the DIPROPHEADER structure to DIPH_BYID or to DIPH_BYOFFSET and setting the DIPROPHEADER.dwObj field to the object id or offset (respectively).

Control panel applications that set new calibration data must also invoke the IDirectInputJoyConfig::SendNotify method to notify other applications of the change in calibration.



DirectPlay
===========

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

Cancelling Outstanding Sends
----------------------------
  Applications should call CancelAsyncOperation to cancel all
  outstanding Sends prior to calling Close or doing a final 
  Release call on the IDirectPlay8Client, IDirectPlay8Server, or
  IDirectPlay8Peer interfaces.  Failing to do so will cause 
  unpredictable results.


Client-Server Sessions
----------------------
  When the server closes a session, it gets DPN_MSGID_DESTROY_PLAYER 
  for all connected players. Because the server knows that it
  is disconnecting, this is normal behavior, and the dwReason member 
  of the associated structure will be set to
  DPNDESTROYPLAYERREASON_NORMAL.The
  DPNDESTROYPLAYERREASON_SESSIONTERMINATED value is only set 
  for unexpected disconnections.


TCP/IP Port Settings
--------------------

  Application developers that choose to override the default DirectPlay
  8 dialog for TCP/IP are strongly urged to implement a solution that
  allows the user to override the port used for a connect or 
  enumeration.  One possible solution is to allow users to follow 
  the host name with colon and then the port, as implemented by the
  default DirectPlay 8 TCP/IP dialog (i.e. "host.domain.com:8090" ).
  Another possible solution would be to add another field to the UI
  that allows the user to enter a port.

Using the Netmon Parser
-----------------------
  To parse ports other than the default DirectPlay ports,
  create two new DWORD values under the
  HKEY_CURRENT_USER\Microsoft\DirectPlay\Parsers key
  
    MinUserPort=x
    MaxUserPort=y
  
  x and y define the range you want to parse in addition 
  to the default DirectPlay ports. They can be the same value if 
  you only need one custom port.

-----------------
Reference Topics
-----------------

Connect() methods
------------------
  After a call to Connect() succeeds, all outstanding Enumerations will 
  be canceled with the return of DPNERR_USERCANCEL.

SetApplicationDescription Methods
---------------------------------
  You cannot set the dwMaxPlayers parameter to a smaller value 
  than the current number of players in the session.


IDirectPlay8Peer::CancelAsyncOperation IDirectPlay8Client::CancelAsyncOperation
-----------------------------------------
  DPN_CANCELCONNECT and DPN_CANCELSEND should be DPNCANCEL_CONNECT
  and DPNCANCEL_SEND.




DirectShow
===========

-----------------
Reference Topics
-----------------

Media Locator
--------------

  The description of the SFN_VALIDATEF_USELOCAL flag is incorrect.  It 
  should read:

    Always use a local file, even if a version of the file exists 
    on the network.

  For more information, see IMediaLocator::FindMediaFile and 
  IRenderEngine::SetSourceNameValidation.

DV Muxer Filter
-----------------------
  The following sentence is incorrect:

	If no audio pins are connected, the filter produces 
    DV frames with no audio.
    
  It should read:
    If no audio pins are connected, the output 
    contains the audio data from the incoming DV frames.
    This might be silence, or valid audio data.

DirectX Media Objects
----------------------

  The descriptions of the IMediaObject::GetInputType and GetOutputType
  methods are incomplete.  They should include the following 
  information:

	The pmt parameter can be NULL.  In that case, the method 
        returns	S_OK if the type index is in range.  Otherwise, 
        it returns DMO_E_NO_MORE_ITEMS or another error code.



DirectShow (Visual Basic)
=========================

  DirectShow Visual Basic documentation is presently tied in closely 
  with the C++ documentation.  Information on DirectShow Visual 
  Basic programming, including use of DirectShow Editing 
  Services, is located exclusively in an appendix to the 
  C++ document.  There is no separate Visual Basic Documentation.

MSWebDVD
=========================
  The documentation states that you can change the size of the 
  video display through the methods GetClipVideoRect and 
  GetVideoSize.  This is incorrect. The size of the clipped 
  video rectangle is changed through the SetClipVideoRect 
  method. The size of the native video obviously cannot be modified.

CBaseInputPin
=========================
The reference documentation lists the following methods which must be overridden when implementing this class: BeginFlush, EndFlush, and Receive. Since CBaseInputPin derives from CBasePin, you must also override certain CBasePin methods as well, including CBasePin::CheckMediaTypes and CBasePin::GetMediaType. See the reference page for CBasePin for more details.