The following pseudocode example illustrates the version format encoded in the DriverVersion, DriverVersionLowPart, and DriverVersionHighPart members.

 Product = HIWORD(DriverVersion.HighPart)	
            Version = LOWORD(DriverVersion.HighPart)	
            SubVersion = HIWORD(DriverVersion.LowPart)	
            Build = LOWORD(DriverVersion.LowPart)	
            

See the Platform SDK for more information about the HIWORD macro, the LOWORD macro, and the structure.

MAX_DEVICE_IDENTIFIER_STRING is a constant with the following definition.

#define MAX_DEVICE_IDENTIFIER_STRING        512

The VendorId, DeviceId, SubSysId, and Revision members can be used in tandem to identify particular chip sets. However, use these members with caution.

Note??If an effect is created with , this method will return null references (in ) to the shader functions.

This method is used to get an element of a parameter that is an array.

Annotations are user-specific data that can be attached to any technique, pass, or parameter. See Handles (Direct3D 9).

This method can be used in place of nearly all the effect set API calls.

If the destination vector is smaller than the source vector, the additional components of the source vector will be ignored.

If the destination vector is larger than the source vector, only the initial components of the destination vector will be filled, and the remaining components will be set to zero.

If the destination vectors are smaller than the source vectors, the additional components of the source vectors will be ignored.

If the destination vectors are larger than the source vectors, only the initial components of each destination vector will be filled, and the remaining destination vector components will be set to zero.

A non-transposed matrix contains row-major data. In other words, each vector is contained in a row.

If the destination matrix is smaller than the source matrix, the additional components of the source matrix will be ignored.

A nontransposed matrix contains row-major data; that is, each vector is contained in a row.

If the destination matrix is larger than the source matrix, only the upper-left components of the destination matrix will be filled, and the remaining components will be set to zero.

A nontransposed matrix contains row-major data; that is, each vector is contained in a row.

If the destination matrices are smaller than the source matrices, the additional components of the source matrices will be ignored.

A nontransposed matrix contains row-major data; that is, each vector is contained in a row.

If the destination matrices are larger than the source matrices, only the upper-left components of each destination matrix will be filled, and the remaining destination matrix components will be set to zero.

A nontransposed matrix contains row-major data; that is, each vector is contained in a row.

If the destination matrices are smaller than the source matrices, the additional components of the source matrices will be ignored.

A nontransposed matrix contains row-major data; that is, each vector is contained in a row.

If the destination matrices are larger than the source matrices, only the upper-left components of each destination matrix will be filled, and the remaining destination matrix components will be set to zero.

A transposed matrix contains column-major data; that is, each vector is contained in a column.

If the destination matrix is smaller than the source matrix, the additional components of the source matrix will be ignored.

A transposed matrix contains column-major data; that is, each vector is contained in a column.

If the destination matrix is larger than the source matrix, only the upper-left elements of the destination matrix will be filled, and the remaining destination matrix components will be set to zero.

A transposed matrix contains column-major data; that is, each vector is contained in a column.

If the destination matrices are smaller than the source matrices, the additional components of the source matrices will be ignored.

A transposed matrix contains column-major data; that is, each vector is contained in a column.

If the destination matrices are larger than the source matrices, only the upper-left components of each destination matrix will be filled, and the remaining destination matrix components will be set to zero.

A transposed matrix contains column-major data; that is, each vector is contained in a column.

If the destination matrices are smaller than the source matrices, the additional components of the source matrices will be ignored.

A transposed matrix contains column-major data; that is, each vector is contained in a column.

If the destination matrices are larger than the source matrices, only the upper-left components of each destination matrix will be filled, and the remaining destination matrix components will be set to zero.

The interface assigned to a particular stage for a device is obtained by calling the GetTexture method.

The LPDIRECT3DBASETEXTURE9 and PDIRECT3DBASETEXTURE9 types are defined as references to the interface.

typedef struct  *LPDIRECT3DBASETEXTURE9, *PDIRECT3DBASETEXTURE9;

Warning??If you create a texture with to make that texture automatically generate sublevels, GetLevelCount always returns 1 for the number of levels.

This method applies to the following interfaces, which inherit from .

Changing the filter type "dirties" the mipmap sublevels and causes them to be regenerated.

The (default) filter type set at texture creation time is . If the driver doesn't support a linear filter, the filter type will be set to . All filter types supported by the driver for regular texture filtering are supported for autogeneration except . For each resource type, drivers should support all the filter types reported in the corresponding texture, CubeTexture, and volumetexture filter caps. For more information about texture types, see .

This method has no effect if the texture is not created with .

This method applies to the following interfaces, which inherit from .

SetLOD is used for level-of-detail control of managed textures. This method returns 0 on nonmanaged textures.

SetLOD communicates to the Direct3D texture manager the most detailed mipmap in the chain that should be loaded into local video memory. For example, in a five-level mipmap chain, setting LODNew to 2 indicates that the texture manager should load only mipmap levels 2 through 4 into local video memory at any given time.

More specifically, if the texture was created with the dimensions of 256x256, setting the most detailed level to 0 indicates that 256 x 256 is the largest mipmap available, setting the most detailed level to 1 indicates that 128 x 128 is the largest mipmap available, and so on, up to the most detailed mip level (the smallest texture size) for the chain.

Warning??If you create a texture with to make that texture automatically generate sublevels, GetLevelCount always returns 1 for the number of levels.

This method applies to the following interfaces, which inherit from .

Changing the filter type "dirties" the mipmap sublevels and causes them to be regenerated.

The (default) filter type set at texture creation time is . If the driver does not support a linear filter, the filter type will be set to . All filter types supported by the driver for regular texture filtering are supported for autogeneration except . SetAutoGenFilterType will fail unless the driver sets the appropriate D3DPTFILTERCAPS_MINFxxx caps. These values are specified in the TextureFilterCaps and/or CubeTextureFilterCaps members of . For more information about texture filter types, see .

This method has no effect if the texture is not created with . In this case, no failure is returned. For more information about usage constants, see .

Changing the filter type "dirties" the mipmap sublevels and causes them to be regenerated.

The (default) filter type set at texture creation time is . If the driver doesn't support a linear filter, the filter type will be set to . All filter types supported by the driver for regular texture filtering are supported for autogeneration except . For each resource type, drivers should support all the filter types reported in the corresponding texture, CubeTexture, and volumetexture filter caps. For more information about texture types, see .

This method has no effect if the texture is not created with .

An application can generate mipmap sublevels at any time by calling GenerateMipSubLevels. To have mipmap sublevels generated automatically at texture creation time (see Automatic Generation of Mipmaps (Direct3D 9)), specify during CreateTexture, CreateCubeTexture, and CreateVolumeTexture. For more information about usage constants, see .

The MaxTextureBlendStages and MaxSimultaneousTextures members might seem similar, but they contain different information. The MaxTextureBlendStages member contains the total number of texture-blending stages supported by the current device, and the MaxSimultaneousTextures member describes how many of those stages can have textures bound to them by using the SetTexture method.

When the driver fills this structure, it can set values for execute-buffer capabilities, even when the interface being used to retrieve the capabilities (such as ) does not support execute buffers.

In general, performance problems may occur if you use a texture and then modify it during a scene. Ensure that no texture used in the current BeginScene and EndScene block is evicted unless absolutely necessary. In the case of extremely high texture usage within a scene, the results are undefined. This occurs when you modify a texture that you have used in the scene and there is no spare texture memory available. For such systems, the contents of the z-buffer become invalid at EndScene. Applications should not call UpdateSurface to or from the back buffer on this type of hardware inside a BeginScene/EndScene pair. In addition, applications should not try to access the z-buffer if the capability flag is set. Finally, applications should not lock the back buffer or the z-buffer inside a BeginScene/EndScene pair.

The following flags concerning mipmapped textures are not supported in Direct3D 9.

• D3DPTFILTERCAPS_LINEAR
• D3DPTFILTERCAPS_LINEARMIPLINEAR
• D3DPTFILTERCAPS_LINEARMIPNEAREST
• D3DPTFILTERCAPS_MIPNEAREST
• D3DPTFILTERCAPS_NEAREST

The LPD3DXCONSTANTTABLE type is defined as a reference to the interface.

 typedef interface  ;	
            typedef interface  *LPD3DXCONSTANTTABLE;	
            

will sometimes return a with a Register_Count of 0. This will happen with a constant appears in more than one Register_Set but does not have space in that register set allocated.

Because a sampler can appear more than once in a constant table, this method can return an array of descriptions, each one with a different register index.

To get a constant from an array of constants, use .

To get a constant that is not part of an array, use or .

A nontransposed matrix contains row-major data; that is, each vector is contained in a row.

A transposed matrix contains column-major data; that is, each vector is contained in a column.

The interface can be obtained by calling the method or one of the xxx functions.

This interface inherits additional functionality from the interface.

This interface, like all COM interfaces, inherits additional functionality from the interface.

The LPDIRECT3DCUBETEXTURE9 and PDIRECT3DCubeTexture9 types are defined as references to the interface.

 typedef struct  *LPDIRECT3DCUBETEXTURE9, *PDIRECT3DCubeTexture9;	
            

The structure contains Width and Height members, which describe the size of one face in the cube. To get the size of the entire cube, multiply six (the number of cube faces) by the product of Width and Height.

Calling this method will increase the internal reference count on the interface. Failure to call IUnknown::Release when finished using this interface results in a memory leak.

For performance reasons, dirty regions are only recorded for level zero of a texture. Dirty regions are automatically recorded when is called without or . See for more information.

Cube textures created with are not lockable. Cube textures created in video memory are lockable when created with USAGE_DYNAMIC.

The only lockable format for a depth-stencil texture is .

For performance reasons, dirty regions are only recorded for level zero of a texture. For sublevels, it is assumed that the corresponding (scaled) rectangle or box is also dirty. Dirty regions are automatically recorded when is called without or . The destination surface of is also marked dirty automatically.

Using and explicitly specifying dirty regions can be used to increase the efficiency of . Using this method, applications can optimize what subset of a resource is copied by specifying dirty regions on the resource. However, the dirty regions may be expanded to optimize alignment.

The interface is obtained by calling the method.

This interface, like all COM interfaces, inherits the interface methods.

The LPDIRECT3DDEVICE9 and PDIRECT3DDEVICE9 types are defined as references to the interface.

 typedef struct  *LPDIRECT3DDEVICE9, *PDIRECT3DDEVICE9;	
            

Calling will increase the internal reference count on the interface. Failure to call IUnknown::Release when finished using this interface results in a memory leak.

retrieves the software vertex pipeline capabilities when the device is being used in software vertex processing mode.

You can query the AdapterOrdinal member of the returned structure to retrieve the ordinal of the adapter represented by this device.

Implicit swap chains are created by the device during . This method returns the number of swap chains created by CreateDevice.

An application may create additional swap chains using .

The GDI dialog boxes must be created as child to the device window. They should also be created within the same thread that created the device because this enables the parent window to manage redrawing the child window.

The method has no effect for windowed mode applications, but this setting will be respected if the application resets the device into full-screen mode. If SetDialogBoxMode succeeds in a windowed mode application, any subsequent reset to full-screen mode will be checked against the restrictions listed above. Also, SetDialogBoxMode causes all back buffers on the swap chain to be discarded, so an application is expected to refresh its content for all back buffers after this call.

Calling this method will increase the internal reference count on the interface. Failure to call IUnknown::Release when finished using this interface results in a memory leak.

Typically, methods that return state will not work on a device that is created using . This method however, will work even on a pure device.

This method will not return device state for a device that is created using . If you want to use this method, you must create your device with any of the other values in .

When clipping is enabled during vertex processing (by , , or other drawing functions), Direct3D computes a clip code for every vertex. The clip code is a combination of D3DCS_* bits. When a vertex is outside a particular clipping plane, the corresponding bit is set in the clipping code. Direct3D maintains the clip status using , which has ClipUnion and ClipIntersection members. ClipUnion is a bitwise "OR" of all vertex clip codes and ClipIntersection is a bitwise "AND" of all vertex clip codes. Initial values are zero for ClipUnion and 0xFFFFFFFF for ClipIntersection. When is set to , ClipUnion and ClipIntersection are set to zero. Direct3D updates the clip status during drawing calls. To compute clip status for a particular object, set ClipUnion and ClipIntersection to their initial value and continue drawing.

Clip status is not updated by and because there is no software emulation for them.

Clip status is used during software vertex processing. Therefore, this method is not supported on pure or nonpure hardware processing devices. For more information about pure devices, see .

The scissor rectangle is used as a rectangular clipping region.

See Rectangles (Direct3D 9) for further information on the use of rectangles in DirectX.

An application can create a mixed-mode device to use both the software vertex processing and the hardware vertex processing. To switch between the two vertex processing modes in DirectX 8.x, use with the render state D3DRS_SOFTWAREVERTEXPROCESSING and the appropriate argument. The drawback of the render state approach was the difficulty in defining the semantics for state blocks. Applications and the runtime had to do extra work and be careful while recording and playing back state blocks.

In Direct3D 9, use instead. This new API is not recorded by StateBlocks.

The fixed vertex function declaration is a set of FVF flags that determine how vertices processed by the fixed function pipeline will be used.

Typically, methods that return state will not work on a device that is created using . This method however, will work even on a pure device because it returns an interface.

Calling this method will increase the internal reference count on the interface. Failure to call IUnknown::Release when finished using this interface results in a memory leak.

This method will not work on a device that is created using .

If the device is lost but cannot be restored at the current time, returns the return code. This would be the case, for example, when a full-screen device has lost focus. If an application detects a lost device, it should pause and periodically call until it receives a return value of . The application may then attempt to reset the device by calling and, if this succeeds, restore the necessary resources and resume normal operation. Note that will return if the device is either "lost" or "not reset".

A call to will fail if called on a different thread than that used to create the device being reset.

The returned value is rounded to the nearest MB. This is done to reflect the fact that video memory estimates are never precise due to alignment and other issues that affect consumption by certain resources. Applications can use this value to make gross estimates of memory availability to make large-scale resource decisions such as how many levels of a mipmap to attempt to allocate, but applications cannot use this value to make small-scale decisions such as if there is enough memory left to allocate another resource.

This function causes only the copy of resources to be evicted. The resource copy in system memory is retained. See .

Calling will increase the internal reference count on the interface. Failure to call IUnknown::Release when finished using this interface results in a memory leak.

retrieves the software vertex pipeline capabilities when the device is being used in software vertex processing mode.

You can query the AdapterOrdinal member of the returned structure to retrieve the ordinal of the adapter represented by this device.

An operating system cursor is created and used under either of these conditions:

• The hardware has set (see ), and the cursor size is 32x32 (which is the cursor size in the operating system).
• The application is running in windowed mode.

Otherwise, DirectX uses an emulated cursor. An application uses to move an emulated cursor to follow mouse movement.

It is recommended for applications to always trap WM_MOUSEMOVE events and call DXSetCursorPosition.

Direct3D cursor functions use either GDI cursor or software emulation, depending on the hardware. Users typically want to respond to a WM_SETCURSOR message. For example, they might want to write the message handler as follows:

 case WM_SETCURSOR:	
            // Turn off window cursor. 	
            SetCursor( null );	
            m_pd3dDevice->ShowCursor( TRUE );	
            return TRUE; // Prevent Windows from setting cursor to window class cursor.	
            break;	
            

Or, users might want to call the method if they want to change the cursor.

The application can determine what hardware support is available for cursors by examining appropriate members of the structure. Typically, hardware supports only 32x32 cursors and, when windowed, the system might support only 32x32 cursors. In this case, still succeeds but the cursor might be reduced to that size. The hot spot is scaled appropriately.

The cursor does not survive when the device is lost. This method must be called after the device is reset.

When running in full-screen mode, screen space coordinates are the back buffer coordinates appropriately scaled to the current display mode. When running in windowed mode, screen space coordinates are the desktop coordinates. The cursor image is drawn at the specified position minus the hotspot-offset specified by the SetCursorProperties method.

If the cursor has been hidden by ShowCursor, the cursor is not drawn.

Direct3D cursor functions use either GDI cursor or software emulation, depending on the hardware. Users usually want to respond to a WM_SETCURSOR message. For example, the users might want to write the message handler like this:

 case WM_SETCURSOR: // Turn off window cursor  SetCursor( null ); m_pd3dDevice->ShowCursor( TRUE ); return TRUE; // prevent Windows from setting cursor to window class cursor break;	
            

Or users might want to call the method if they want to change the cursor. See the code in the DirectX Graphics C/C++ Samples for more detail.

There is always at least one swap chain (the implicit swap chain) for each device because Direct3D 9 has one swap chain as a property of the device.

Note that any given device can support only one full-screen swap chain.

can be specified for the windowed mode back buffer format when calling , and CreateAdditionalSwapChain. This means the application does not have to query the current desktop format before calling CreateDevice for windowed mode. For full-screen mode, the back buffer format must be specified.

Implicit swap chains are created by the device during . This method returns the number of swap chains created by CreateDevice.

An application may create additional swap chains using .

If a call to fails, the device will be placed in the "lost" state (as indicated by a return value of from a call to ) unless it is already in the "not reset" state (as indicated by a return value of from a call to ). Refer to and Lost Devices (Direct3D 9) for further information concerning the use of in the context of lost devices.

Calling causes all texture memory surfaces to be lost, managed textures to be flushed from video memory, and all state information to be lost. Before calling the method for a device, an application should release any explicit render targets, depth stencil surfaces, additional swap chains, state blocks, and resources associated with the device.

There are two different types of swap chains: full-screen or windowed. If the new swap chain is full-screen, the adapter will be placed in the display mode that matches the new size.

Direct3D 9 applications can expect messages to be sent to them during this call (for example, before this call is returned); applications should take precautions not to call into Direct3D at this time. In addition, when fails, the only valid methods that can be called are , , and the various Release member functions. Calling any other method can result in an exception.

A call to will fail if called on a different thread than that used to create the device being reset.

Pixel shaders and vertex shaders survive calls for Direct3D 9. They do not need to be re-created explicitly by the application.

can be specified for the windowed mode back buffer format when calling , , and . This means the application does not have to query the current desktop format before calling for windowed mode. For full-screen mode, the back buffer format must be specified. Setting BackBufferCount equal to zero (BackBufferCount = 0) results in one back buffer.

When trying to reset more than one display adapter in a group, set pPresentationParameters to point to an array of structures, one for each display in the adapter group.

If a multihead device was created with , requires an array of structures wherein each structure must specify a full-screen display. To switch back to windowed mode, the application must destroy the device and re-create a non-multihead device in windowed mode.

If necessary, a stretch operation is applied to transfer the pixels within the source rectangle to the destination rectangle in the client area of the target window.

Present will fail, returning , if called between BeginScene and EndScene pairs unless the render target is not the current render target (such as the back buffer you get from creating an additional swap chain). This is a new behavior for Direct3D 9.

Calling this method will increase the internal reference count on the interface. Failure to call IUnknown::Release when finished using this interface results in a memory leak.

The GDI dialog boxes must be created as child to the device window. They should also be created within the same thread that created the device because this enables the parent window to manage redrawing the child window.

The method has no effect for windowed mode applications, but this setting will be respected if the application resets the device into full-screen mode. If SetDialogBoxMode succeeds in a windowed mode application, any subsequent reset to full-screen mode will be checked against the restrictions listed above. Also, SetDialogBoxMode causes all back buffers on the swap chain to be discarded, so an application is expected to refresh its content for all back buffers after this call.

There is always at least one swap chain (the implicit swap chain) for each device, because Direct3D 9 has one swap chain as a property of the device. The gamma ramp takes effect immediately; there is no wait for a vertical sync.

If the device does not support gamma ramps in the swap chain's current presentation mode (full-screen or windowed), no error return is given. Applications can check the and capability bits in the Caps2 member of the structure to determine the capabilities of the device and whether a calibrator is installed.

For windowed gamma correction presentation, use if the hardware supports the feature. In DirectX 8, SetGammaRamp will set the gamma ramp only on a full-screen mode application. For more information about gamma correction, see Gamma (Direct3D 9).

An application can discover support for Automatic Generation of Mipmaps (Direct3D 9) in a particular format by calling with . If returns , will succeed but it will return a one-level texture.

In Windows Vista CreateTexture can create a texture from a system memory reference allowing the application more flexibility over the use, allocation and deletion of the system memory. For example, an application could pass a GDI system memory bitmap reference and get a Direct3D texture interface around it. Using a system memory reference with CreateTexture has the following restrictions.

• The pitch of the texture must be equal to the width multiplied by the number of bytes per pixel.
• Only textures with a single mipmap level are supported. The Levels argument must be 1.
• The Pool argument must be .
• The pSharedHandle argument must be a valid reference to a buffer that can hold the system memory point; *pSharedHandle must be a valid reference to system memory with a size in bytes of texture width * texture height * bytes per pixel of the texture format.

A mipmap (texture) is a collection of successively downsampled (mipmapped) surfaces. On the other hand, a cube texture (created by ) is a collection of six textures (mipmaps), one for each face. All faces must be present in the cube texture. Also, a cube map surface must be the same pixel size in all three dimensions (x, y, and z).

An application can discover support for Automatic Generation of Mipmaps (Direct3D 9) in a particular format by calling with . If returns , will succeed but it will return a one-level texture.

A vertex buffer can be used with either hardware or software vertex processing. This is determined by how the device and the vertex buffer are created.

When a device is created, CreateDevice uses the behavior flag to determine whether to process vertices in hardware or software. There are three possibilities:

• Process vertices in hardware by setting .
• Process vertices in software by setting .
• Process vertices in either hardware or software by setting .

Mixed-mode devices might need to switch between software and hardware processing (using ) after the device is created.

When a vertex buffer is created, CreateVertexBuffer uses the usage parameter to decide whether to process vertices in hardware or software.

• If CreateDevice uses , CreateVertexBuffer must use 0.
• If CreateDevice uses , CreateVertexBuffer must use either 0 or . For either value, vertices will be processed in software.
• If CreateDevice uses , CreateVertexBuffer can use either 0 or .

To use a vertex buffer with a mixed mode device, create a single vertex buffer which can be used for both hardware or software processing. Use to set the current vertex buffer and use , if necessary, to change the device behavior to match. It is recommended that the vertex buffer usage matches the device behavior. Note that a vertex buffer created for software processing cannot be located in video memory.

The interface supports rendering of primitives using vertex data stored in vertex buffer objects. Vertex buffers are created from the , and are usable only with the object from which they are created.

When set to a nonzero value, which must be a valid FVF code, the FVF parameter indicates that the buffer content is to be characterized by an FVF code. A vertex buffer that is created with an FVF code is referred to as an FVF vertex buffer. For more information, see FVF Vertex Buffers (Direct3D 9).

Non-FVF buffers can be used to interleave data during multipass rendering or multitexture rendering in a single pass. To do this, one buffer contains geometry data and the others contain texture coordinates for each texture to be rendered. When rendering, the buffer containing the geometry data is interleaved with each of the buffers containing the texture coordinates. If FVF buffers were used instead, each of them would need to contain identical geometry data in addition to the texture coordinate data specific to each texture rendered. This would result in either a speed or memory penalty, depending on the strategy used. For more information about texture coordinates, see Texture Coordinates (Direct3D 9).

Index buffers are memory resources used to hold indices, they are similar to both surfaces and vertex buffers. The use of index buffers enables Direct3D to avoid unnecessary data copying and to place the buffer in the optimal memory type for the expected usage.

To use index buffers, create an index buffer, lock it, fill it with indices, unlock it, pass it to , set up the vertices, set up the vertex shader, and call for rendering.

The MaxVertexIndex member of the structure indicates the types of index buffers that are valid for rendering.

Render-target surfaces are placed in the memory class.

The creation of lockable, multisampled render targets is not supported.

The memory class of the depth-stencil buffer is always .

This method is similar to CopyRects in DirectX 8.

This function has the following restrictions.

• The source surface must have been created with .
• The destination surface must have been created with .
• Neither surface can be locked or holding an outstanding device context.
• Neither surface can be created with multisampling. The only valid flag for both surfaces is .
• The surface format cannot be a depth stencil format.
• The source and dest rects must fit within the surface.
• No stretching or shrinking is allowed (the rects must be the same size).
• The source format must match the dest format.

The following table shows the supported combinations.

?

* If the driver does not support the requested copy, it will be emulated using lock and copy.

If the application needs to copy data from a render target to a surface, it can use GetRenderTargetData.

You can dirty a portion of a texture by locking it, or by calling one of the following methods.

retrieves the dirty portions of the texture by calculating what has been accumulated since the last update operation.

For performance reasons, dirty regions are only recorded for level zero of a texture. For sublevels, it is assumed that the corresponding (scaled) rectangle or box is also dirty. Dirty regions are automatically recorded when LockRect or is called without or . Also, the destination surface of is marked dirty.

This method fails if the textures are of different types, if their bottom-level buffers are of different sizes, or if their matching levels do not match. For example, consider a six-level source texture with the following dimensions.

 32x16, 16x8, 8x4, 4x2, 2x1, 1x1	
            

This six-level source texture could be the source for the following one-level destination.

 1x1	
            

For the following two-level destination.

 2x1, 1x1	
            

Or, for the following three-level destination.

 4x2, 2x1, 1x1	
            

In addition, this method will fail if the textures are of different formats. If the destination texture has fewer levels than the source, only the matching levels are copied. If the source texture has fewer levels than the destination, the method will fail.

If the source texture has dirty regions, the copy can be optimized by restricting the copy to only those regions. It is not guaranteed that only those bytes marked dirty will be copied.

Here are the possibilities for source and destination surface combinations:

• If pSourceTexture is a non-autogenerated mipmap and pDestinationTexture is an autogenerated mipmap, only the topmost matching level is updated, and the destination sublevels are regenerated. All other source sublevels are ignored.
• If both pSourceTexture and pDestinationTexture are autogenerated mipmaps, only the topmost matching level is updated. The sublevels from the source are ignored and the destination sublevels are regenerated.
• If pSourceTexture is an autogenerated mipmap and pDestinationTexture a non-autogenerated mipmap, UpdateTexture will fail.

The destination surface must be either an off-screen plain surface or a level of a texture (mipmap or cube texture) created with .

The source surface must be a regular render target or a level of a render-target texture (mipmap or cube texture) created with POOL_DEFAULT.

This method will fail if:

• The render target is multisampled.
• The source render target is a different size than the destination surface.
• The source render target and destination surface formats do not match.

The buffer pointed to by pDestSurface will be filled with a representation of the front buffer, converted to the standard 32 bits per pixel format .

This method is the only way to capture an antialiased screen shot.

This function is very slow, by design, and should not be used in any performance-critical path.

For more information, see Lost Devices and Retrieved Data.

StretchRect Restrictions

• Driver support varies. See the section on driver support (below) to see which drivers support which source and destination formats.
• The source and destination surfaces must be created in the default memory pool.
• If filtering is specified, you must set the appropriate filter caps (see StretchRectFilterCaps in ).
• Stretching is not supported between source and destination rectangles on the same surface.
• Stretching is not supported if the destination surface is an off-screen plain surface but the source is not.
• You many not stretch between source and destination rectangles if either surface is in a compressed format (see Using Compressed Textures (Direct3D 9)).
• Stretching supports color-space conversion from YUV to high-precision RGBA only. Since color conversion support is not supported by software emulation, use to test the hardware for color conversion support.
• If the source or destination surface is a texture surface (or a cube texture surface), you must use a Direct3D 9 driver that supports (see ).

Additional Restrictions for Depth and Stencil Surfaces

• The source and destination surfaces must be plain depth stencil surfaces (not textures) (see ).
• Neither of the surfaces can be discardable.
• The entire surface must be copied (that is: sub-rectangle copies are not allowed).
• Format conversion, stretching, and shrinking are not supported.
• StretchRect cannot be called inside of a BeginScene/EndScene pair.

Using StretchRect to downsample a Multisample Rendertarget

You can use StretchRect to copy from one rendertarget to another. If the source rendertarget is multisampled, this results in downsampling the source rendertarget. For instance you could:

• Create a multisampled rendertarget.
• Create a second rendertarget of the same size, that is not multisampled.
• Copy (using StretchRect the multisample rendertarget to the second rendertarget.

Note that use of the extra surface involved in using StretchRect to downsample a Multisample Rendertarget will result in a performance hit.

Driver Support

There are many restrictions as to which surface combinations are valid for StretchRect. Factors include whether the driver is a Direct3D 9 driver or older, and whether the operation will result in stretching/shrinking. Since applications are not expected to recognize if the driver is a Direct3D 9 driver or not, the runtime will automatically set a new cap, cap (see ), for Direct3D 9-level drivers and above.

?

?

?

?

This method can only be applied to a render target, a render-target texture surface, or an off-screen plain surface with a pool type of .

will work with all formats. However, when using a reference or software device, the only formats supported are , , , , , , , , , , , , , , and .

When using a DirectX 7 or DirectX 8.x driver, the only YUV formats supported are and .

will return a surface that has identical characteristics to a surface created by the DirectX 8.x method CreateImageSurface.

is the appropriate pool for use with the and .

is not allowed when creating an offscreen plain surface. For more information about memory pools, see .

Off-screen plain surfaces are always lockable, regardless of their pool types.

The device can support multiple render targets. The number of render targets supported by a device is contained in the NumSimultaneousRTs member of . See Multiple Render Targets (Direct3D 9).

Setting a new render target will cause the viewport (see Viewports and Clipping (Direct3D 9)) to be set to the full size of the new render target.

Some hardware tests the compatibility of the depth stencil buffer with the color buffer. If this is done, it is only done in a debug build.

Restrictions for using this method include the following:

• The multisample type must be the same for the render target and the depth stencil surface.
• The formats must be compatible for the render target and the depth stencil surface. See .
• The size of the depth stencil surface must be greater than or equal to the size of the render target.

These restrictions are validated only when using the debug runtime when any of the Draw methods are called.

Cube textures differ from other surfaces in that they are collections of surfaces. To call with a cube texture, you must select an individual face using and pass the resulting surface to .

Typically, methods that return state will not work on a device that is created using . This method however, will work even on a pure device because it returns an interface.

The device can now support multiple render targets. The number of render targets supported by a device is contained in the NumSimultaneousRTs member of . See Multiple Render Targets (Direct3D 9).

Calling this method will increase the internal reference count on the interface. Failure to call IUnknown::Release when finished using the interface results in a memory leak.

Restrictions for using this method include the following:

• The multisample type must be the same for the render target and the depth stencil surface.
• The formats must be compatible for the render target and the depth stencil surface. See .
• The size of the depth stencil surface must be greater than or equal to the size of the render target.

These restrictions are validated only when using the debug runtime when any of the Draw methods are called.

Cube textures differ from other surfaces in that they are collections of surfaces. To call with a cube texture, you must select an individual face using and pass the resulting surface to .

Calling this method will increase the internal reference count on the interface. Failure to call IUnknown::Release when finished using this interface results in a memory leak.

Applications must call before performing any rendering and must call when rendering is complete and before calling again.

If fails, the device was unable to begin the scene, and there is no need to call . In fact, calls to will fail if the previous failed. This applies to any application that creates multiple swap chains.

There should be one / pair between any successive calls to present (either or ). should be called once before any rendering is performed, and should be called once after all rendering for a frame has been submitted to the runtime. Multiple non-nested / pairs between calls to present are legal, but having more than one pair may incur a performance hit. To enable maximal parallelism between the CPU and the graphics accelerator, it is advantageous to call as far ahead of calling present as possible.

When this method succeeds, the scene has been queued up for rendering by the driver. This is not a synchronous method, so the scene is not guaranteed to have completed rendering when this method returns.

Applications must call before performing any rendering and must call when rendering is complete and before calling again.

If fails, the device was unable to begin the scene, and there is no need to call . In fact, calls to will fail if the previous failed. This applies to any application that creates multiple swap chains.

There should be at most one / pair between any successive calls to present (either or ). should be called once before any rendering is performed, and should be called once after all rendering for a frame has been submitted to the runtime. To enable maximal parallelism between the CPU and the graphics accelerator, it is advantageous to call as far ahead of calling present as possible.

Use this method to clear a surface including: a render target, all render targets in an MRT, a stencil buffer, or a depth buffer. Flags determines how many surfaces are cleared. Use pRects to clear a subset of a surface defined by an array of rectangles.

will fail if you:

• Try to clear either the depth buffer or the stencil buffer of a render target that does not have an attached depth buffer.
• Try to clear the stencil buffer when the depth buffer does not contain stencil data.

This method will not return device state for a device that is created using . If you want to use this method, you must create your device with any of the other flag values in .

The multiplication order is pMatrix times State.

An application might use the method to work with hierarchies of transformations. For example, the geometry and transformations describing an arm might be arranged in the following hierarchy.

 shoulder_transformation upper_arm geometry elbow transformation lower_arm geometry wrist transformation hand geometry	
            

An application might use the following series of calls to render this hierarchy. Not all the parameters are shown in this pseudocode.

 (D3DTS_WORLDMATRIX(0),  shoulder_transform)	
            (upper_arm)	
            (D3DTS_WORLDMATRIX(0),  elbow_transform)	
            (lower_arm)	
            (D3DTS_WORLDMATRIX(0),  wrist_transform)	
            (hand)

Direct3D sets the following default values for the viewport.

  vp;	
            vp.X      = 0;	
            vp.Y      = 0;	
            vp.Width  = RenderTarget.Width;	
            vp.Height = RenderTarget.Height;	
            vp.MinZ   = 0.0f;	
            vp.MaxZ   = 1.0f;	
            

can be used to draw on part of the screen. Make sure to call it before any geometry is drawn so the viewport settings will take effect.

To draw multiple views within a scene, repeat the and draw geometry sequence for each view.

Typically, methods that return state will not work on a device that is created using . This method however, will work even on a pure device.

This method will not return device state for a device that is created using . If you want to use this method, you must create your device with any of the other values in .

Set light properties by preparing a structure and then calling the method. The method accepts the index at which the device should place the set of light properties to its internal list of light properties, and the address of a prepared structure that defines those properties. You can call with new information as needed to update the light's illumination properties.

The system allocates memory to accommodate a set of lighting properties each time you call the method with an index that has never been assigned properties. Applications can set a number of lights, with only a subset of the assigned lights enabled at a time. Check the MaxActiveLights member of the structure when you retrieve device capabilities to determine the maximum number of active lights supported by that device. If you no longer need a light, you can disable it or overwrite it with a new set of light properties.

The following example prepares and sets properties for a white point-light whose emitted light will not attenuate over distance.

 // Assume d3dDevice is a valid reference to an  interface.	
             d3dLight;	
               hr; // Initialize the structure.	
            ZeroMemory(&d3dLight, sizeof(d3dLight)); // Set up a white point light.	
            d3dLight.Type = ;	
            d3dLight.Diffuse.r  = 1.0f;	
            d3dLight.Diffuse.g  = 1.0f;	
            d3dLight.Diffuse.b  = 1.0f;	
            d3dLight.Ambient.r  = 1.0f;	
            d3dLight.Ambient.g  = 1.0f;	
            d3dLight.Ambient.b  = 1.0f;	
            d3dLight.Specular.r = 1.0f;	
            d3dLight.Specular.g = 1.0f;	
            d3dLight.Specular.b = 1.0f; // Position it high in the scene and behind the user.	
            // Remember, these coordinates are in world space, so	
            // the user could be anywhere in world space, too. 	
            // For the purposes of this example, assume the user	
            // is at the origin of world space.	
            d3dLight.Position.x = 0.0f;	
            d3dLight.Position.y = 1000.0f;	
            d3dLight.Position.z = -100.0f; // Don't attenuate.	
            d3dLight.Attenuation0 = 1.0f; 	
            d3dLight.Range        = 1000.0f; // Set the property information for the first light.	
            hr = d3dDevice->SetLight(0, &d3dLight);	
            if (SUCCEEDED(hr)) // Handle Success	
            else // Handle failure	
            

Enable a light source by calling the method for the device.